Log inSubmit server
Claude Octopus logo

Claude Octopus

Runs multiple independently configured Claude Code agents as MCP tools, with session history, timelines, transcripts, and reports.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Claude Octopus

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "claude-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "claude-octopus"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y claude-octopus

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 9d ago.

Overview

The claude-octopus MCP server wraps the Claude Agent SDK and exposes specialized Claude Code agents through MCP. Each agent can use its own model, tools, system prompt, permissions, effort level, and budget. Use it when one coding assistant is not enough, such as for separate review, testing, research, or orchestration roles. It also provides an initialization wizard, an agent factory, and a local dashboard for monitoring runs.

Use cases

  • Create separate code-review and test-writing agents
  • Delegate work among specialized Claude Code agents
  • Tune models and budgets for different coding tasks
  • Inspect agent runs through timelines and transcripts
  • Generate MCP configurations with the init wizard

Key features

  • Multiple independently configured Claude Code agents
  • Task continuation with session IDs
  • Workflow timelines and session transcripts
  • HTML report generation
  • Agent factory for generated configurations
  • Local monitoring dashboard

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

5/5 checks healthy over the last 46d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · claude-octopus (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars21Stargazers on the source repository.
npm downloads249Package downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Claude Octopus works

What claude-octopus does

The claude-octopus MCP server turns Claude Code agents into MCP tools. A single instance can handle tasks through a configured agent, while multiple instances can appear as separate tools with different names and responsibilities. For example, one agent can review code with read-only tools, another can write tests, and a third can answer quick questions with a lower-cost model.

Each agent may be configured with a model, tool allowlist, system-prompt addition, permission mode, effort level, and maximum budget. The server also supports a coordinator pattern: one agent can receive other Claude Octopus instances as inner MCP tools and delegate work to them.

How it works

The package launches through Node.js and uses the Claude Agent SDK, which starts the Claude Code CLI underneath. MCP clients connect to the configured process and receive agent-specific tools. A regular instance exposes a task tool, a reply tool for continuing a session, timeline and transcript queries, session-history listing, and HTML report generation.

Agents return session and run identifiers that can be used to continue conversations or inspect execution details. Coordinated agent calls are recorded in a shared timeline. The optional dashboard reads that timeline and serves a local web interface with run statistics, recent activity, costs, durations, statuses, and error information. Server-sent events provide live updates while agents run.

Setup and configuration

The claude-octopus MCP server requires Node.js 18 or newer and a working claude CLI installation. Authentication can use ANTHROPIC_API_KEY or an active Claude Code OAuth session. Install it from npm, invoke it with npx, or resolve it through the MCP Registry under io.github.xiaolai/claude-octopus.

Run npx claude-octopus init to use the interactive setup wizard. It can select a built-in template, detect Claude Desktop, Claude Code, Cursor, or Windsurf, merge with an existing configuration, and warn before overwriting. Templates cover a solo agent, code-review team, publishing-house workflow, tiered models, and an agent factory.

Configuration is supplied through environment variables in the MCP client configuration. Important settings include the tool and server names, model, description, allowed tools, appended prompt, permission mode, effort, maximum budget, and nested MCP server definitions. The dashboard starts with npx claude-octopus dashboard and accepts a custom port.

Tools and capabilities

A non-factory instance provides these capabilities:

  • Send a task to the configured agent and receive a result.
  • Continue an existing conversation with a session ID.
  • Query the workflow timeline.
  • Read complete session transcripts.
  • List Claude Code sessions for the current project or all projects.
  • Generate HTML reports.

Factory-only mode exposes create_claude_code_mcp instead of query tools. That wizard creates configuration for new agents from a natural-language description and presents available options for customization.

Limitations and notes

The Claude Agent SDK is bundled, but the underlying Claude Code CLI must still be installed and usable. An API key is not the only authentication option because an active Claude Code OAuth session is also supported. Multiple agents require separate MCP configuration entries unless they are created through the factory. The coordinator pattern requires nested server configuration in CLAUDE_MCP_SERVERS.

Read the full README View source on GitHub

Reviews

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

Frequently Asked Questions about Claude Octopus

claude-octopus is an MCP server that connects MCP clients to the Claude Agent SDK and Claude Code CLI. Its main tools send tasks to configured agents, continue sessions, inspect timelines and transcripts, list session history, and generate HTML reports. Multiple instances can expose specialized agents with different models, prompts, and tool permissions.

Install it with npm, run it through npx, or use an MCP Registry-aware client to resolve `io.github.xiaolai/claude-octopus`. The quickest setup is `npx claude-octopus init`, which creates client configuration from a selected template.

It requires Node.js 18 or newer, a working Claude Code CLI installation, and authentication through either `ANTHROPIC_API_KEY` or an active Claude Code OAuth session. The Claude Agent SDK is included as a dependency, but the CLI still runs underneath.

Yes, claude-octopus supports Cursor configuration. The init wizard detects Cursor and can write or merge the MCP configuration, alongside support for Claude Desktop, Claude Code, and Windsurf.

Create multiple MCP configuration entries, assigning each instance its own tool name, model, prompt, permissions, and other environment settings. Alternatively, configure factory-only mode and use `create_claude_code_mcp` to generate agent entries interactively.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

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 PreviewClaude Octopus AllMCPs Directory Badge
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>