Claude Code Mcp

claude-code-mcp

[](https://www.npmjs.com/package/@leo000001/claude-code-mcp) [](https://github.com/xihuai18/claude-code-mcp/blob/HEAD/LICENSE) [](https://nodejs.org)

MCP server that wraps Claude Code (Claude Agent SDK) as tools, enabling any MCP client to invoke Claude Code for autonomous coding tasks. Designed for local use — the MCP server and client are expected to run on the same machine. It works especially well with OpenCode/Codex-style clients that prefer async polling and explicit permission decisions.

Inspired by the Codex MCP design philosophy — minimum tools, maximum capability.

This package is CLI-first: it is intended to run as an MCP server process (npx @leo000001/claude-code-mcp), not as a stable programmatic library API.

Visibility Boundary

Not every piece of documentation below is visible to an MCP-connected coding agent.

• Usually visible to the agent: MCP tool names, tool descriptions, input field descriptions, and MCP resources that the client explicitly reads.
• Not safe to assume visible: this README.md, docs/DESIGN.md, AGENTS.md, and other repository files unless the client or orchestrator copies that content into the model context.
• Authoring rule: keep protocol-critical calling rules in tool descriptions and MCP resources first; mirror them in README for humans, but do not rely on README alone.

In practice, the most important runtime rules are duplicated in the claude_code* tool descriptions and the quickstart / gotchas / compat-report resources so async polling clients can succeed even when they never read this file.

Features

• 4 tools covering the full agent lifecycle: start, continue, check/poll, manage
• Read-only MCP resources for server info, internal tool catalog, and compatibility diagnostics
• Session management with resume and fork support
• Local settings loaded by default — automatically reads ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, and CLAUDE.md so the agent behaves like your local Claude Code CLI
• Async permissions — allow/deny lists + explicit approvals via claude_code_check
• Custom subagents — define specialized agents per session
• Cost tracking — per-session turn and cost accounting
• Session cancellation via AbortController
• Auto-cleanup — 30-minute idle timeout for expired sessions
• Security — callers control tool permissions via allow/deny lists + explicit permission decisions

See CHANGELOG.md for release history.

Prerequisites

• Node.js >= 18 is required.
• Same-platform deployment — this MCP server is designed to run on the same machine as the MCP client. It communicates via stdio (child process), reads local Claude configuration files from ~/.claude/, and accesses the local file system directly. Remote deployment is not supported.

This MCP server uses the @anthropic-ai/claude-agent-sdk package, which bundles its own Claude Code CLI (cli.js). When no explicit pathToClaudeCodeExecutable is provided, this server now prefers a detected local claude command, then claude-internal, and falls back to the SDK-bundled CLI if neither is found.

• The SDK bundles a Claude Code CLI; its version generally tracks the SDK package version, but the exact scheme is not guaranteed
• Default executable resolution order is: request-level pathToClaudeCodeExecutable -> CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH -> CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND -> auto-detected claude -> auto-detected claude-internal -> SDK-bundled CLI
• Configuration is shared — the bundled CLI reads API keys and settings from ~/.claude/, same as the system-installed claude
• All local settings are loaded by default — unlike the raw SDK (which defaults to isolation mode), this MCP server loads user, project, and local settings automatically, including CLAUDE.md project context. Pass advanced.settingSources: [] to opt out
• You must have Claude Code configured (API key set up) before using this MCP server: see Claude Code documentation

> Note: The bundled CLI version may differ from your system-installed claude. To check: claude --version (system) vs npm ls @anthropic-ai/claude-agent-sdk (SDK).

Quick Start

As an MCP server (recommended)

Install globally or use npx (no install needed):

npm install -g @leo000001/claude-code-mcp

Add to your MCP client configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "claude-code": {
      "command": "npx",
      "args": ["-y", "@leo000001/claude-code-mcp"]
    }
  }
}

> Some clients cache tool/resource metadata at connect-time. This server emits notifications/tools/list_changed and notifications/resources/list_changed after runtime tool discovery so clients can refresh both the claude_code tool description and internal-tools resource.

Anthropic Claude Code CLI (as an MCP client)

claude mcp add --transport stdio claude-code -- npx -y @leo000001/claude-code-mcp

OpenCode

Add a local MCP entry in opencode.json / opencode.jsonc (project) or the global OpenCode config under ~/.config/opencode/:

{
  "mcp": {
    "claude-code": {
      "type": "local",
      "command": ["npx", "-y", "@leo000001/claude-code-mcp"],
      "enabled": true
    }
  }
}

OpenCode tip: start with claude_code, keep the returned sessionId, then background-poll with claude_code_check. When approvals appear, decision: "allow_for_session" is usually the best UX because it reduces repeated prompts for the same tool in a session.

