MCP Sound Tool

A sound tool for MCP-compatible IDEs like Cursor. Plays sounds for events like completion, error, and notification.

A Model Context Protocol (MCP) implementation that plays sound effects for Cursor AI and other MCP-compatible environments. This Python implementation provides audio feedback for a more interactive coding experience.

- Plays sound effects for various events (completion, error, notification)
- Uses the Model Context Protocol (MCP) for standardized integration with Cursor and other IDEs
- Cross-platform support (Windows, macOS, Linux)
- Configurable sound effects

This package is tested with Python 3.8-3.11. If you encounter errors with Python 3.12+ (particularlyBrokenResourceErrororTaskGroupexceptions), please try using an earlier Python version.

The recommended way to install mcp-sound-tool is withpipx, which installs the package in an isolated environment while making the commands available globally:

# Install pipx if you don't have it python -m pip install --user pipx python -m pipx ensurepath # Install mcp-sound-tool pipx install mcp-sound-tool

git clone https://github.com/yourusername/mcp-sound-tool cd mcp-sound-tool

// ~/Library/Application Support/Cursor/mcp.json { "mcpServers": { "sound": { "command": "mcp-sound-tool", "args": [], "type": "stdio", "pollingInterval": 5000, "startupTimeout": 10000, "restartOnFailure": true } } }

// %APPDATA%/Cursor/mcp.json { "mcpServers": { "sound": { "command": "mcp-sound-tool", "args": [], "type": "stdio", "pollingInterval": 5000, "startupTimeout": 10000, "restartOnFailure": true } } }

When installed withpipx, themcp-sound-toolcommand will be available in your PATH, so Cursor will be able to find and execute it without specifying the full path.

Sound MCP Usage Guidelines for AI Models

This MCP server provides audio feedback capabilities for AI interactions. It's designed to enhance the user experience by providing clear audio cues that indicate the status of operations without requiring the user to read text.

AI agents should use the sound tools proactively at appropriate moments:

- After a task or command has successfully completed
- When a significant operation has finished successfully
- When confirming a user's request has been fulfilled

- When a command has failed or encountered an error
- When warning the user about a problem
- When an operation couldn't be completed as requested

- When alerting the user to important information
- When prompting for user attention or input
- For status updates on long-running operations

# When a command completes successfully @mcp.tool() def execute_command(command): result = run_command(command) if result.success: play_sound("completion") # Indicate success with audio return "Command executed successfully" else: play_sound("error") # Indicate failure with audio return f"Error: {result.error_message}"

- play_sound(sound_type="completion", custom_sound_path=None): Play a sound effect
- list_available_sounds(): List all available sound files
- install_to_user_dir(): Install sound files to user's config directory

For more details, connect to the MCP server and check the tool descriptions.

# Install development dependencies pip install -e ".[dev]" # Run tests pytest

- SIAM-TheLegendfor creating the originalsound-mcpJavaScript implementation that inspired this Python version
- The MCP protocol developers for creating a powerful standard for AI tool interactions
- Contributors to the testing and documentation

Cinema-grade video production MCP server — 8 tools for recording, editing, effects, captions, TTS, and smart screenshots. Built on ffmpeg + Playwright.