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.

• 🔔 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

• 🍎 macOS (uses afplay and system sounds)
• 🟢 Node.js 18+
• 📝 TypeScript

1. Clone this repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

Start the MCP server:

npm start

For development with auto-reload:

npm run dev

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.

The server provides four tools:

• Description: Play an informational system sound
• Parameters: None
• Sound: Glass.aiff

• Description: Play a warning system sound
• Parameters: None
• Sound: Purr.aiff

• Description: Play an error system sound
• Parameters: None
• Sound: Sosumi.aiff

• Description: Play various types of sounds with customizable parameters
• Parameters:
  • type (required): "system", "tts", or "file"
  • Additional based on type (see examples below)

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

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.

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.

• 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

This server can be integrated with any MCP-compatible client, such as:

• 🤖 Claude Desktop
• 🛠️ Custom MCP clients
• 🧠 AI assistants that support MCP

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"
  }
}

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

• 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

• 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

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

• 🔌 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

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

MIT License

Contributions are welcome! Please feel free to submit a Pull Request.

• 🔔 Info: Glass.aiff - A pleasant chime sound
• ⚠️ Warning: Purr.aiff - A gentle alert sound
• ❌ Error: Sosumi.aiff - A distinctive error 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.