Claude Octopus

Spawn multiple specialized Claude Code agents as MCP servers, each independently configured.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "claude-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "claude-octopus"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Claude Octopus

One brain, many arms.

An MCP server that wraps the Claude Agent SDK, letting you run multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.

Why

Claude Code is powerful. But one instance does everything the same way. Sometimes you want a strict code reviewer that only reads files. A test writer that defaults to TDD. A cheap quick helper on Haiku. A deep thinker on Opus.

Claude Octopus lets you spin up as many of these as you need. Same binary, different configurations. Each one shows up as a separate tool in your MCP client.

Prerequisites

Node.js >= 18
Claude Code — the Claude Agent SDK is bundled as a dependency, but it spawns Claude Code under the hood, so you need a working claude CLI installation
Anthropic API key (ANTHROPIC_API_KEY env var) or an active Claude Code OAuth session

Install

Three paths, pick whichever matches your MCP client.

npm (most direct)

Terminal

npm install claude-octopus

npx (no install needed)

Skip the install entirely — reference claude-octopus@latest in your .mcp.json and the client will fetch on demand (see Quick Start below).

MCP Registry

The server is published to the MCP Registry under the name io.github.xiaolai/claude-octopus. Registry-aware MCP clients can resolve and install it by that name without touching npm directly.

Quick Start

The fastest way to get started:

Terminal

npx claude-octopus init

This interactive wizard lets you pick a template, detects your MCP client, and writes the config for you.

Or add to your .mcp.json manually:

config.json

{
  "mcpServers": {
    "claude": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_PERMISSION_MODE": "bypassPermissions"
      }
    }
  }
}

This gives you six tools:

Tool	Purpose
`claude_code`	Send a task, get a result
`claude_code_reply`	Continue a conversation
`claude_code_timeline`	Query the workflow timeline
`claude_code_transcript`	Read full session transcripts
`claude_code_sessions`	List Claude Code session history (this project, or all)
`claude_code_report`	Generate HTML reports

That's it — you have Claude Code as a tool, with full workflow observability built in.

Multiple Agents

The real power is running several instances with different configurations:

config.json

{
  "mcpServers": {
    "code-reviewer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "code_reviewer",
        "CLAUDE_SERVER_NAME": "code-reviewer",
        "CLAUDE_DESCRIPTION": "Strict code reviewer. Finds bugs and security issues. Read-only.",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_ALLOWED_TOOLS": "Read,Grep,Glob",
        "CLAUDE_APPEND_PROMPT": "You are a strict code reviewer. Report real bugs, not style preferences.",
        "CLAUDE_EFFORT": "high"
      }
    },
    "test-writer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "test_writer",
        "CLAUDE_SERVER_NAME": "test-writer",
        "CLAUDE_DESCRIPTION": "Writes thorough tests with edge case coverage.",
        "CLAUDE_MODEL": "sonnet",
        "CLAUDE_APPEND_PROMPT": "Write tests first. Cover edge cases. TDD."
      }
    },
    "quick-qa": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "quick_qa",
        "CLAUDE_SERVER_NAME": "quick-qa",
        "CLAUDE_DESCRIPTION": "Fast answers to quick coding questions.",
        "CLAUDE_MODEL": "haiku",
        "CLAUDE_MAX_BUDGET_USD": "0.02",
        "CLAUDE_EFFORT": "low"
      }
    }
  }
}

Your MCP client now sees distinct tools for each agent — code_reviewer, test_writer, quick_qa — each purpose-built.

Multi-Agent Orchestration

Agents can coordinate through a coordinator pattern: one agent has the others as inner MCP tools via CLAUDE_MCP_SERVERS, and its system prompt drives the pipeline.

config.json

