Sound Effects

🚀 MCP Sound Tool

This is an implementation of the Model Context Protocol (MCP) for playing sound effects in Cursor AI and other MCP-compatible environments. This Python implementation provides audio feedback for a more interactive coding experience.

🚀 Quick Start

The MCP Sound Tool is a Python implementation designed to play sound effects in Cursor AI and other MCP-compatible environments, offering audio feedback for a more engaging coding experience.

✨ Features

• Play sound effects for various events (completion, error, notification).
• Use the Model Context Protocol (MCP) for standardized integration.
• Support cross-platform (Windows, macOS, Linux).
• Configurable sound effects.

📦 Installation

Python Version Compatibility

This package has been tested to support Python 3.8 - 3.11. If you encounter errors (especially BrokenResourceError or TaskGroup exceptions) when using Python 3.12+, please try using an earlier Python version.

Recommended: Install with pipx

It is recommended to use pipx for installation. It installs the package in an isolated environment and adds the command to the global PATH:

# First, install pipx (if not already installed)
python -m pip install --user pipx
python -m pipx ensurepath

# Install mcp-sound-tool
pipx install mcp-sound-tool

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 using pip:

pip install mcp-sound-tool

Install from Source Code

If you have the source code, you can install it like this:

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

💻 Usage Examples

Add Sound Files

Place sound files in the following paths:

• Windows: %APPDATA%\mcp-sound-tool\resources\sounds
• macOS: ~/Library/Application Support/mcp-sound-tool/resources/sounds
• Linux: ~/.config/mcp-sound-tool/resources/sounds

Run the MCP Server

Run the following command in the terminal or command prompt to start the MCP server:

mcp-sound-server

By default, the server will run on port 5005.

Configure in Cursor

Edit your configuration file (usually ~/.config/cursor/settings.json) and add the following to the plugins section:

{
  "plugins": {
    "mcp-sound": true
  }
}

Then restart Cursor.

Sound MCP Usage Guide: AI Model

Define Sound Event Types

1. Completion Sound: Play a sound when an operation is completed.
2. Error Sound: Play a sound when an error is detected.
3. Notification Sound: Play a sound when user attention is required.

Configuration Example

Edit your configuration file (usually ~/.config/mcp-sound_TOOL/config.json) and add the following:

{
  "sounds": {
    "completion": "assets/complete.mp3",
    "error": "assets/error.mp3",
    "notification": "assets/notification.mp3"
  }
}

Then restart the MCP service.

🔧 Technical Details

Install Development Dependencies

Run the following command in the terminal or command prompt to install development dependencies:

pip install -e ".[dev]"

Run Tests

Run the following command to execute tests:

pytest tests/

🤝 Acknowledgments

• SIAM-TheLegend created the original sound-mcp JavaScript implementation, which inspired this Python version.
• The MCP protocol developers created a powerful standard for AI tool interaction.
• Contributors who contributed to testing and documentation.

📄 License

This project is released under the MIT License. Please refer to the LICENSE file for the specific license content.