bell-mcp

A local MCP server that rings a bell through your speakers — so you get an audible nudge when your AI assistant finishes a task or needs your attention.

Four built-in sounds, synthesized from scratch with the Python standard library (no audio assets to download):

id	name	sound
beep	Retro Beep	harsh 90s PC-speaker square-wave beep
ding	Ding	single soft struck-bell tone
ding-ding	Double Ding	two struck-bell tones in a row
warning	Warning Alarm	urgent alternating two-tone alarm

You can preset a default sound and/or pick a sound per call.

Requirements

• Python ≥ 3.11 and uv
• An audio player on PATH:
  • macOS: afplay (built in)
  • Linux: paplay, aplay, or ffplay
  • Windows: PowerShell (built in)

Tools

• ring_bell(sound?, message?) — ring a bell. sound is one of beep / ding / ding-ding / warning; if omitted, the preset default is used. message is an optional note (e.g. "build finished") echoed back in the confirmation.
• list_bells() — list available sounds (id, name, description) and show the current default.

Configuration

The default bell (used when ring_bell is called without sound) is set via the BELL_DEFAULT_SOUND environment variable. Valid values: beep, ding, ding-ding, warning. If unset or invalid, it falls back to ding.

Install

Clone the repository, then register the server with your MCP client.

git clone git@github.com:taylor224/bell-mcp.git
cd bell-mcp
uv sync

Claude Code

Run this from the cloned project directory:

claude mcp add bell -e BELL_DEFAULT_SOUND=ding -- uv run --directory "$(pwd)" bell-mcp

Add --scope user to make it available in every project (instead of just the current one).

Verify it connected:

claude mcp list

Other MCP clients (Claude Desktop, etc.)

Add an entry to your client's MCP config. Replace /absolute/path/to/bell-mcp with the path where you cloned this repo:

{
  "mcpServers": {
    "bell": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/bell-mcp", "bell-mcp"],
      "env": { "BELL_DEFAULT_SOUND": "ding" }
    }
  }
}

Once registered, ask your assistant to ring the bell — e.g. "ring ding-ding whenever you finish a task" or "ring the warning alarm if you need my input."

Development

uv sync                          # install dependencies
uv run bell-mcp                  # run the server over stdio
uv run python -m bell_mcp.sounds # (re)generate the WAV files

The WAV files live in bell_mcp/assets/ and are generated automatically on first run. To tweak the timbres, edit the frequency / decay / partial values in bell_mcp/sounds.py and regenerate.

Project layout

bell_mcp/
  server.py     # FastMCP server + tools, cross-platform playback
  sounds.py     # WAV synthesis (stdlib only); auto-generated on first run
  assets/       # generated *.wav files
pyproject.toml  # bell-mcp entry point

License

MIT