workbeep-mcp

An MCP (Model Context Protocol) server that provides audio notification functionality for AI agents. Play sounds when your AI agent starts or finishes tasks!

Features

• 🎵 play_start_agent_sound - Plays a sound when an agent starts its work
• 🎉 play_finish_agent_sound - Plays a sound when an agent finishes its tasks

Quick Installation

Option 1: Using Claude MCP CLI (Recommended)

# Install using the Claude MCP CLI
claude mcp add workbeep -- npx -y workbeep-mcp

Option 2: NPX Direct Installation

# Run directly without installation
npx workbeep-mcp

# Or install globally
npm install -g workbeep-mcp

Option 3: From Source

# Clone the repository
git clone https://github.com/yourusername/workbeep-mcp.git
cd workbeep-mcp

# Install dependencies
npm install

# Run the server
npm start

Configure with Claude Desktop

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the workbeep server configuration:

{
  "mcpServers": {
    "workbeep": {
      "command": "workbeep-mcp"
    }
  }
}

3. Restart Claude Desktop

Manual Setup

If you prefer to run from source:

{
  "mcpServers": {
    "workbeep": {
      "command": "node",
      "args": ["/path/to/workbeep_mcp/index.js"]
    }
  }
}

Audio Files

The package includes default notification sounds. You can customize them by replacing:

• audio/start.mp3 - Sound played when agent starts
• audio/finish.mp3 - Sound played when agent finishes

Requirements

• Node.js 16+
• Audio playback capability on your system

How It Works

When configured, Claude Desktop will have access to two new tools:

1. When an agent begins a task, it can call play_start_agent_sound
2. When an agent completes its work, it can call play_finish_agent_sound

These audio notifications help you stay aware of your AI agent's progress without constantly monitoring the screen.

Troubleshooting

• No sound? Make sure your system volume is on and the audio files exist
• Command not found? Run npm install -g workbeep-mcp or use the full path
• Permission denied? Make sure the files have execute permissions

License

MIT