The claudecode-mcp server wraps the headless Claude Code CLI as MCP tools, enabling stateless, one-shot prompts against Claude models from any MCP-compatible client. It spawns a new Claude Code process per call with no session persistence.
Three core tools:
claude_prompt – Send a simple text prompt and receive a text response, with optional model selection and system prompt.
claude_prompt_with_context – Same as above, but enriched with free-form context text and/or local file contents (prepended as labeled blocks), with safety checks to prevent path traversal.
claude_prompt_structured – Send a prompt and receive a validated JSON response by providing a JSON Schema; the server instructs the model to conform to the schema and validates output before returning it (requires claude CLI v2.1.0+).
Notable operational details:
Inherits authentication from the underlying claude CLI (OAuth, keychain, or ANTHROPIC_API_KEY).
Per-call timeouts (default 10 min) and output size caps (default 50 MB) prevent runaway processes.
Child processes use an explicit environment variable allowlist for security.
Debug logging available via DEBUG=claudecode-mcp.
Click on "Install 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., "@claudecode-mcp claude_prompt_structured write a Python function to calculate factorial with schema validation"
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.
Local stdio MCP server that wraps the headless Claude Code CLI as MCP tools. Stateless, spawn-per-call.
claude_prompt { prompt, model?, system_prompt? }
claude_prompt_with_context { prompt, context?, files?, model?, system_prompt? }
claude_prompt_structured { prompt, schema, model?, system_prompt? } —
uses claude --json-schema; fails loudly if the installed CLI lacks that flag.
Related MCP server: claude-bridge-mcp
npm install -g claudecode-mcpOr install locally and reference the binary from node_modules/.bin/. The
package exposes a claudecode-mcp executable that runs the stdio server.
You also need the claude CLI
on your PATH, authenticated however you normally use it (OAuth, keychain,
or ANTHROPIC_API_KEY). This server inherits that auth — it does not manage
credentials of its own.
Recommended claude CLI version: 2.1.0 or later. claude_prompt_structured
needs the --json-schema flag, and --no-session-persistence had a brief
regression in v2.0.57 (see anthropics/claude-code#20398)
that's resolved in current 2.1.x builds.
npm install
npm run build
node dist/server.jsClaude Code (~/.claude/mcp.json):
{
"mcpServers": {
"claudecode": {
"command": "claudecode-mcp"
}
}
}If you installed locally instead of globally, point command at node and
args at the absolute path to dist/server.js:
{
"mcpServers": {
"claudecode": {
"command": "node",
"args": ["/absolute/path/to/claudecode-mcp/dist/server.js"]
}
}
}The examples/ directory ships with the npm tarball. Each *.json is a
single JSON-RPC tools/call request for one of the three tools. See
examples/README.md for a one-liner to drive them
against node dist/server.js.
skill.sh is a minimal shell wrapper for direct CLI invocation outside MCP.
Usage: ./skill.sh "<prompt>" [working_dir], or pipe a large prompt to
./skill.sh - [working_dir]. It runs claude --print with the same flags and
curated child environment the MCP server uses, including
CLAUDECODE_MCP_BARE=1 opt-in. Not installed with the npm package. The script
remains compatible with the Bash 3.2 shipped by older macOS releases.
Set DEBUG=claudecode-mcp to get one structured JSON line per spawn / call
on stderr. No prompt bodies are logged — only tool names, byte counts, exit
codes, and durations.
DEBUG=claudecode-mcp claudecode-mcpnpm run test:liveRuns tiny real prompts against claude. Skipped unless CLAUDECODE_MCP_LIVE=1.
claude: command not found (or spawn claude ENOENT).
The MCP server invokes claude from your shell PATH. If your claude CLI
lives outside PATH (or you're launching the MCP under a process that has a
different PATH, e.g. some IDEs), set CLAUDECODE_MCP_CLAUDE_BIN to the
absolute path of the binary:
export CLAUDECODE_MCP_CLAUDE_BIN=/usr/local/bin/claudeVerify the binary works on its own first:
"$CLAUDECODE_MCP_CLAUDE_BIN" --versionAuth not configured / Please run claude login.
This server runs claude as a child process and inherits its auth. If
claude --print "hi" fails on your shell, the MCP will fail too. Fix the CLI
first:
For OAuth/keychain auth: run claude login once interactively.
For API-key auth: export ANTHROPIC_API_KEY=sk-ant-... in the environment
that launches the MCP server (your shell, your IDE, your launchd plist,
etc.).
--bare is intentionally off by default — it would disable OAuth/keychain and
force ANTHROPIC_API_KEY. Set CLAUDECODE_MCP_BARE=1 only when that tradeoff
is intentional.
claude_prompt_structured errors with "does not support the --json-schema flag".
Your installed claude CLI predates --json-schema. Upgrade Claude Code
(npm i -g @anthropic-ai/claude-code or whatever your install method is) or
fall back to claude_prompt.
No session tracking. No session_id in tool inputs. --no-session-persistence always.
No working_dir parameter. Uses process.cwd() of the MCP server process.
Argv array spawning — never shell-interpolated. Prompts larger than 100 KiB
are delivered to the CLI via stdin instead of a positional argument (in
--print mode the CLI reads the prompt from stdin when no positional is
given). This stays under the OS per-argument size limit (Linux
MAX_ARG_STRLEN, 128 KiB), so large contexts — up to the 5 MB per-file
cap — spawn successfully instead of failing with E2BIG. On Windows, the
complete quoted command line is checked against the 32,767 UTF-16-unit
CreateProcess limit; prompts move to stdin as needed, and oversized
non-prompt combinations fail with a bounded application error before spawn.
Prompts that do travel on argv are preceded by a -- end-of-options
separator, so prompt text beginning with - can never be parsed as CLI
flags.
--bare is opt-in via CLAUDECODE_MCP_BARE=1. Default keeps OAuth/keychain
auth working, but pins --strict-mcp-config --mcp-config '{"mcpServers":{}}'
so the wrapped subprocess does NOT load the user's own MCP servers (avoids
the recursion footgun where this server is itself in ~/.claude/mcp.json).
In bare mode, OAuth/keychain are unavailable; you must set
ANTHROPIC_API_KEY or pass apiKeyHelper via --settings.
See https://code.claude.com/docs/en/headless#start-faster-with-bare-mode.
Default 10-minute per-call timeout. Override with CLAUDECODE_MCP_TIMEOUT_MS=<ms>.
On timeout the subprocess is sent SIGTERM and then SIGKILL after a 2s
grace, and the tool call rejects with an InvokeTimeoutError. On POSIX the
complete CLI process group is terminated, including descendants.
MCP request cancellation is propagated to the active CLI process (including
the shared --json-schema capability probe) and rejects with
InvokeAbortedError; it uses the same process-tree cleanup path. Cancelling
one caller does not interrupt a shared probe still needed by another caller.
Default 50 MB cap on combined stdout/stderr from a single call. Override with
CLAUDECODE_MCP_MAX_OUTPUT_BYTES=<bytes>. On overflow the subprocess is
killed and the call rejects with OutputTooLargeError. There is no silent
truncation — truncated JSON would parse to wrong data.
claude_prompt_with_context)File paths must be relative to the server process's working directory.
Absolute paths, .. escapes, and symlinks pointing outside cwd are rejected.
Per-file size cap, default 5 MB. Override with CLAUDECODE_MCP_MAX_FILE_BYTES=<bytes>.
At most 32 files are accepted per request. Free-form context and included
file bodies also share a 20 MB aggregate cap; override it with
CLAUDECODE_MCP_MAX_CONTEXT_BYTES=<bytes>.
File contents and paths are inserted into the prompt inside ----- file: NAME -----
fenced blocks (not pseudo-XML), so quotes or angle brackets in paths cannot
break the block boundaries.
The child inherits an explicit allowlist of environment variables, not the full parent env. Pass-through includes:
Shell/locale: PATH, HOME, USER, LOGNAME, SHELL, TERM, TZ,
TMPDIR, LANG, LC_*, XDG_*.
Anthropic auth: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN,
CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_CODE_OAUTH_REFRESH_TOKEN,
CLAUDE_CODE_OAUTH_SCOPES.
Cloud provider routing/auth: the documented CLAUDE_CODE_USE_* and
CLAUDE_CODE_SKIP_*_AUTH selectors; standard AWS credential/region/profile
variables; AWS_BEARER_TOKEN_BEDROCK; ANTHROPIC_AWS_*;
Foundry API/bearer/resource variables and Azure service-principal variables;
and Vertex project/region/application-credentials variables.
Routing: ANTHROPIC_BASE_URL, ANTHROPIC_*_BASE_URL.
Model selection: ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, ANTHROPIC_BETAS.
TLS: CLAUDE_CODE_CERT_STORE, CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY,
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE.
Locations: CLAUDE_CONFIG_DIR, CLAUDE_CODE_DEBUG_LOGS_DIR.
Anything in CLAUDECODE_MCP_EXTRA_ENV (comma-separated key names).
Windows runtime/config-location variables such as SystemRoot, PATHEXT,
USERPROFILE, and APPDATA are retained on Windows. Always force-set:
NO_COLOR=1, TERM=dumb. Always stripped (unless the explicit
CLAUDECODE_MCP_FORWARD_DANGEROUS=1 opt-in is set):
CLAUDE_CODE_SHELL_PREFIX,
CLAUDE_CODE_EXTRA_BODY, ANTHROPIC_CUSTOM_HEADERS,
CLAUDE_CODE_SCRIPT_CAPS, CLAUDECODE.
Errors returned to MCP clients are truncated (1 KB) and redact sk-ant-*
tokens, Bearer … headers, and any verbatim copies of values held in known
auth env vars or variables named in CLAUDECODE_MCP_EXTRA_ENV. Local
diagnostics contain redacted, bounded previews and byte counts rather than raw
CLI stderr.
MIT © 2026 Trevor Spencer
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode (no session persistence, no resume). Returns the model's text response. Uses the server process's current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: stateless operation, no session persistence, no resume capability, and that it uses the server's current working directory. However, it doesn't mention rate limits, authentication requirements, error handling, or response format details that would be helpful for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality and key behavioral constraints. The second sentence provides important operational context about the working directory. There's zero wasted language or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides adequate but incomplete context. It covers the operational mode and working directory context well, but doesn't address what the return value looks like (only says 'Returns the model's text response' without format details), error conditions, or performance characteristics that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all three parameters thoroughly. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it doesn't explain parameter interactions, provide examples, or clarify usage patterns. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Run a one-shot prompt'), target resource ('Claude Code CLI'), and operational mode ('headless, stateless mode with no session persistence, no resume'). It distinguishes from siblings by specifying this is a one-shot operation without persistence, unlike tools that might maintain context or structure outputs differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('headless, stateless mode with no session persistence, no resume'), which implicitly suggests alternatives when persistence or session management is needed. However, it doesn't explicitly name sibling tools or provide explicit 'when-not-to-use' guidance beyond the stateless nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode and return a structured JSON object. If schema (a JSON Schema) is provided, the tool instructs the model to conform to it and validates the parsed output against the schema (basic type/required-field checks). Returns the parsed JSON as the tool response content. Uses the server process's current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| schema | No | Optional JSON Schema describing the expected shape of the model's JSON output. Used both as an instruction to the model and for lightweight post-hoc validation. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the tool runs in 'headless, stateless mode', validates output against a schema if provided, returns parsed JSON, and uses the 'server process's current working directory'. This covers execution mode, validation behavior, and environmental context, though it lacks details on error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first. Every sentence adds value: the first defines the action and output, the second explains schema usage, and the third provides environmental context. There is no wasted text, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a 4-parameter tool with no annotations and no output schema, the description is mostly complete. It covers the tool's purpose, behavioral traits, and usage context. However, it lacks details on error cases, response format beyond 'parsed JSON', or performance considerations, leaving minor gaps for a tool with no structured safety hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, only mentioning that the schema is 'used both as an instruction to the model and for lightweight post-hoc validation'. This aligns with the baseline score of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a one-shot prompt against the Claude Code CLI in headless, stateless mode and return a structured JSON object.' It specifies the verb ('Run'), resource ('Claude Code CLI'), and distinguishes from siblings by mentioning 'structured JSON object' and schema validation, unlike the generic 'claude_prompt' and context-aware 'claude_prompt_with_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for 'one-shot prompt' execution in 'headless, stateless mode' with structured JSON output. It implies usage for schema-constrained responses but does not explicitly state when NOT to use it or name alternatives like the sibling tools, though the structured output focus differentiates it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode, with additional free-form context and/or file contents prepended to the prompt. Returns the model's text response. Uses the server process's current working directory; file paths are resolved relative to cwd.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| context | No | Optional free-form context text to prepend to the prompt. | |
| files | No | Optional list of file paths whose contents will be read and prepended to the prompt as labeled context blocks. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral traits: 'headless, stateless mode', 'Returns the model's text response', and 'Uses the server process's current working directory; file paths are resolved relative to cwd.' However, it lacks details about rate limits, authentication needs, error conditions, or response format specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the core functionality and key differentiators, the second adds important operational context about working directory and file path resolution. Every element earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and no output schema, the description provides adequate but not complete coverage. It explains the core operation and some behavioral context but lacks details about response format, error handling, or model selection implications. For a tool with this complexity and no structured safety/behavior annotations, more completeness would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds some context about how 'context' and 'files' parameters work ('prepended to the prompt'), but doesn't provide significant additional meaning beyond what's in the schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run a one-shot prompt'), the target ('Claude Code CLI'), the mode ('headless, stateless mode'), and key differentiators from siblings ('with additional free-form context and/or file contents prepended'). It distinguishes this tool from 'claude_prompt' and 'claude_prompt_structured' by emphasizing the context/file prepending capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('with additional free-form context and/or file contents prepended to the prompt'), which implicitly suggests alternatives when such context isn't needed. However, it doesn't explicitly state when NOT to use it or name specific sibling alternatives beyond the general differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The three tools have clearly distinct purposes: one returns plain text, one returns structured JSON, and one accepts additional context/files. However, the core functionality of running a one-shot prompt is identical across all three, which could cause minor confusion about when to use each variant.
All tool names follow a perfect 'claude_prompt_' prefix pattern with descriptive suffixes (_structured, _with_context). The naming is completely consistent and predictable, making it easy to understand the tool hierarchy at a glance.
Three tools is reasonable for a Claude Code CLI interface, covering the main variations needed (text, structured, contextual). However, this feels slightly minimal - additional tools for session management or configuration might be expected but aren't strictly necessary for the stated headless, stateless approach.
The tools cover the basic prompt execution variations well, but there are notable gaps for a complete Claude Code CLI surface. Missing operations include session management (contradicting the stateless approach), model selection, parameter tuning, streaming responses, and error handling tools that would be expected for production use.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/trevoraspencer/claudecode-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
