sound-mcp

<p align="center"> <img src="assets/banner.png" alt="sound-mcp banner" width="600"> </p>

<p align="center"> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white" alt="Python"></a> <a href="#requirements"><img src="https://img.shields.io/badge/platform-linux-555?logo=linux&logoColor=white" alt="Platform"></a> <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a> </p>

A small FastMCP server that lets the agent play a notification sound, and optionally pop a desktop toast, when something finishes. Useful for "poll X until Y, then ping me" workflows.

Tools

• list_sounds(): show every available sound name and the current default.
• play_sound(name=None): play a registered sound, an absolute file path, or the default.
• set_default_sound(name_or_path): persist a new default (registered name or absolute path) to ~/.config/sound-mcp/default. Survives restarts. Overridden at runtime by SOUND_MCP_DEFAULT if it is set in mcp.json.
• notify(message, title="Claude", sound=None, urgency="normal", expire_ms=0): desktop toast + sound. urgency=critical: makes the toast sticky on most desktops.

Requirements

Linux with paplay (PulseAudio/PipeWire) and notify-send (libnotify-bin). Builtin sounds come from sound-theme-freedesktop, preinstalled on Ubuntu. You only need uv and Python ≥ 3.11.

Quick start

Claude Code

claude mcp add sound-mcp -- uvx --from git+https://github.com/giuliocapecchi/sound-mcp sound-mcp

Other MCP clients (Claude Desktop, Codex, OpenCode, …)

Add this block to your client's MCP config file:

{
  "mcpServers": {
    "sound-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/giuliocapecchi/sound-mcp", "sound-mcp"]
    }
  }
}

Common config locations:

Client	Config file
Claude Desktop	claude_desktop_config.json
Codex (OpenAI)	~/.codex/config.json
OpenCode	opencode.json

Configuration

All settings are read from environment variables, so you set them in the env block of your mcp.json (or equivalent):

{
  "mcpServers": {
    "sound-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/giuliocapecchi/sound-mcp", "sound-mcp"],
      "env": {
        "SOUND_MCP_DEFAULT": "warning",
        "SOUND_MCP_SOUNDS_DIR": "/home/you/.config/sound-mcp/sounds"
      }
    }
  }
}

Variable	Default	Purpose
SOUND_MCP_DEFAULT	warning	Sound played when play_sound/notify is called with no name.
SOUND_MCP_SOUNDS_DIR	~/.config/sound-mcp/sounds	Directory scanned for user sound files.

Custom sounds

Builtin names: complete, bell, warning, error, alarm.

Drop audio files (.oga, .ogg, .wav, .mp3, .flac) into your sounds directory and each becomes a sound keyed by its filename stem. For example tada.wav → play_sound("tada"). User files override builtins on name collision.

You can also pass an absolute path directly: play_sound("/tmp/horn.wav").

Example prompt

Poll tailscale status every 10 seconds. When node myserver shows as online, call the notify tool with title="Tailscale" and message="myserver is back".

Local development

git clone https://github.com/giuliocapecchi/sound-mcp
cd sound-mcp
uv venv && uv pip install -e .
uv run fastmcp dev src/sound_mcp/server.py   # opens MCP Inspector

License

MIT.