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 PORT env var)
• TTL: 24h message expiry (configurable via MESSAGE_TTL_MS env var)