MCP 服务器

claude-teams

MCP server that enables multi-agent collaboration with task lists, inter-agent messaging, and tmux-based spawning, making Claude Code's agent teams protocol available to any MCP client.

README

claude-teams

MCP server that implements Claude Code's agent teams protocol for any MCP client.

</div>

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), not main. 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_URL and the claude-teams MCP 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 via filelock.

~/.claude/
├── teams/<team>/
│   ├── config.json
│   └── inboxes/
│       ├── team-lead.json
│       ├── worker-1.json
│       └── .lock
└── tasks/<team>/
    ├── 1.json
    ├── 2.json
    └── .lock