MCP Make Sound

# 🔊 MCP Make Sound A Model Context Protocol (MCP) server that provides comprehensive sound playback capabilities for macOS. This server allows AI assistants and other MCP clients to play system sounds, text-to-speech, and custom audio files for rich audio feedback. <a href="https://glama.ai/mcp/servers/@nocoo/mcp-make-sound"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@nocoo/mcp-make-sound/badge" alt="Make Sound MCP server" /> </a> ## ✨ Features - **🔔 Simple Sound Methods**: Pre-configured info, warning, and error sounds - **🎵 Custom System Sounds**: Play any of the 14 built-in macOS sounds - **🗣️ Text-to-Speech**: Convert text to speech with customizable voices - **📁 File Playback**: Play custom audio files from disk - 🚀 Built with TypeScript and the MCP SDK - 🪶 Lightweight and easy to integrate ## 📋 Requirements - 🍎 macOS (uses `afplay` and system sounds) - 🟢 Node.js 18+ - 📝 TypeScript ## 🚀 Installation 1. Clone this repository: ```bash git clone <repository-url> cd mcp-make-sound ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ## 💡 Usage ### 🎵 Running the Server Start the MCP server: ```bash npm start ``` For development with auto-reload: ```bash npm run dev ``` ### 🎯 Example: Claude Integration with Warp Terminal Here's how you can set up the MCP sound server to provide audio feedback when AI tasks complete in Warp terminal: **Configuration Rule:** "When AI is done, use mcp-make-sound to play a sound. The MCP supports error, info and success. Play the right sound based on AI task outcome." This setup allows you to: - 🔔 Hear a pleasant chime when tasks complete successfully - ⚠️ Get an alert sound for warnings or partial completions - ❌ Receive clear audio feedback for errors or failures The audio feedback helps you stay focused on other work while knowing immediately when your AI assistant has finished processing your requests. ### 🛠️ Available Tools The server provides four tools: #### Simple Sound Methods (Legacy) #### `play_info_sound` - **Description**: Play an informational system sound - **Parameters**: None - **Sound**: Glass.aiff #### `play_warning_sound` - **Description**: Play a warning system sound - **Parameters**: None - **Sound**: Purr.aiff #### `play_error_sound` - **Description**: Play an error system sound - **Parameters**: None - **Sound**: Sosumi.aiff #### Advanced Sound Method #### `play_sound` - **Description**: Play various types of sounds with customizable parameters - **Parameters**: - `type` (required): `"system"`, `"tts"`, or `"file"` - Additional based on type (see examples below) ### 📖 Usage Examples #### System Sounds Play any of the 14 built-in macOS sounds: ```json { "name": "play_sound", "arguments": { "type": "system", "name": "Basso" } } ``` **Available system sounds:** `Basso`, `Blow`, `Bottle`, `Frog`, `Funk`, `Glass`, `Hero`, `Morse`, `Ping`, `Pop`, `Purr`, `Sosumi`, `Submarine`, `Tink` #### Text-to-Speech Convert text to speech with optional voice selection: ```json { "name": "play_sound", "arguments": { "type": "tts", "text": "Hello, this is a test message", "voice": "Albert" } } ``` Without voice (uses system default): ```json { "name": "play_sound", "arguments": { "type": "tts", "text": "Task completed successfully" } } ``` **Supported voices:** - **English**: `Albert`, `Alice`, `Bad News`, `Bahh`, `Bells`, `Boing`, `Bruce`, `Bubbles`, `Cellos`, `Daniel`, `Deranged`, `Fred`, `Good News`, `Hysterical`, `Junior`, `Kathy`, `Pipe Organ`, `Princess`, `Ralph`, `Trinoids`, `Whisper`, `Zarvox` - **International**: `Anna`, `Amélie`, `Daria`, `Eddy`, `Fiona`, `Jorge`, `Juan`, `Luca`, `Marie`, `Moira`, `Nora`, `Rishi`, `Samantha`, `Serena`, `Tessa`, `Thomas`, `Veena`, `Victoria`, `Xander`, `Yelda`, `Zosia` **Note**: If an unsupported voice is specified, the system will gracefully fall back to the default voice and continue playback. #### Custom Audio Files Play audio files from disk: ```json { "name": "play_sound", "arguments": { "type": "file", "path": "/Users/username/Music/notification.mp3" } } ``` Supports common audio formats: `.aiff`, `.wav`, `.mp3`, `.m4a`, etc. ### 🔒 Security & Limitations - **System Sounds**: Only the 14 official macOS sounds are allowed - **Text-to-Speech**: - Text limited to 1000 characters maximum - Voice validation with graceful fallback to system default - Curated list of 43+ supported voices for security - **File Playback**: Requires absolute paths and validates file existence ### 🔗 Integration with MCP Clients This server can be integrated with any MCP-compatible client, such as: - 🤖 Claude Desktop - 🛠️ Custom MCP clients - 🧠 AI assistants that support MCP #### MCP Configuration Example Add this to your MCP client configuration: ```json { "mcp-make-sound": { "command": "node", "args": [ "/Users/nocoo/Workspace/mcp-make-sound/dist/index.js" ], "env": {}, "working_directory": "/Users/nocoo/Workspace/mcp-make-sound", "start_on_launch": true } } ``` Example tool calls: ```json { "name": "play_info_sound", "arguments": {} } ``` ```json { "name": "play_sound", "arguments": { "type": "system", "name": "Hero" } } ``` ## 🛠️ Development ### 📁 Project Structure ``` mcp-make-sound/ ├── src/ │ ├── index.ts # Main server implementation │ └── __tests__/ # Unit tests │ └── sound.test.ts # Sound system tests ├── dist/ # Compiled JavaScript output ├── eslint.config.js # ESLint configuration ├── vitest.config.ts # Vitest test configuration ├── package.json # Project configuration ├── tsconfig.json # TypeScript configuration └── README.md # This file ``` ### 📜 Scripts #### Build & Run - `npm run build` - 🔨 Compile TypeScript to JavaScript - `npm start` - ▶️ Run the compiled server - `npm run dev` - 🔄 Development mode with auto-rebuild and restart - `npm run kill` - 🛑 Stop all running MCP server instances #### Code Quality & Testing - `npm run lint` - 🔍 Check code style and errors - `npm run lint:fix` - 🔧 Fix auto-fixable linting issues - `npm run test` - 🧪 Run tests in watch mode - `npm run test:run` - ✅ Run tests once - `npm run test:ui` - 🎛️ Run tests with interactive UI ### ⚙️ How It Works 1. The server implements the MCP protocol using the official SDK 2. It exposes four tools for different sound capabilities 3. When a tool is called, it uses macOS commands: - `afplay` for audio file playback (system sounds and custom files) - `say` for text-to-speech synthesis 4. System sounds are located in `/System/Library/Sounds/` 5. The server communicates over stdio transport ## 🔧 Technical Details - **🔌 Transport**: Standard I/O (stdio) - **📡 Protocol**: Model Context Protocol (MCP) - **🎧 Audio Backend**: macOS `afplay` and `say` commands - **🎵 Sound Files**: System .aiff files, custom audio files, and synthesized speech ## 🚨 Error Handling The server includes comprehensive error handling: - Validates tool names and parameters - Handles `afplay` and `say` command failures - Validates required parameters for each sound type - Returns appropriate error messages to clients - Graceful server shutdown on errors ## 📄 License MIT License ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## 🎼 Sound Capabilities ### Simple Methods (Legacy) - **🔔 Info**: Glass.aiff - A pleasant chime sound - **⚠️ Warning**: Purr.aiff - A gentle alert sound - **❌ Error**: Sosumi.aiff - A distinctive error sound ### Advanced Method (play_sound) - **🎵 14 System Sounds**: All built-in macOS sounds available - **🗣️ 50+ TTS Voices**: Multiple languages and character voices - **📁 Custom Files**: Support for .aiff, .wav, .mp3, .m4a, and more These capabilities provide rich audio feedback options for any application need.