play-sound-mcp-server

play-sound-mcp-server

3.2

If you are the rightful owner of play-sound-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Play Sound Server is a Model Context Protocol server designed to provide audio playback functionality for AI agents, enabling them to play sound notifications upon task completion.

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]"
  1. 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"
      ]
    }
  }
}
  1. 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 file for details.

Acknowledgments