claude-teams
MCP server that implements Claude Code's agent teams protocol for any MCP client.
https://github.com/user-attachments/assets/531ada0a-6c36-45cd-8144-a092bb9f9a19
Claude Code has a built-in agent teams feature (shared task lists, inter-agent messaging, tmux-based spawning), but the protocol is internal and tightly coupled to its own tooling. This MCP server reimplements that protocol as a standalone MCP server, making it available to any MCP client: Claude Code, OpenCode, or anything else that speaks MCP. Based on a deep dive into Claude Code's internals. PRs welcome.
Install
Pin to a release tag (e.g.
@v0.1.1), notmain. There are breaking changes between releases.
Claude Code (.mcp.json):
{
"mcpServers": {
"claude-teams": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"]
}
}
}
OpenCode (~/.config/opencode/opencode.json):
{
"mcp": {
"claude-teams": {
"type": "local",
"command": ["uvx", "--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"],
"enabled": true
}
}
}
Requirements
- Python 3.12+
- tmux
- At least one coding agent on PATH: Claude Code (
claude) or OpenCode (opencode) - OpenCode teammates require
OPENCODE_SERVER_URLand theclaude-teamsMCP connected in that instance
Configuration
| Variable | Description | Default |
|---|---|---|
CLAUDE_TEAMS_BACKENDS | Comma-separated enabled backends (claude, opencode) | Auto-detect from connecting client |
OPENCODE_SERVER_URL | OpenCode HTTP API URL (required for opencode teammates) | (unset) |
USE_TMUX_WINDOWS | Spawn teammates in tmux windows instead of panes | (unset) |
Without CLAUDE_TEAMS_BACKENDS, the server auto-detects the connecting client and enables only its backend. Set it explicitly to enable multiple backends:
{
"mcpServers": {
"claude-teams": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cs50victor/claude-code-teams-mcp@v0.1.1", "claude-teams"],
"env": {
"CLAUDE_TEAMS_BACKENDS": "claude,opencode",
"OPENCODE_SERVER_URL": "http://localhost:4096"
}
}
}
}
Tools
| Tool | Description |
|---|---|
team_create | Create a new agent team (one per session) |
team_delete | Delete team and all data (fails if teammates active) |
spawn_teammate | Spawn a teammate in tmux |
send_message | Send DMs, broadcasts (lead only), shutdown/plan responses |
read_inbox | Read messages from an agent's inbox |
read_config | Read team config and member list |
task_create | Create a task (auto-incrementing ID) |
task_update | Update task status, owner, dependencies, or metadata |
task_list | List all tasks |
task_get | Get full task details |
force_kill_teammate | Kill a teammate's tmux pane/window and clean up |
process_shutdown_approved | Remove teammate after graceful shutdown |
Architecture
- Spawning: Teammates launch in tmux panes (default) or windows (
USE_TMUX_WINDOWS). Each gets a unique agent ID and color. - Messaging: JSON inboxes at
~/.claude/teams/<team>/inboxes/. Lead messages anyone; teammates message only lead. - Tasks: JSON files at
~/.claude/tasks/<team>/. Status tracking, ownership, and dependency management. - Concurrency: Atomic writes via
tempfile+os.replace. Cross-platform file locks viafilelock.
~/.claude/
├── teams/<team>/
│ ├── config.json
│ └── inboxes/
│ ├── team-lead.json
│ ├── worker-1.json
│ └── .lock
└── tasks/<team>/
├── 1.json
├── 2.json
└── .lock