{
  "mcpServers": {
    "publishing-house": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "publishing_house",
        "CLAUDE_SERVER_NAME": "publishing-house",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_PERMISSION_MODE": "bypassPermissions",
        "CLAUDE_APPEND_PROMPT": "You are a publishing house coordinator. Dispatch tasks to your specialist agents and drive the pipeline to completion.",
        "CLAUDE_MCP_SERVERS": "{\"researcher\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"researcher\",\"CLAUDE_SERVER_NAME\":\"researcher\",\"CLAUDE_MODEL\":\"sonnet\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}},\"architect\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"architect\",\"CLAUDE_SERVER_NAME\":\"architect\",\"CLAUDE_MODEL\":\"opus\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}}}"
      }
    }
  }
}

The coordinator agent autonomously calls researcher, architect, etc. as MCP tools — fully autonomous, no human in the loop until it finishes. Every invocation is tracked in the shared timeline.

Agent Factory

Don't want to write configs by hand? Add a factory instance:

config.json

{
  "mcpServers": {
    "agent-factory": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_FACTORY_ONLY": "true",
        "CLAUDE_SERVER_NAME": "agent-factory"
      }
    }
  }
}

This exposes a single create_claude_code_mcp tool — an interactive wizard. Tell it what you want ("a strict code reviewer that only reads files") and it generates the .mcp.json entry for you, listing all available options you can customize.

In factory-only mode, no query tools are registered — just the wizard. This keeps routing clean: the factory creates agents, the agents do work.

Init Wizard

Don't want to edit JSON by hand? The init wizard gets you from zero to working in 30 seconds:

Terminal

npx claude-octopus init

Code

  Claude Octopus — init wizard

  One brain, many arms. Let's set up your agents.

Pick a template (or build your own):

  1. Code Review Team — Reviewer + test writer + security auditor
  2. Publishing House — Researcher + architect + editor + proofreader
  3. Tiered Models — Haiku for quick Q&A, Sonnet for coding, Opus for hard problems
  4. Solo Agent — Single Claude Code agent with sensible defaults
  5. Agent Factory — Interactive wizard that generates agent configs on demand
  6. Custom — describe your own agent(s)

Choice [1-6]:

It auto-detects installed MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), merges with existing config, and warns before overwriting.

Skip the menu

Terminal

npx claude-octopus init --template code-review-team
npx claude-octopus init --template tiered-models
npx claude-octopus init --template publishing-house

Templates

Five built-in templates, battle-tested and ready to use:

Template	Agents	Purpose
`code-review-team`	code-reviewer (opus), test-writer (sonnet), security-auditor (opus)	Thorough code review pipeline
`publishing-house`	researcher (sonnet), architect (opus), editor (sonnet), proofreader (haiku)	Multi-stage content/code pipeline
`tiered-models`	quick-qa (haiku), coder (sonnet), deep-thinker (opus)	Right model for the job
`solo-agent`	claude (default)	Single agent, quick setup
`factory`	agent-factory	Generates configs on demand

Each agent comes pre-tuned with appropriate model, tools, effort level, and system prompt.

Dashboard

Monitor your agents in real time:

Terminal

npx claude-octopus dashboard

Opens a local web dashboard at http://localhost:3456 with:

Live stats — total runs, invocations, cost, SDK turns, responses, errors
Recent activity — agent cards for the latest run
Run table — all runs with cost, duration, and status
Auto-refresh — SSE connection pushes updates as agents run

bash

# Custom port
npx claude-octopus dashboard --port 8080

The dashboard reads the same timeline index used by the _timeline and _report tools. No additional configuration needed.

Tools

Each non-factory instance exposes:

Tool	Purpose
`<name>`	Send a task to the agent, get a response + `session_id` + `run_id`
`<name>_reply`	Continue a previous conversation by `session_id`
`<name>_timeline`	Query the cross-agent workflow timeline
`<name>_transcript`	Retrieve full session transcript from Claude Code's storage
`<name>_sessions`	List Claude Code session history — this project by default, or all projects with `all_projects: true`
`<name>_report`	Generate a self-contained HTML report for a run or all runs

