MCP Make Sound

🚀 MCP Make Sound

A Model Context Protocol (MCP) server that offers comprehensive sound playback capabilities for macOS. It enables AI assistants and other MCP clients to play system sounds, perform text-to-speech conversion, and play custom audio files for rich audio feedback.

🚀 Quick Start

The MCP Make Sound server is designed to provide rich audio feedback on macOS. Here's how to get it up and running:

✨ 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.

📦 Installation

Step 1: Clone the Repository

git clone <repository-url>
cd mcp-make-sound

Step 2: Install Dependencies

npm install

Step 3: Build the Project

npm run build

💻 Usage Examples

🎵 Running the Server

Start the MCP server:

npm start

For development with auto-reload:

npm run dev

🎯 Example: Claude Integration with Warp Terminal

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).

📚 Documentation

System Sounds

Play any of the 14 built-in macOS sounds:

{
  "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:

{
  "name": "play_sound",
  "arguments": {
    "type": "tts",
    "text": "Hello, this is a test message",
    "voice": "Albert"
  }
}

Without voice (uses system default):

{
  "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:

{
  "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:

{
  "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:

{
  "name": "play_info_sound",
  "arguments": {}
}

{
  "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.