# claude-octopus

Runs multiple customized Claude Code instances as MCP tools with dedicated model tiers and tool permissions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 21
- Author: xiaolai
- License: ISC · policy=link-only · description only; the file stays with the author
- Source: https://github.com/xiaolai/claude-octopus
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/claude-octopus

## What it does

This MCP server wraps Anthropic's Claude Agent SDK to run multiple Claude Code processes as separate tools. Each agent keeps its own configuration. For example, a code reviewer can run on Opus with read-only file access, while routine queries route to Haiku. Default tools let you run tasks and generate HTML summary reports.

Pipelines can use the coordinator pattern through `CLAUDE_MCP_SERVERS`. Setup is straightforward. The package provides an interactive wizard via `npx claude-octopus init` and a factory tool named `create_claude_code_mcp`. You need Node.js 18 or higher and an existing `claude` CLI installation. Authentication relies on `ANTHROPIC_API_KEY` or an active OAuth login.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ANTHROPIC_API_KEY`, `CLAUDE_TOOL_NAME`, `CLAUDE_MODEL`, `CLAUDE_PERMISSION_MODE`, `CLAUDE_ALLOWED_TOOLS`, `CLAUDE_APPEND_PROMPT`, `CLAUDE_FACTORY_ONLY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env CLAUDE_TOOL_NAME=<CLAUDE_TOOL_NAME> --env CLAUDE_MODEL=<CLAUDE_MODEL> --env CLAUDE_PERMISSION_MODE=<CLAUDE_PERMISSION_MODE> --env CLAUDE_ALLOWED_TOOLS=<CLAUDE_ALLOWED_TOOLS> --transport stdio claude-octopus -- npx -y claude-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add claude-octopus --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env CLAUDE_TOOL_NAME=<CLAUDE_TOOL_NAME> --env CLAUDE_MODEL=<CLAUDE_MODEL> --env CLAUDE_PERMISSION_MODE=<CLAUDE_PERMISSION_MODE> --env CLAUDE_ALLOWED_TOOLS=<CLAUDE_ALLOWED_TOOLS> -- npx -y claude-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "claude-octopus": {
            "command": "npx",
            "args": [
                "-y",
                "claude-octopus"
            ],
            "env": {
                "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
                "CLAUDE_TOOL_NAME": "<CLAUDE_TOOL_NAME>",
                "CLAUDE_MODEL": "<CLAUDE_MODEL>",
                "CLAUDE_PERMISSION_MODE": "<CLAUDE_PERMISSION_MODE>",
                "CLAUDE_ALLOWED_TOOLS": "<CLAUDE_ALLOWED_TOOLS>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "claude-octopus": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "claude-octopus"
            ],
            "env": {
                "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
                "CLAUDE_TOOL_NAME": "<CLAUDE_TOOL_NAME>",
                "CLAUDE_MODEL": "<CLAUDE_MODEL>",
                "CLAUDE_PERMISSION_MODE": "<CLAUDE_PERMISSION_MODE>",
                "CLAUDE_ALLOWED_TOOLS": "<CLAUDE_ALLOWED_TOOLS>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e CLAUDE_TOOL_NAME=<CLAUDE_TOOL_NAME> -e CLAUDE_MODEL=<CLAUDE_MODEL> -e CLAUDE_PERMISSION_MODE=<CLAUDE_PERMISSION_MODE> -e CLAUDE_ALLOWED_TOOLS=<CLAUDE_ALLOWED_TOOLS> claude-octopus npx -y claude-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- allocate specific model tiers like Haiku or Opus to different subtasks
- restrict code review agents to read-only tool permissions
- coordinate nested worker pipelines without human intervention
- inspect execution history and generate HTML session reports

## Example prompts
- Inspect `src/auth.ts` for vulnerabilities using the `code_reviewer` tool
- Generate a summary of the latest workflow run with `claude_code_report`
- Write unit tests for the checkout module using `test_writer`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md