Skip to main content
Glama
taylor224

bell-mcp

by taylor224
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description must convey behavioral traits. It adequately indicates a read-only listing operation, but does not mention permissions or side effects. Given the simplicity, it is minimally sufficient.

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 a single, well-structured sentence that efficiently conveys the tool's purpose and output. No redundant or filler content.

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?

Given the low complexity (0 parameters) and the existence of an output schema, the description provides sufficient information about the returned data. It could optionally mention ordering or filtering, but the current content is adequate for selection and invocation.

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?

There are 0 parameters, and schema coverage is 100% trivially. The description adds value by specifying the output fields (id, name, description, default) beyond the empty schema, fulfilling the baseline expectation for zero-parameter tools.

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 specifies the verb 'list', the resource 'bell sounds', and the returned fields (id, name, description, default). It inherently distinguishes from the sibling tool 'ring_bell' which performs a different action.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like 'ring_bell'. The description does not provide context for selection or exclusion criteria.

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

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.
ParametersJSON Schema
NameRequiredDescriptionDefault
soundNo
messageNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and does well by explaining the tool's action (ringing a bell through speakers), the sound effects, and that the message is returned in confirmation. It does not mention potential hardware requirements or asynchronicity, but these are minor for a simple notification tool.

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 compact and well-structured: a clear purpose statement, usage context, and a bulleted list of arguments with clear formatting. Every sentence adds value without redundancy.

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 has two optional parameters, no required fields, and an output schema exists (not shown but noted), the description covers all necessary aspects: what the tool does, when to use it, and what each parameter does. It is complete for an agent to select and invoke correctly.

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?

Schema description coverage is 0%, but the description adds extensive detail: for 'sound' it lists four specific options with human-readable descriptions and mentions the default behavior; for 'message' it explains its role and what happens to it (returned in confirmation). This fully compensates for the schema's lack of descriptions.

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 verb 'Ring a bell', the resource 'bell', and the purpose 'to alert the human'. It distinguishes itself from the sibling tool 'list_bells' which lists bells rather than ringing them.

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 explicitly says when to call it: 'when a task is complete or when you need the human's attention.' It provides detailed guidance on sound options and message parameter but does not explicitly state when not to use it, though that is implicit given its simplicity.

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.

  1. 2 tool updatesv0.1.0
    • First observedlist_bells
    • First observedring_bell
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Sound Notification MCP

    ks0318-p
    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.
    6 npm
    2
    MIT

  • ntfy-me-mcp

    gitmotion
    A
    license
    A
    quality
    C
    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
    104 npm
    73
    GPL 3.0