Query and reply parameters

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Claude Octopus

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "claude-octopus": { "command": "npx", "args": ["-y", "claude-octopus"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/claude-octopus?style=directory)](https://allmcps.com/mcp/claude-octopus)

HTML Embed

<a href="https://allmcps.com/mcp/claude-octopus"><img src="https://allmcps.com/api/badge/claude-octopus?style=directory" alt="Claude Octopus on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Claude Octopus →Install in Claude Desktop Install in Cursor Install in VS Code

Claude Octopus

Spawn multiple specialized Claude Code agents as MCP servers, each independently configured.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "claude-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "claude-octopus"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Claude Octopus

One brain, many arms.

An MCP server that wraps the Claude Agent SDK, letting you run multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.

Why

Claude Octopus lets you spin up as many of these as you need. Same binary, different configurations. Each one shows up as a separate tool in your MCP client.

Prerequisites

Node.js >= 18
Claude Code — the Claude Agent SDK is bundled as a dependency, but it spawns Claude Code under the hood, so you need a working claude CLI installation
Anthropic API key (ANTHROPIC_API_KEY env var) or an active Claude Code OAuth session

Install

Three paths, pick whichever matches your MCP client.

npm (most direct)

Terminal

npm install claude-octopus

npx (no install needed)

Skip the install entirely — reference claude-octopus@latest in your .mcp.json and the client will fetch on demand (see Quick Start below).

MCP Registry

The server is published to the MCP Registry under the name io.github.xiaolai/claude-octopus. Registry-aware MCP clients can resolve and install it by that name without touching npm directly.

Quick Start

The fastest way to get started:

Terminal

npx claude-octopus init

This interactive wizard lets you pick a template, detects your MCP client, and writes the config for you.

Or add to your .mcp.json manually:

config.json

{
  "mcpServers": {
    "claude": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_PERMISSION_MODE": "bypassPermissions"
      }
    }
  }
}

This gives you six tools:

Tool	Purpose
`claude_code`	Send a task, get a result
`claude_code_reply`	Continue a conversation
`claude_code_timeline`	Query the workflow timeline
`claude_code_transcript`	Read full session transcripts
`claude_code_sessions`	List Claude Code session history (this project, or all)
`claude_code_report`	Generate HTML reports

That's it — you have Claude Code as a tool, with full workflow observability built in.

Multiple Agents

The real power is running several instances with different configurations:

config.json

{
  "mcpServers": {
    "code-reviewer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "code_reviewer",
        "CLAUDE_SERVER_NAME": "code-reviewer",
        "CLAUDE_DESCRIPTION": "Strict code reviewer. Finds bugs and security issues. Read-only.",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_ALLOWED_TOOLS": "Read,Grep,Glob",
        "CLAUDE_APPEND_PROMPT": "You are a strict code reviewer. Report real bugs, not style preferences.",
        "CLAUDE_EFFORT": "high"
      }
    },
    "test-writer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "test_writer",
        "CLAUDE_SERVER_NAME": "test-writer",
        "CLAUDE_DESCRIPTION": "Writes thorough tests with edge case coverage.",
        "CLAUDE_MODEL": "sonnet",
        "CLAUDE_APPEND_PROMPT": "Write tests first. Cover edge cases. TDD."
      }
    },
    "quick-qa": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "quick_qa",
        "CLAUDE_SERVER_NAME": "quick-qa",
        "CLAUDE_DESCRIPTION": "Fast answers to quick coding questions.",
        "CLAUDE_MODEL": "haiku",
        "CLAUDE_MAX_BUDGET_USD": "0.02",
        "CLAUDE_EFFORT": "low"
      }
    }
  }
}

Your MCP client now sees distinct tools for each agent — code_reviewer, test_writer, quick_qa — each purpose-built.

Multi-Agent Orchestration

Agents can coordinate through a coordinator pattern: one agent has the others as inner MCP tools via CLAUDE_MCP_SERVERS, and its system prompt drives the pipeline.

config.json

