Beep MCP Server

A Model Context Protocol (MCP) server that provides beep sound playback functionality for Claude Code hooks.

Features

• 🔊 Headphone-friendly: Plays sounds through system audio devices (headphones/speakers)
• ⚡ Fast preset mode: Uses pre-generated WAV file (800Hz, 300ms) for instant playback
• 🎛️ Customizable: Supports custom frequency and duration parameters
• 🔌 MCP-compatible: Works seamlessly with Claude Code hooks
• 🖥️ Cross-platform: Supports Windows, macOS, and Linux

Installation

From npm (Recommended)

npm install -g @progden/beep-mcp

From Source

git clone https://github.com/progden/beep-mcp.git
cd beep-mcp
npm install

The installation will automatically:

1. Compile TypeScript source files
2. Generate the default beep.wav file (800Hz, 300ms, 80% volume)

Usage

As MCP Server (Claude Code Hook)

After installing globally, add to your .claude/settings.json:

{
  "hooks": {
    "userPromptSubmitTool": {
      "command": "beep-mcp"
    }
  }
}

Now Claude Code will play a beep sound when the Stop hook event is triggered.

Standalone Test

Test the beep functionality directly:

# If installed globally
beep-mcp --test

# If installed from source
npm run test
# Or manually
node dist/index.js --test

MCP Tool API

play_beep

Plays a beep sound through system audio.

Parameters:

| Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ---------------------------------------- | | frequency | number | No | 800 | Frequency in Hz (20-20000) | | duration | number | No | 300 | Duration in milliseconds (10-5000) |

Behavior:

• No parameters: Uses pre-generated beep.wav (800Hz, 300ms, 80% volume) - fastest option
• With parameters: Dynamically generates WAV with specified frequency/duration

Examples:

// Preset beep (fastest)
await playBeep();

// Custom frequency
await playBeep(800);

// Custom frequency and duration
await playBeep(1000, 300);

Project Structure

beep-mcp/
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── sounds/
│   └── beep.wav             # Pre-generated beep (800Hz, 300ms, 80% volume)
├── src/
│   ├── index.ts             # MCP server main entry point
│   ├── audio.ts             # WAV generation logic
│   ├── player.ts            # Audio playback module
│   └── generate-beep.ts     # Preset beep generator script
└── dist/                    # Compiled JavaScript (auto-generated)

Technical Details

Audio Generation

• Format: WAV (PCM 16-bit mono)
• Sample Rate: 44.1 kHz (CD quality)
• Waveform: Sine wave with fade in/out envelope (prevents clicks)
• Volume: 80% of max amplitude (adjustable)

Audio Playback

• Library: node-wav-player (background playback using PowerShell SoundPlayer on Windows)
• Background Mode: No visible windows, plays directly through system audio
• Temp Files: Custom beeps use temporary files (auto-cleanup)
• Error Handling: Graceful fallback with detailed error messages

MCP Integration

• Protocol: Model Context Protocol (stdio transport)
• SDK: @modelcontextprotocol/sdk
• Tool Definition: Single play_beep tool with optional parameters

Development

Build

npm run build

Watch Mode

npm run dev

Regenerate Preset Beep

npm run generate-beep

Troubleshooting

No sound in headphones

1. Check system audio settings
2. Verify default playback device is set correctly
3. Test with npm run test to ensure audio works standalone

"Preset beep.wav not found" error

Run the generator script:

npm run generate-beep

MCP server not responding

1. Check that the path in .claude/settings.json is correct
2. Ensure TypeScript has been compiled (npm run build)
3. Test MCP server manually: node dist/index.js

Dependencies

• Runtime:

  • @modelcontextprotocol/sdk: MCP protocol implementation
  • node-wav-player: Cross-platform background audio playback

• Development:

  • typescript: TypeScript compiler
  • @types/node: Node.js type definitions

License

MIT

Author

Created for Claude Code integration