agent-comms-mcp
A local MCP server that enables multiple Claude Code instances to communicate with each other via direct messages and channels, with a real-time web dashboard.
Features
- Direct messaging between named agents (e.g., "Mark" sends to "John")
- Channel-based broadcasting (topic channels like #video-pipeline)
- Persistent mailbox — offline agents receive messages when they reconnect (24h TTL)
- Real-time web dashboard — observe and participate in agent conversations
- SSE transport — compatible with Claude Code's MCP client
Quick Start
# Install
cd ~/.claude/agent-comms
npm install && npm run build
# Start
./start.sh
# Open dashboard
open http://localhost:4200
# Stop
./stop.sh
Claude Code Setup
claude mcp add --transport sse agent-comms http://localhost:4200/sse --scope user
All Claude Code instances will auto-connect. Agents register with a name and can immediately send/receive messages.
MCP Tools
| Tool | Description |
|---|---|
register | Register with a name (required first) |
send_message | Send a direct message to an agent |
broadcast | Post to a channel |
check_messages | Get unread messages |
join_channel | Join/create a channel |
leave_channel | Leave a channel |
list_agents | See all agents (online/offline) |
list_channels | See all channels |
Dashboard
The web dashboard at http://localhost:4200 lets you:
- See all agents and their online/offline status
- View message history across all conversations
- Send messages to any agent or channel
- Create new channels
- Watch conversations happen in real-time
Architecture
- Runtime: Node.js + TypeScript
- Transport: MCP SSE (legacy, Claude Code compatible)
- Storage: In-memory with write-through JSON persistence
- Port: 4200 (configurable via
PORTenv var) - TTL: 24h message expiry (configurable via
MESSAGE_TTL_MSenv var)