Skip to main content
Glama
giuliocapecchi

sound-mcp

by giuliocapecchi
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

sound-mcp

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.

Related MCP server: mcp-notifications

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.

Available Tools

3 tools
list_soundsA

List every sound name the user can pick from, plus the current default.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. 'List' implies a read-only operation, but the description does not explicitly state lack of side effects or state changes. Adds minimal behavioral context beyond the verb.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the key action and result. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with no parameters and an output schema exists. The description covers the essential information (sound names and default), making it complete for an agent to understand the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has zero parameters with 100% coverage, so baseline is 4. The description adds no parameter info because none exist, which is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all sound names and the current default, with a specific verb ('List') and resource ('sound names'). It distinguishes from siblings 'notify' and 'play_sound' which involve actions rather than listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for browsing sounds and knowing the default, but does not explicitly state when to use vs. alternatives like 'play_sound'. No when-not or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notifyA

Show a desktop notification AND play a sound.

urgency: low | normal | critical (critical toasts are sticky on most desktops). expire_ms: notification timeout in ms; 0 = desktop default.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYes
titleNoClaude
soundNo
urgencyNonormal
expire_msNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains urgency effects and expire_ms behavior, but fails to disclose that the 'sound' parameter is optional (default null) and may not actually play a sound, contradicting the claim 'play a sound'. No annotations are provided, so the description carries the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences in a list format. The main purpose is front-loaded, and parameter details are efficiently provided without repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple notification tool, the description covers most relevant aspects. Minor gaps exist (e.g., sound parameter behavior), but the presence of an output schema reduces the need for return value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds value by explaining urgency values and expire_ms behavior. However, it does not clarify the 'message', 'title', or 'sound' parameters, leaving gaps in understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Show a desktop notification AND play a sound.' It specifies the action and resources (notification and sound), and distinguishes from sibling tools like list_sounds and play_sound by combining both functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (for notifications with optional sound) but does not explicitly compare to siblings. However, the context of sibling tools list_sounds and play_sound makes the intended usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

play_soundA

Play a notification sound.

name can be a registered sound (see list_sounds) or an absolute path to an audio file. If omitted, plays the configured default.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must explain behavior. It discloses the parameter options and default, but does not cover edge cases like error handling, blocking versus non-blocking execution, or file compatibility, limiting full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (two sentences) and front-loaded with the core action. Every sentence is meaningful and contributes to understanding, with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter) and the existence of an output schema, the description is complete. It covers the purpose, parameter semantics, default behavior, and references a sibling tool, leaving no major gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining the 'name' parameter in detail: it can be a registered sound (linking to list_sounds) or an absolute path, and it is optional with a default. This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Play a notification sound.' It is specific and distinct from siblings like list_sounds and notify, ensuring the agent can select it appropriately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance by mentioning list_sounds for registered sounds and explaining default behavior. However, it lacks explicit when-not-to-use or comparison with the notify sibling, which would improve decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedlist_sounds
    • First observednotify
    • First observedplay_sound
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation4/5

The tools have distinct purposes but notify and play_sound both involve playing a sound, which could cause confusion. However, the descriptions clarify the differences, so disambiguation is good overall.

Naming Consistency4/5

Two tools follow verb_noun pattern (list_sounds, play_sound), while notify is a single verb. This is a minor inconsistency but not chaotic.

Tool Count4/5

Three tools is reasonable for a focused sound server. It covers core operations without being excessive, though it's on the smaller side.

Completeness4/5

The tool set covers listing sounds, playing sounds, and notifications. Missing management of sound library (add/remove) but this is acceptable for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/giuliocapecchi/sound-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server