claude-wrap-mcp
An MCP server that lets an agent spawn and
drive real Claude Code sessions, so Claude Code can run a fleet of Claude Code
sub-agents. Built on claude-wrap.
Needs Node ≥ 18 and the claude CLI on your PATH. Headless sessions work
everywhere; attaching to visible terminal windows is Windows-first.
Install
npm install -g claude-wrap-mcp
claude mcp add claude-wrap -- claude-wrap-mcp
Or in .mcp.json / claude_desktop_config.json:
{
"mcpServers": {
"claude-wrap": { "command": "npx", "args": ["-y", "claude-wrap-mcp"] }
}
}
Tools
| Tool | What it does |
|---|---|
claude_spawn | Start a session in an absolute cwd. Returns a sessionId. |
claude_ask | Send a prompt, wait for idle, return the transcript tail + parsed state. |
claude_send | Send raw input (text / line / key) without waiting — for long tasks. |
claude_status | Busy, mode, tokens, pending permission prompt, todos, last 5 tool names. |
claude_tool_calls | Page through the session's tool calls. Ids + names by default. |
claude_tool_result | One tool call by id: its args and result. |
claude_snapshot | The rendered transcript lines. |
claude_list | Every session, spawned here or discovered, with its backend, tmux attach command and lineage. |
claude_resolve_permission | approve / deny a pending permission prompt. |
claude_stop | Shut down a session this server spawned or adopted (kills a tmux session). |
There is a second family, claudep_*, that drives non-interactive claude -p
sessions and returns structured JSON, tool calls, usage and cost.
Two things worth knowing:
- Permission prompts are surfaced, not bypassed. When
claude_askorclaude_statusreports apermissionPrompt, answer it withclaude_resolve_permission. - Tool calls are paged, not dumped. A status poll stays cheap because it
carries only names;
claude_tool_callslists the rest andclaude_tool_resultfetches one call's output by id.
Sessions in tmux (Linux/macOS)
Set CLAUDE_WRAP_BACKEND=tmux in the server's environment (e.g. box-wide).
claude_* sessions then run in tmux sessions, with no change to the MCP
config:
- they outlive this server: on shutdown it leaves them running, and anyone
can
tmux attach(the command is inclaude_spawn/claude_list). SetCLAUDE_WRAP_TMUX_ON_EXIT=killto stop them with the server instead; - any server adopts them: pass a tmux session name (as listed) as
sessionIdand the session is attached in-process, with full parsed state; - lineage: a session spawned from inside an agent that has
TASK_ID/AGENT_IDset records that task and parent.claude_listshows it, and the registry entry (CLAUDE_WRAP_REGISTRY, one file per session when it's a directory) carries it for a supervisor.
See claude-wrap's README ("tmux backend") for the knobs and the entry format.
Develop
pnpm install
pnpm --filter claude-wrap-mcp build
pnpm --filter claude-wrap-mcp test
License
MIT © Alex Kaffetzakis