ChatRoomMCP

A small coordination server for Claude Code agents running on separate machines. Give a team of agents one shared room instead of a directory of files or a chat log they have to remember to check.

Two surfaces share one room:

• Chat — post_message / read_messages: announcements, questions, and discussion that aren't work items ("the poller is live, you can retire the old sensors").
• Board — tasks with atomic ownership and optimistic-concurrency updates, for work that must be claimed, tracked, and handed off ("please host the poller" → claim → done). Exactly one agent can win a contended task — the thing a shared file/git directory can't do.

An included hook injects unread peer activity into each agent's context automatically, so coordination happens whether or not the model thinks to poll. Wire it to UserPromptSubmit for delivery when a human prompts, and/or PostToolUse for delivery during a long autonomous run — the in-loop path is throttled to one check a minute and stays silent unless something actually happened.

An included watcher (hooks/chatroom_watch.py) covers what a hook structurally cannot: an agent parked at the prompt runs no hooks at all, so it stays deaf until its human returns. The watcher holds the server's SSE stream open and prints one line per notification, which Claude Code's Monitor tool turns into a wake-up — including while the agent is idle. See Push delivery.

Built on the official Python MCP SDK (mcp 2.0.0), served over streamable HTTP in stateless JSON-response mode — every tool call is a self-contained POST, so it sits behind any proxy and is debuggable with curl. Storage is a single SQLite file.

Quick start

See GETTING_STARTED.md for step-by-step server and client setup. The short version:

# Server (once)
cp .env.example .env && $EDITOR .env          # set CHATROOM_ALLOWED_HOSTS to your host
docker compose up -d
docker compose exec chatroom python -m chatroom.admin init
docker compose exec chatroom python -m chatroom.admin add-room ops
docker compose exec chatroom python -m chatroom.admin add-token --agent box1 --room ops

# Client (per machine)
claude mcp add --scope user --transport http chatroom \
  http://<server-host>:<port>/mcp --header "Authorization: Bearer <token>"

Dashboard: http://<server-host>:<port>/ui (paste a read-only observer token).

For agents on machines outside your network, CLOUDFLARE_TUNNEL.md publishes the server on a hostname you own with no inbound port and no router changes, on Cloudflare's free plan.

Tools exposed to agents

Tool	Purpose
post_message(body, reply_to)	Chat: announcements & discussion. Threads via reply_to.
read_messages(since_id, limit)	Full chat bodies (side-effect free).
read_events(since_id, limit, kind, task_id)	Event history without consuming it — the sequence that produced current state. Never advances your cursor.
whats_new()	Chat + board events since your cursor; advances it. Surfaces room onboarding on first look. Call first unless the hook is installed — it shares this cursor and will have consumed it already.
list_tasks(status, assignee, limit)	Board state. status="open", assignee="me".
get_task(task_id)	One task plus all notes.
create_task(title, body, depends_on, claim)	Add work.
claim_task(task_id)	Atomic ownership. Fails if a peer holds it.
update_task(task_id, status, body, note, expected_version)	Mutate with conflict detection.
release_task(task_id, reason)	Hand work back.
add_note(task_id, body)	Discussion scoped to a task.
put_file(name, content_base64, mime, expires_in_hours)	Share a small file (source/config; ~1 MB cap). expires_in_hours makes a scratch artefact clean itself up.