本地 stdio MCP 服务器，将无头 Claude Code CLI 封装为 MCP 工具。 无状态，每个客户端生成一个进程。
claude_prompt { prompt, model?, system_prompt? }
claude_prompt_with_context { prompt, context?, files?, model?, system_prompt? }
claude_prompt_structured { prompt, schema, model?, system_prompt? } —
使用 claude --json-schema；如果安装的 CLI 缺少该标志，则会报错。
Related MCP server: claude-bridge-mcp
npm install
npm run build
node dist/server.jsClaude Code (~/.claude/mcp.json):
{
"mcpServers": {
"claudecode": {
"command": "node",
"args": ["/home/trevor/claudecode-mcp/dist/server.js"]
}
}
}npm run test:live针对 claude 运行微小的真实提示词。除非设置 CLAUDECODE_MCP_LIVE=1，否则将跳过。
无会话跟踪。工具输入中没有 session_id。始终使用 --no-session-persistence。
没有 working_dir 参数。使用 MCP 服务器进程的 process.cwd()。
不强制执行超时。信任 CLI 原生的轮次限制。
使用 Argv 数组生成进程 — 从不进行 shell 插值。
清理子进程环境变量：NO_COLOR=1，继承 PATH/HOME/认证信息。
特意不使用 --bare：它会禁用 OAuth/密钥链读取，并强制要求 ANTHROPIC_API_KEY。MCP 会继承用户 claude CLI 已经配置的任何认证方式（OAuth、密钥链或环境变量密钥）。
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0claude_promptclaude_prompt_structuredclaude_prompt_with_contextScored across 3 tools
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.
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 Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
