claude-octopus — Claude Code MCP server: how to install
Runs multiple customized Claude Code instances as MCP tools with dedicated model tiers and tool permissions.
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-octopusWhat claude-octopus 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.
What it helps with
- 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 for the agent
- Inspect
src/auth.tsfor vulnerabilities using thecode_reviewertool - Generate a summary of the latest workflow run with
claude_code_report - Write unit tests for the checkout module using
test_writer
How to install claude-octopus
Platform CLI
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-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
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-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about claude-octopus
How do I install claude-octopus in Claude Code?
Run claude mcp add claude-octopus -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -- npx -y claude-octopus. To configure custom agent behavior, include relevant --env flags during setup.
What does claude-octopus do?
It exposes Claude Code instances as MCP tools so you can run several specialized agents inside your MCP client. Each instance operates with its own system prompt, budget cap, and allowed tools.
What are the prerequisites for running claude-octopus?
You need Node.js 18 or newer, a working local claude CLI installation, and an ANTHROPIC_API_KEY or active Claude Code OAuth session.
