@agentbell/mcp-server

MCP (Model Context Protocol) server for AgentBell — a macOS menubar companion that watches your AI coding sessions and responds with emotional feedback (bubble text + voice).

This server acts as the bridge between your IDE's AI agent and the AgentBell desktop app. When the AI starts or finishes a task, this server notifies AgentBell so it can react in real time.

Quick Setup

Add to your IDE's MCP configuration:

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "agentbell": {
      "command": "npx",
      "args": ["-y", "@agentbell/mcp-server@latest"]
    }
  }
}

VSCode (~/.vscode/mcp.json):

{
  "servers": {
    "agentbell": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@agentbell/mcp-server@latest"]
    }
  }
}

Or run directly:

npx @agentbell/mcp-server

Tools

agentbell_notify

Notify AgentBell of an AI agent state change.

| Parameter | Required | Values | Description | |-----------|----------|--------|-------------| | state | Yes | running, waiting, done, error | Current task state | | project | No | any string | Project name for context |

agentbell_status

Query the current AgentBell app status. No parameters needed.

How It Works

IDE AI Agent → MCP tool call → agentbell_notify(state="done")
                                      ↓
                              writes to agentbell-events.jsonl
                                      ↓
                              AgentBell.app picks up event
                                      ↓
                              Live2D bubble + voice feedback 🎉

The server communicates with AgentBell.app by appending events to a local JSONL file (~/Library/Caches/agentbell-events.jsonl), which the app monitors in real time. No network requests, no external services.

Requirements

• AgentBell.app running on macOS
• Node.js >= 18

License

MIT