Claude Team

You deploy and run Claude Team MCP Server to orchestrate a fleet of Claude Code sessions from a central manager. This lets you spawn workers, assign parallel tasks, monitor progress, and collect logs in real time, all while keeping each worker isolated and controllable from a single interface.

How to use

You interact with the MCP server through your Claude Code client and the built-in tools described below. Start the MCP server in a local environment, then use the manager to spawn workers, assign tasks, and monitor progress. You can issue commands to spawn workers with defined project paths, broadcast messages to multiple workers, read logs from each worker, and observe idle or active states to coordinate workflows.

How to install

Prerequisites you need before starting are:

• macOS with iTerm2 installed
• iTerm2 Python API enabled (Preferences → General → Magic → Enable Python API)
• Python 3.11 or newer
• uv tool (used to run MCP servers)

Install and run the MCP server locally by cloning the project, syncing dependencies, and starting the server in development mode. Use the following steps exactly as shown:

Step-by-step commands

# Clone the repository
git clone https://github.com/Martian-Engineering/claude-team.git
cd claude-team

# Install dependencies and prepare the environment
uv sync

# Run the server directly (for debugging)
uv run python -m claude_team_mcp

Configure Claude Code to use the MCP server

Add an MCP server reference to Claude Code so it can communicate with the manager. You can configure this globally or per project.

{
  "mcpServers": {
    "claude-team": {
      "command": "uv",
      "args": ["run", "python", "-m", "claude_team_mcp"]
    }
  }
}

Environment variables to customize behavior

Two environment variables control how Claude Code starts workers and how Codex (if used) starts inside workers, plus an optional project directory hint.

export CLAUDE_TEAM_COMMAND=happy
export CLAUDE_TEAM_CODEX_COMMAND="happy codex"
export CLAUDE_TEAM_PROJECT_DIR=/path/to/projects

Additional setup notes

If you plan to use worktrees for isolated worker branches, ensure your Git setup is accessible and that iTerm2 is running with the Python API enabled. Worktrees will be located under the manager’s worktree directory and will each have a dedicated branch.

Configuration for Claude Code

You can point Claude Code to the MCP server either globally or per project. Use the provided JSON examples to map the server name to the start command.

{
  "mcpServers": {
    "claude-team": {
      "command": "uvx",
      "args": ["--from", "claude-team-mcp@latest", "claude-team"]
    }
  }
}

Troubleshooting and tips

If you run into issues starting iTerm2 sessions, verify iTerm2 is open and that the Python API is enabled. If a worker session cannot be found, list available workers to verify their IDs or names, and ensure workers have not been closed externally.

Development

For development and testing you can sync dependencies, run tests, and start the MCP server directly to debug. Use the following commands to reproduce the development workflow.

# Sync dependencies
uv sync

# Run tests
uv run pytest

# Run the server directly (for debugging)
uv run python -m claude_team_mcp

# Install slash commands
make install-commands

Upgrading and maintenance

If you update to a new MCP version, you may need to clear tool caches and reinstall the MCP toolchain to ensure compatibility with the new server features.

Notes on usage patterns

Spawn workers with a multi-pane layout to run frontend and backend tasks in parallel. Send messages to workers individually or broadcast to all. Read logs from each worker’s JSONL file to track conversations and progress. Use idle detection to wait for workers to complete tasks before proceeding with follow-up steps.

Available tools

spawn_workers

Create workers in a new window with multi-pane layouts (single, vertical, horizontal, quad, triple_vertical)

list_workers

List all managed workers with their status

examine_worker

Get detailed status for a worker including conversation stats and last response preview

close_workers

Gracefully terminate one or more workers

discover_workers

Find existing Claude Code sessions running in iTerm2

adopt_worker

Import a discovered iTerm2 session into the managed registry

message_workers

Send a message to one or more workers with optional wait modes (none, any, all)

read_worker_logs

Get paginated conversation history from a worker’s JSONL file

annotate_worker

Add a coordinator note to a worker for visibility in listings

check_idle_workers

Quick non-blocking check if workers are idle

wait_idle_workers

Block until workers are idle with configurable mode and timeout

list_worktrees

List git worktrees created for a repository by claude-team

bd_help

Get a quick reference guide for using Beads issue tracking