Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CollabMCP Who owns the files in src/models/?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shared, real-time context for every Claude Code on your team — scope awareness, prior decisions, and anti-overlap. No database, no server to host. Just files in your repo.
When two people point Claude Code at the same repo, the agents have no idea the other exists. CollabMCP fixes that: it's a local MCP server that gives each agent a shared view of who's working on what, what's already been decided, and whether a file is "owned" by someone else right now.
Everything lives in a .collab/ directory in your repo — plain JSON and a JSONL log. No Postgres, no Redis, no embeddings.
Five tools, available to Claude Code automatically:
Tool | When Claude uses it |
| At the start of a session — who's active, recent decisions, your scope, unread messages |
| Before editing a file that might belong to a teammate |
| Before a big decision — has this already been settled? |
| After an architectural decision or non-obvious fix |
| To warn the team about a breaking change |
Plus a dynamic CLAUDE.md: a <!-- COLLAB --> block at the top of your CLAUDE.md that regenerates automatically as the team's state changes, so every agent reads the latest context.
Related MCP server: whiteboard-mcp-server
CollabMCP is distributed from source (not on npm). Install it once, globally:
git clone https://github.com/BautistaPessagno/collab-mcp.git
cd collab-mcp
npm install
npm run build
npm link # makes the `collab-mcp` command available everywhereAfter npm link, collab-mcp and npx collab-mcp both resolve to your local build.
Prerequisite: do the Install step once on your machine (clone + build +
npm link). That's what makes thecollab-mcp/npx collab-mcpcommand resolve — the package is not on npm.
# 1. In your project repo, initialize CollabMCP
npx collab-mcp init
# 2. Set your identity and scope
# Edit .claude/collab.json: set "dev_id" and the "scope" globs you own
# e.g. "dev_id": "bautista", "scope": ["/auth/**", "/middleware/**"]
# 3. Restart Claude Code so it loads the MCP server from .claude/mcp.json
# 4. Commit the shared state so teammates get it
git add .collab/state.json .collab/decisions.jsonl .claude/ CLAUDE.md
git commit -m "Add CollabMCP"
# 5. Each teammate does the Install step once (clone + build + npm link),
# then in this repo runs `npx collab-mcp init`, sets their own
# dev_id/scope, and restarts Claude Code. Done.Check the team state from the terminal any time:
npx collab-mcp status.collab/
├── state.json # active devs, their scope, current task (committed)
├── decisions.jsonl # append-only log of decisions (committed)
├── locks/ # short-lived path locks (gitignored)
└── inbox/ # per-dev broadcast messages (gitignored)who_owns matches a path against each dev's scope globs (via minimatch) and any active lock.
recall is keyword-overlap search over decisions.jsonl — simple, fast, no embeddings.
A file watcher regenerates the CLAUDE.md block within ~150ms of any state change.
Writes to state.json are atomic (temp file + rename), so concurrent devs don't corrupt it.
.claude/collab.json){
"server": "local",
"collab_dir": ".collab",
"dev_id": "bautista",
"scope": ["/auth/**", "/middleware/**"],
"lock_ttl_minutes": 30
}Vector search, web dashboard, auth, Postgres/Redis, multi-repo. The data model is intentionally just files — see the roadmap in collab_mvp_plan.md.
MIT
Send a message to every active teammate — breaking changes, interface changes, or coordination requests.
Inputs: message (required), urgency.
Snapshot of the team's shared context: your scope, who else is active, recent decisions, active locks, and any inbox messages. Call this at the start of every session.
Inputs: no named parameters.
Search prior team decisions before making an important choice, to check if something was already resolved.
Inputs: query (required).
Record an architectural decision, a non-obvious bug fix, or anything teammates should know. Append-only and shared with the team.
Inputs: content (required), scope (required), tags.
Check whether a file or directory belongs to another dev's scope before editing it. Returns the owner and whether you can proceed.
Inputs: path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool has a clearly distinct purpose: broadcast for messaging, get_session for context snapshot, recall for reading past decisions, remember for writing decisions, who_owns for ownership queries. No overlap.
Naming is mixed: 'broadcast', 'recall', 'remember' are single verbs; 'get_session' is verb_noun; 'who_owns' is a question. No consistent pattern, though all are readable.
With 5 tools covering communication, session management, knowledge base, and ownership, the count is well-scoped for a team collaboration server.
Covers key collaboration features (messaging, context, decisions, ownership). Minor gap: no explicit lock acquisition/release tool, but get_session and who_owns may suffice.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared, scoped, reviewable team memory for AI coding agents.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.