Skip to main content
Glama

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)

Related MCP server: ntfy-me-mcp

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

Available Tools

2 tools
list_bellsA

List the available bell sounds (id, name, description) and the default.

Inputs: no named parameters. Returns: result

ring_bellA

Ring a bell through the speakers to alert the human.

Call this when a task is complete or when you need the human's attention.

Args:
    sound: Which bell to ring. One of:
        - "beep"      (Retro Beep): harsh 90s PC-speaker beep
        - "ding"      (Ding): single soft bell tone
        - "ding-ding" (Double Ding): two bell tones in a row
        - "warning"   (Warning Alarm): urgent alternating two-tone alarm
        If omitted, the preset default (BELL_DEFAULT_SOUND, else "ding")
        is used.
    message: Optional note about why the bell is ringing (e.g. "build
        finished", "need your input"). Returned in the confirmation.

Inputs: sound, message. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: list_bells retrieves available sounds, ring_bell triggers an alert. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern ('list_bells', 'ring_bell'), making their actions predictable.

    Tool Count5/5

    Two tools perfectly match the narrow domain of bell ringing—listing options and ringing—without unnecessary extras.

    Completeness5/5

    The tool set covers the full lifecycle: discover available sounds and trigger an alert. No missing operations for this focused purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that plays notification sounds when AI coding assistants like Windsurf or Cursor require user attention, such as when coding is complete or when user approval is needed.
      17 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A streamlined MCP server that enables AI assistants to send real-time notifications to your devices through the ntfy service, allowing you to receive alerts when tasks complete or important events occur.
      2
      244 npm
      76
      GPL 3.0