claude-cli-mcp
Allows OpenAI Codex CLI to delegate work to Claude Code as a sub-agent via MCP tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-cli-mcp write a Python script to fetch and display the current weather from OpenWeatherMap API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bridge Anthropic Claude Code CLI to any MCP client
English | 한국어
npm · GitHub · Issues
Overview
An MCP (Model Context Protocol) server that wraps Anthropic Claude Code CLI as tools. Lets MCP clients like Claude Desktop, Cursor, Windsurf, and Claude Code itself invoke headless Claude Code sessions.
Forked from
@nayagamez/codex-cli-mcp. Same architecture (stdio MCP, stream-json parser, idle timeout, progress notifications) — adapted forclaudeCLI semantics.
Related MCP server: claude-code-mcp
Prerequisites
1. Install Claude Code CLI
The recommended method is the native installer (Node.js not required, auto-updates):
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdOther options: brew install --cask claude-code · winget install Anthropic.ClaudeCode · apt/dnf/apk via downloads.claude.ai · npm install -g @anthropic-ai/claude-code (advanced).
Windows native install requires Git for Windows. See Claude Code setup docs for details.
2. Authenticate
Run claude and follow the browser prompt to sign in. Requires a Pro, Max, Team, Enterprise, or API plan.
For headless / CI:
export ANTHROPIC_API_KEY="sk-ant-..."See Authentication docs.
3. Node.js (npm) installed
The Setup snippets below invoke this server with npx -y (ships with npm). Verify Node ≥ 18:
node --version
npm --versionIf missing, install Node.js LTS from nodejs.org.
If you'd rather use Bun's bunx (avoids Windows .cmd shim issues), see the installation guide §5.7 for the alternative TOML block.
Tools
claude
Start a new Claude Code session.
Parameter | Type | Required | Description |
| string | Yes | The prompt to send |
| string | No | Model id or alias ( |
| enum | No |
|
| enum | No |
|
| string | No | Working directory |
| string[] | No | Additional read/write directories ( |
| string[] | No | e.g. |
| string[] | No | Tools that may not be used |
| string | No | Text appended to default system prompt |
| string[] | No | MCP server config files or JSON strings |
| number | No | Limit agentic turns (headless safety stop) |
| boolean | No |
|
| number | No | Idle timeout in ms (default: |
The response includes a Session ID that can be passed to claude-reply.
claude-reply
Continue an existing Claude Code session.
Parameter | Type | Required | Description |
| string | Yes | Follow-up prompt |
| string | Yes | Session ID from a previous |
| No | Same as | |
| boolean | No | Create a new session ID instead of reusing the original ( |
No
cwdparameter. Sessions are tied to the directory they were started in (Claude Code issue #5768). Run from the original cwd.
⚠️ Known Issues & Warnings
bypassPermissionsis the default — Matchescodex --full-autoparity. Bypass mode has known instability (issue #39523) where protected directory writes still prompt and the mode can reset mid-session. For sensitive workspaces usepermissionMode: "acceptEdits"or"auto".Resume requires the original cwd — Sessions cannot be moved across directories. Same-cwd execution is the user's responsibility (issue #5768).
Windows native CLI bug — Claude Code on Windows native may exit silently with no output, hang, or report
Query closed before response received(issue #50616). Recommended fallback: WSL.bare: truebreaks OAuth —--bareskips OAuth and keychain reads. Authentication must come fromANTHROPIC_API_KEYorapiKeyHelper. Pro/Max OAuth users must keepbare: false(the default).--bareis the future default for-p— Anthropic has stated--barewill become the default for-pin a future release (headless docs). v0.1 explicitly defaults tobare: falsefor OAuth compatibility; behavior may need to be revisited.
Setup
The primary use case is OpenAI Codex CLI delegating work to Claude Code as a sub-agent. Cursor and Windsurf are also supported. Calling this server from Claude Code itself is not useful (Claude calling Claude).
For Humans
Copy the prompt below and paste it into your LLM agent (Codex, Cursor, Windsurf, etc.) — it will install and configure everything automatically:
Install and configure @nayagamez/claude-cli-mcp by following: https://raw.githubusercontent.com/nayagamez/claude-cli-mcp/main/docs/guide/installation.mdOr set it up manually — see Manual Setup below.
For LLM Agents
curl -s https://raw.githubusercontent.com/nayagamez/claude-cli-mcp/main/docs/guide/installation.mdManual Setup
Examples below use
npx -yas the default runner. If you'd rather use Bun'sbunx, see installation guide §5.7.
Codex CLI
Edit ~/.codex/config.toml (global) or .codex/config.toml (project-scoped, trusted projects only):
[mcp_servers.claude-cli-mcp]
command = "npx"
args = ["-y", "@nayagamez/claude-cli-mcp"]
# Codex defaults (10s / 60s) are too short for npx cold install +
# Claude Code first response. Do not omit these.
startup_timeout_sec = 30
tool_timeout_sec = 600Restart Codex to load the server. See installation guide for project-scope and trusted-project notes.
Cursor / Windsurf
Add to the appropriate MCP config (.cursor/mcp.json, ~/.cursor/mcp.json, .windsurf/mcp.json, etc.):
{
"mcpServers": {
"claude-cli-mcp": {
"command": "npx",
"args": ["-y", "@nayagamez/claude-cli-mcp"]
}
}
}Progress Notifications
The server sends MCP progress notifications in real-time as Claude processes your request:
[5s] Session started (<id>, model: claude-sonnet-4-6)— init received[12s] Tool use: Bash— agent invoked a tool[18s] Message: Refactoring the auth module...— assistant text[24s] Retry 2/3 in 1000ms (rate_limit)—system/api_retryevent[25s] Result: success (24230ms, $0.0142)— final result
Idle-based Timeout
Timeout is idle-based: the timer resets on every event. Long-running tasks with continuous activity never time out; truly stuck processes are killed after the configured idle period.
Default: 10 minutes
Override per-call via
timeout, or globally viaCLAUDE_TIMEOUT_MS
Environment Variables
Variable | Default | Description |
|
| Path to the Claude Code CLI binary |
|
| Idle timeout for child Claude process |
| (unset) | Set to enable debug logging to stderr |
The server automatically scrubs the following env vars from the spawned child to prevent parent Claude Code state from leaking into headless invocations:
CLAUDECODE,CLAUDE_CODE_SIMPLE(officially documented parent-detection signals)CLAUDE_CODE_ENTRYPOINT,CLAUDE_CODE_SSE_PORT,CLAUDE_PROJECT_DIR(observed contributors to parent stop-hook injection)
ANTHROPIC_API_KEY, apiKeyHelper, and Bedrock/Vertex/Foundry credentials are preserved.
How It Works
MCP Client → Tool Call (claude / claude-reply)
→ Spawn `claude -p --output-format stream-json --verbose ...`
→ Pipe a stream-json user envelope into stdin
→ Parse JSONL events from stdout
→ Send progress notifications on each event (idle timer resets)
→ Return aggregated result + session idMCP client sends
claudeorclaude-replytool callServer spawns
claudewith-p,--output-format stream-json,--input-format stream-json,--verbose, plus user-specified flagsPrompt is delivered as a single-line user envelope on stdin (avoids Windows 8191-char
cmd.exelimit)stream-json events are parsed in real time (
system/init,system/api_retry,system/plugin_install,assistant,user,result,rate_limit_event)Progress notifications are sent on every event; idle timer resets
Final result includes session id, messages, tool uses, structured error, usage, and cost
License
MIT
Available Tools
2 toolsclaudeA
Run a Claude Code CLI session. Executes claude -p --output-format stream-json as a subprocess and returns the result.
Use this tool to start a new coding task with Claude Code. The response includes a Session ID that can be used with the claude-reply tool to continue the conversation.
WARNING: defaults to permission mode bypassPermissions (parity with codex --full-auto). Use a safer mode (e.g. acceptEdits or auto) for sensitive workspaces.
Inputs: prompt (required), model, effort, permissionMode, +9 more.
claude-replyA
Continue a Claude Code CLI conversation by providing the session ID from a previous claude call and a follow-up prompt.
Uses claude --resume <session-id> to load the previous session and continue.
NOTE: Sessions are tied to the directory they were started in (Claude Code issue #5768). The MCP server cannot change the resumed session's working directory — make sure the host process runs from the original cwd, otherwise the session may not be found.
Inputs: prompt (required), sessionId (required), model, effort, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: 'claude' starts a new Claude Code CLI session, while 'claude-reply' continues an existing session using a session ID. There is no overlap or ambiguity.
Both tool names use a consistent lowercase-with-hyphen pattern ('claude' and 'claude-reply'), where the first is a base command and the second adds a modifier. The naming is predictable and clear.
With only two tools, the set is minimal but sufficient for starting and continuing Claude Code sessions. The count is slightly low but reasonable given the focused scope of the server.
The server covers the essential actions (starting and continuing sessions) but lacks tools for explicitly ending sessions, listing active sessions, or changing session parameters. The absence of session management creates a notable gap.
Maintenance
Related MCP Connectors
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal MCP server that wraps the headless Claude Code CLI as MCP tools, providing stateless access to Claude's coding capabilities through prompt-based interactions. It enables users to execute Claude Code commands with various prompt formats and structured outputs directly from MCP clients.3MIT
- AlicenseAqualityDmaintenanceWraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.493 npm21MIT
- FlicenseNot gradedqualityDmaintenanceExposes Claude Code's file editing, command execution, and test running capabilities as composable MCP tools for any MCP-compatible host, enabling code operations via a stateless bridge.-
- FlicenseNot gradedqualityCmaintenanceEnables ISLI agents and MCP clients to dispatch natural-language coding and terminal tasks to a locally-installed Claude Code CLI, supporting both one-shot execution and persistent sessions with workspace and security controls.-