> OpenCode project configs can launch local commands. Only enable repository-level MCP configs in repos you trust.

OpenAI Codex CLI

codex mcp add claude-code -- npx -y @leo000001/claude-code-mcp

Or manually add to ~/.codex/config.toml:

[mcp_servers.claude-code-mcp]
command = "npx"
args = ["-y", "@leo000001/claude-code-mcp"]

Codex supports both user-level (~/.codex/config.toml) and project-level (.codex/config.toml) configuration. See Codex config reference for advanced options like tool_timeout_sec and enabled_tools.

From source

git clone https://github.com/xihuai18/claude-code-mcp.git
cd claude-code-mcp
npm install
npm run build
npm start

Tools

claude_code — Start a new session

Start a new Claude Code session. The agent autonomously performs coding tasks: reading/writing files, running shell commands, searching code, managing git, and interacting with APIs.

Important protocol note: this call starts background work and returns quickly with sessionId; it does not return the final result. Callers must poll claude_code_check(action="poll"), persist nextCursor, and use claude_code_reply to continue the same session later.

| Parameter | Type | Required | Description | | ---------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | prompt | string | Yes | Task or question for Claude Code | | cwd | string | No | Working directory (defaults to server cwd) | | allowedTools | string[] | No | Auto-approved tool names. Default: [] (none). This is not a strict allowlist unless strictAllowedTools=true. Example: ["Bash", "Read", "Write", "Edit"] | | strictAllowedTools | boolean | No | Server-side strict allowlist toggle. When true, tools outside allowedTools are denied. Default: false | | disallowedTools | string[] | No | Forbidden tool names. Default: [] (none). SDK behavior: disallowed tools are removed from the model's context. Takes precedence over allowedTools and will be denied even if later approved interactively | | maxTurns | number | No | Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Default: SDK/Claude Code default | | model | string | No | Model to use (e.g. "claude-sonnet-4-5-20250929"). Default: SDK/Claude Code default | | effort | string | No | Effort string: "low", "medium", "high", "max". Default: SDK/Claude Code default | | thinking | object | No | Thinking config object, not a string: { type: "adaptive" }, { type: "enabled", budgetTokens?: N }, or { type: "disabled" }. Do not pass "low"/"high" here. Default: SDK/Claude Code default | | systemPrompt | string \| object | No | Override the agent's system prompt. Default: SDK/Claude Code default. Pass a string for full replacement, or { type: "preset", preset: "claude_code", append?: "..." } to extend the default prompt | | permissionRequestTimeoutMs | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: 60000 (server-clamped to 5min) | | advanced | object | No | Advanced/low-frequency parameters (see below) |

advanced object parameters (24 low-frequency parameters)

| Parameter | Type | Description | | ------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | advanced.tools | string[] \| object | Visible built-in tool set. Array of exact tool names, [] to disable built-ins, or { type: "preset", preset: "claude_code" } for the default set. This controls what Claude can see/call; allowedTools only controls pre-approval. | | advanced.persistSession | boolean | Persist session history to disk (~/.claude/projects/). Default: true. Set false to disable. | | advanced.sessionInitTimeoutMs | number | Session init timeout in milliseconds waiting for system/init. Default: 10000. | | advanced.agents | object | Define custom sub-agents the main agent can delegate tasks to. Default: none. SDK default: if a sub-agent omits tools, it inherits all tools from the parent. | | advanced.agent | string | Name of a custom agent (defined in agents) to use as the primary agent. Default: omitted | | advanced.maxBudgetUsd | number | Maximum budget in USD. Default: SDK/Claude Code default | | advanced.betas | string[] | Beta features (e.g. ["context-1m-2025-08-07"]). Default: none | | advanced.additionalDirectories | string[] | Additional directories the agent can access beyond cwd. Default: none | | advanced.outputFormat | object | Structured output config: { type: "json_schema", schema: {...} }. Default: omitted (plain text) | | advanced.pathToClaudeCodeExecutable | string | Path to the Claude Code executable. Default: auto-detect claude, then claude-internal, else SDK-bundled Claude Code (cli.js). | | advanced.mcpServers | object | MCP server configurations keyed by server name. Default: none | | advanced.sandbox | object | Sandbox behavior config object. This controls sandbox behavior, not the actual Read/Edit/WebFetch permission rules. Default: SDK/Claude Code default | | advanced.fallbackModel | string | Fallback model if the primary model fails or is unavailable. Default: none | | advanced.enableFileCheckpointing | boolean | Enable file checkpointing to track file changes during the session. Default: false | | advanced.toolConfig | object | Per-tool built-in configuration. Example: { askUserQuestion: { previewFormat: "html" } }. Default: none

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xihuai18
• Source: xihuai18/claude-code-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.