{
  "mcpServers": {
    "publishing-house": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "publishing_house",
        "CLAUDE_SERVER_NAME": "publishing-house",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_PERMISSION_MODE": "bypassPermissions",
        "CLAUDE_APPEND_PROMPT": "You are a publishing house coordinator. Dispatch tasks to your specialist agents and drive the pipeline to completion.",
        "CLAUDE_MCP_SERVERS": "{\"researcher\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"researcher\",\"CLAUDE_SERVER_NAME\":\"researcher\",\"CLAUDE_MODEL\":\"sonnet\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}},\"architect\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"architect\",\"CLAUDE_SERVER_NAME\":\"architect\",\"CLAUDE_MODEL\":\"opus\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}}}"
      }
    }
  }
}

The coordinator agent autonomously calls researcher, architect, etc. as MCP tools — fully autonomous, no human in the loop until it finishes. Every invocation is tracked in the shared timeline.

Agent Factory

Don't want to write configs by hand? Add a factory instance:

config.json

{
  "mcpServers": {
    "agent-factory": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_FACTORY_ONLY": "true",
        "CLAUDE_SERVER_NAME": "agent-factory"
      }
    }
  }
}

In factory-only mode, no query tools are registered — just the wizard. This keeps routing clean: the factory creates agents, the agents do work.

Init Wizard

Don't want to edit JSON by hand? The init wizard gets you from zero to working in 30 seconds:

Terminal

npx claude-octopus init

Code

  Claude Octopus — init wizard

  One brain, many arms. Let's set up your agents.

Pick a template (or build your own):

  1. Code Review Team — Reviewer + test writer + security auditor
  2. Publishing House — Researcher + architect + editor + proofreader
  3. Tiered Models — Haiku for quick Q&A, Sonnet for coding, Opus for hard problems
  4. Solo Agent — Single Claude Code agent with sensible defaults
  5. Agent Factory — Interactive wizard that generates agent configs on demand
  6. Custom — describe your own agent(s)

Choice [1-6]:

It auto-detects installed MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), merges with existing config, and warns before overwriting.

Skip the menu

Terminal

npx claude-octopus init --template code-review-team
npx claude-octopus init --template tiered-models
npx claude-octopus init --template publishing-house

Templates

Five built-in templates, battle-tested and ready to use:

Template	Agents	Purpose
`code-review-team`	code-reviewer (opus), test-writer (sonnet), security-auditor (opus)	Thorough code review pipeline
`publishing-house`	researcher (sonnet), architect (opus), editor (sonnet), proofreader (haiku)	Multi-stage content/code pipeline
`tiered-models`	quick-qa (haiku), coder (sonnet), deep-thinker (opus)	Right model for the job
`solo-agent`	claude (default)	Single agent, quick setup
`factory`	agent-factory	Generates configs on demand

Each agent comes pre-tuned with appropriate model, tools, effort level, and system prompt.

Dashboard

Monitor your agents in real time:

Terminal

npx claude-octopus dashboard

Opens a local web dashboard at http://localhost:3456 with:

Live stats — total runs, invocations, cost, SDK turns, responses, errors
Recent activity — agent cards for the latest run
Run table — all runs with cost, duration, and status
Auto-refresh — SSE connection pushes updates as agents run

bash

# Custom port
npx claude-octopus dashboard --port 8080

The dashboard reads the same timeline index used by the _timeline and _report tools. No additional configuration needed.

Tools

Each non-factory instance exposes:

Tool	Purpose
`<name>`	Send a task to the agent, get a response + `session_id` + `run_id`
`<name>_reply`	Continue a previous conversation by `session_id`
`<name>_timeline`	Query the cross-agent workflow timeline
`<name>_transcript`	Retrieve full session transcript from Claude Code's storage
`<name>_sessions`	List Claude Code session history — this project by default, or all projects with `all_projects: true`
`<name>_report`	Generate a self-contained HTML report for a run or all runs

Query and reply parameters

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Claude Octopus

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "claude-octopus": { "command": "npx", "args": ["-y", "claude-octopus"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/claude-octopus?style=directory)](https://allmcps.com/mcp/claude-octopus)

HTML Embed

<a href="https://allmcps.com/mcp/claude-octopus"><img src="https://allmcps.com/api/badge/claude-octopus?style=directory" alt="Claude Octopus on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Claude Octopus →Install in Claude Desktop Install in Cursor Install in VS Code