MCP Sound Tool
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.
Features
- 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
Installation
Python Version Compatibility
This package is tested with Python 3.8-3.11. If you encounter errors with Python 3.12+ (particularly BrokenResourceError
or TaskGroup
exceptions), please try using an earlier Python version.
Recommended: Install with pipx
The recommended way to install mcp-sound-tool is with pipx, which installs the package in an isolated environment while making the commands available globally:
This method ensures that the tool has its own isolated environment, avoiding conflicts with other packages.
Alternative: Install with pip
You can also install directly with pip:
From Source
- Clone this repository:Copy
- Install with pipx directly from the source directory:Or with pip:CopyCopy
Usage
Adding Sound Files
Place your sound files in the sounds
directory. The following sound files are expected:
completion.mp3
- Played after code generationerror.mp3
- Played when an error occursnotification.mp3
- Used for general notifications
You can find free sound effects on websites like freesound.org.
Running the MCP Server
Run the MCP server:
The server will start and listen for events from Cursor or other MCP-compatible clients through the stdio transport.
Configuration in Cursor
To use this server with Cursor, add it to your MCP configuration file:
On macOS:
On Windows:
When installed with pipx
, the mcp-sound-tool
command 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.
When to Use Sound Feedback
AI agents should use the sound tools proactively at appropriate moments:
- Success Sounds (
completion
):- After a task or command has successfully completed
- When a significant operation has finished successfully
- When confirming a user's request has been fulfilled
- Error Sounds (
error
):- 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
- Notification Sounds (
notification
):- When alerting the user to important information
- When prompting for user attention or input
- For status updates on long-running operations
Example Usage
Available Tools
play_sound(sound_type="completion", custom_sound_path=None)
: Play a sound effectlist_available_sounds()
: List all available sound filesinstall_to_user_dir()
: Install sound files to user's config directory
For more details, connect to the MCP server and check the tool descriptions.
Development
For development:
Acknowledgments
- SIAM-TheLegend for creating the original sound-mcp JavaScript 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
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
A Model Context Protocol implementation that plays sound effects (completion, error, notification) for Cursor AI and other MCP-compatible environments, providing audio feedback for a more interactive coding experience.
Related MCP Servers
- -securityFlicense-qualityProvides audio feedback by playing sound effects when Cursor AI completes code generation, creating a more interactive coding experience.Last updated -15TypeScript
- AsecurityFlicenseAqualityA lightweight Model Context Protocol server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.Last updated -1249TypeScript
- -securityFlicense-qualityAn MCP server that plays notification sounds when AI coding assistants like Windsurf or Cursor require user attention, such as when coding is complete or when user approval is needed.Last updated -1241TypeScript
- -securityAlicense-qualityA Model Context Protocol server that allows AI assistants like Claude and Cursor to create music and control Sonic Pi programmatically through OSC messages.Last updated -JavaScriptMIT License