claude-cli-mcp

<div align="center">

<picture> <img alt="claude-cli-mcp" src="docs/images/banner.svg" width="100%"> </picture>

Bridge Anthropic Claude Code CLI to any MCP client

English | 한국어

<a href="https://www.npmjs.com/package/@nayagamez/claude-cli-mcp">npm</a> · <a href="https://github.com/nayagamez/claude-cli-mcp">GitHub</a> · <a href="https://github.com/nayagamez/claude-cli-mcp/issues">Issues</a>

</div>

---

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 for claude CLI semantics.

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.cmd

Other 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 --version

If 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
prompt	string	Yes	The prompt to send
model	string	No	Model id or alias (sonnet, opus, haiku, or full id)
effort	enum	No	low, medium, high, xhigh, max
permissionMode	enum	No	default, plan, acceptEdits, auto, dontAsk, bypassPermissions (default: bypassPermissions)
cwd	string	No	Working directory
addDirs	string[]	No	Additional read/write directories (--add-dir)
allowedTools	string[]	No	e.g. ["Bash(git *)", "Edit"]
disallowedTools	string[]	No	Tools that may not be used
appendSystemPrompt	string	No	Text appended to default system prompt
mcpConfig	string[]	No	MCP server config files or JSON strings
maxTurns	number	No	Limit agentic turns (headless safety stop)
bare	boolean	No	--bare mode (skip hooks/skills/plugins/MCP). Requires API key
timeout	number	No	Idle timeout in ms (default: 600000)

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
prompt	string	Yes	Follow-up prompt
sessionId	string	Yes	Session ID from a previous claude call
model, effort, permissionMode, allowedTools, disallowedTools, appendSystemPrompt, mcpConfig, maxTurns, bare, timeout		No	Same as claude
forkSession	boolean	No	Create a new session ID instead of reusing the original (--fork-session)

No cwd parameter. Sessions are tied to the directory they were started in (Claude Code issue #5768). Run from the original cwd.

⚠️ Known Issues & Warnings

1. bypassPermissions is the default — Matches codex --full-auto parity. Bypass mode has known instability (issue #39523) where protected directory writes still prompt and the mode can reset mid-session. For sensitive workspaces use permissionMode: "acceptEdits" or "auto".
2. Resume requires the original cwd — Sessions cannot be moved across directories. Same-cwd execution is the user's responsibility (issue #5768).
3. 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.
4. bare: true breaks OAuth — --bare skips OAuth and keychain reads. Authentication must come from ANTHROPIC_API_KEY or apiKeyHelper. Pro/Max OAuth users must keep bare: false (the default).
5. --bare is the future default for -p — Anthropic has stated --bare will become the default for -p in a future release (headless docs). v0.1 explicitly defaults to bare: false for 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.md

Or 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.md

Manual Setup

Examples below use npx -y as the default runner. If you'd rather use Bun's bunx, 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 = 600

Restart 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_retry event
• [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 via CLAUDE_TIMEOUT_MS

Environment Variables

Variable	Default	Description
CLAUDE_CLI_PATH	claude	Path to the Claude Code CLI binary
CLAUDE_TIMEOUT_MS	600000 (10 min)	Idle timeout for child Claude process
CLAUDE_MCP_DEBUG	(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 id

1. MCP client sends claude or claude-reply tool call
2. Server spawns claude with -p, --output-format stream-json, --input-format stream-json, --verbose, plus user-specified flags
3. Prompt is delivered as a single-line user envelope on stdin (avoids Windows 8191-char cmd.exe limit)
4. stream-json events are parsed in real time (system/init, system/api_retry, system/plugin_install, assistant, user, result, rate_limit_event)
5. Progress notifications are sent on every event; idle timer resets
6. Final result includes session id, messages, tool uses, structured error, usage, and cost

License

MIT