What is Play Sound Mcp Server

play-sound-mcp-server is a Model Context Protocol (MCP) server designed to provide audio playback functionality for AI agents. It allows AI agents to play sound notifications upon the completion of coding tasks. Currently, it is an early version and is only tested on macOS.

Use cases

Use cases include notifying developers when a coding task is completed, providing alerts for automated testing results, and enhancing interactive coding environments with sound notifications.

How to use

To use play-sound-mcp-server, clone the repository, set up a Python virtual environment, install the necessary dependencies, and configure it in the Claude Desktop application. After setup, you can test the functionality by asking the AI to play a notification sound.

Key features

Key features include audio notifications for task completion, a default notification sound, support for custom audio files (WAV, MP3, FLAC, OGG, M4A), intelligent fallback to default sound if custom audio fails, and current support for macOS.

Where to use

play-sound-mcp-server can be used in software development environments where AI agents are employed to assist with coding tasks, providing auditory feedback to enhance user experience.

MCP Play Sound Server

A Model Context Protocol (MCP) server that provides audio playback functionality for AI agents. This server enables AI agents to play sound notifications when coding tasks are completed.

⚠️ Early Version / Proof of Concept
This is an early implementation currently tested only on macOS. Future versions will support additional platforms.

Features

• Audio Notifications: Play sound alerts when AI tasks complete
• Default Sound: Bundled notification sound for immediate use
• Custom Audio: Support for custom audio files (WAV, MP3, FLAC, OGG, M4A)
• Intelligent Fallback: Automatic fallback to default sound if custom audio fails
• macOS Support: Currently tested on macOS using AFPlay and SimpleAudio

Installation & Setup

Development Setup

1. Clone and install:

git clone <repository-url>
cd play-sound-mcp-server
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

2. Configure Claude Desktop:
   Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "play-sound": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/play-sound-mcp-server",
        "run",
        "mcp-server-play-sound"
      ]
    }
  }
}

3. Test: Restart Claude Desktop and ask: “Can you play a notification sound?”

Configuration

Environment variables (optional):

• CUSTOM_SOUND_PATH: Path to custom audio file
• VOLUME_LEVEL: Playback volume (0.0-1.0, default: 0.8)
• ENABLE_FALLBACK: Enable fallback to default sound (default: true)
• AUDIO_DEVICE: Specific audio output device name (e.g., “Mac Studio Speakers”)

Available Tools

play_notification_sound

Plays a notification sound to alert the user.

Parameters:

• custom_sound_path (optional): Path to custom audio file
• message (optional): Context message for the notification

get_audio_status

Returns current audio system status and configuration.

test_audio_playback

Tests audio playback functionality.

Parameters:

• use_custom (optional): Test with custom sound if configured

list_audio_devices

Lists all available audio output devices on the system.

Returns:

• List of available audio devices with their properties
• Current configured device (if any)
• Default device information

Development

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Testing

pytest tests/

License

MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol by Anthropic
• Python audio library maintainers