用途
claude-mcp-bridge 是一个 MCP 服务器，它把 Claude Code CLI 作为子进程包装起来，并将其能力暴露为 Model Context Protocol 工具。它适用于任何支持 MCP 的客户端，包括 Codex CLI、Gemini CLI、Cursor、Windsurf、VS Code 等。
何时使用
如果你身处具备 shell 访问权限的终端智能体（如 Codex CLI、Gemini CLI），可以直接调用 Claude Code CLI。直接调用时可使用 --bare 跳过 hooks、memory 和 plugins 以获得干净的子进程；--tools 限制 Claude 可使用的工具；--allowed-tools 仅预先批准权限，其余工具（包括 Bash）仍可触达；--max-budget-usd 防止成本失控。注意 --tools 是可变参数，需在提示词前以 --（或其他标志）结束列表，否则提示词会被当作又一个工具名，CLI 会以“Input must be provided”退出。
在以下情况应改用此 MCP 桥接：客户端没有 shell 访问权限（Cursor、Windsurf、Claude Desktop、VS Code）；需要带原生 --json-schema 校验的结构化输出；需要跨调用恢复会话（--resume SESSION_ID）；需要并发管理与安全加固；希望在 MCP 响应中暴露成本元数据。
前置条件
需要安装 Claude Code CLI 并位于 PATH 中。认证方式二选一：订阅（默认）使用 claude login，走 Pro/Max 套餐，无需 API 额度；API key 方式需设置 ANTHROPIC_API_KEY 与 CLAUDE_BRIDGE_USE_API_KEY=1，按使用量通过 console.anthropic.com 计费。
配置方式
Codex CLI 添加到 ~/.codex/config.json；Gemini CLI 添加到 ~/.gemini/settings.json；Cursor / Windsurf / VS Code 添加到各自的 MCP 设置中。
主要工具
query：执行提示词并可附带文件上下文。支持通过 sessionId 恢复会话、effort 控制（low / medium / high / max）以及预算上限（maxBudgetUsd）。图片（.png、.jpg、.gif、.webp、.bmp）每张最大 5MB，会传给 Claude 的 Read 工具。关键参数：prompt（必填）、files、model（默认 sonnet）、sessionId、effort、maxBudgetUsd、workingDirectory、timeout（默认 60s）。
search：由 Anthropic 的 WebSearch 工具通过 Claude CLI 提供网页搜索，返回带来源 URL 的综合答案。关键参数：query（必填）、model（默认 sonnet）、maxResponseLength、maxBudgetUsd、timeout（默认 120s）。
structured：使用 Claude CLI 原生的 --json-schema 标志生成符合所提供 schema 的 JSON。干净的 JSON 放在第一个内容块，元数据放在单独块中，以免破坏 JSON 解析。关键参数：prompt（必填）、schema（必填，JSON 字符串，最大 20KB）、files、model（默认 sonnet）、sessionId、maxBudgetUsd、timeout（默认 60s）。
status：无参数。返回 CLI 版本、认证方式（subscription/api-key/none）、已配置模型、能力以及服务器版本。
sessions：无参数。返回活动会话及其元数据：sessionId、model、createdAt、lastUsedAt、turnCount、totalCostUsd。
所有工具都会附带执行元数据（_meta），包含 durationMs、model、sessionId、totalCostUsd 以及 token 明细。
模型解析与工具沙箱
模型解析优先级：显式参数 > 工具专属环境变量 > CLAUDE_DEFAULT_MODEL > 内置默认值。
每个生成的子进程都会获得明确的内置工具集。默认是只读的，除非放宽配置，否则不会授予 Bash、Write 和 Edit。工具集接受逗号或空格分隔的列表，默认值为 CLI 的完整内置集，空值表示不授予任何工具。放宽这些设置会让子进程在你传入的工作目录中拥有真实能力。
与其他 Claude Code MCP 服务器的比较
Claude Code CLI 启动开销很小，实际耗时主要由模型推理和智能体探索决定。成本元数据（totalCostUsd、token 明细）会在每次响应的 _meta 中返回。两个 MCP 服务器架构相同但底层 CLI 不同，各自把终端智能体包装为子进程并暴露为 MCP 工具。可按模型提供商选择，或同时运行以支持跨模型工作流。两者共享：子进程环境隔离、路径沙箱、输出脱敏、FIFO 并发队列、MCP 工具注解、_meta 响应元数据、进度心跳。
代码审查
审查提示词由调用方提供，桥接本身不捆绑审查提示词。在 Claude Code 交互式 REPL 中可使用内置的 /review、/security-review、/ultrareview，但这些仅限 REPL，无法通过 claude -p 或此桥接触达。通过此桥接（query / structured）时，需将审查提示词作为纯文本传入；斜杠命令（内置或用户安装于 ~/.claude/commands/）不会通过桥接解析，隔离标志（API key 路径的 --bare、订阅路径的 --setting-sources ""）按设计阻止所有技能解析。直接使用 claude -p（无桥接）时，在没有隔离标志抑制的情况下，用户技能会以 /skill-name 解析。
直接 claude -p 调用（子进程隔离）适用于具备 shell 的消费者（终端智能体、CI、BYOS 技能），可使用加固的隔离标志：--permission-mode plan（只读）、--bare（剥离父进程的 hooks、plugins、auto-memory 和 CLAUDE.md 自动加载）、--add-dir <repo-root>（在 diff 需要时使仓库的 CLAUDE.md / AGENTS.md 可用）、--strict-mcp-config --mcp-config '{"mcpServers":{}}'（阻止父进程的 MCP 服务器泄漏进来，内部 mcpServers 键为必需，schema 拒绝裸 {}）、--no-session-persistence（一次性审查不保留会话文件）、--max-budget-usd（每次调用成本上限）。
适用场景与限制
适用于无 shell 访问权限的 MCP 客户端、需要结构化输出与会话恢复、需要并发管理与安全加固、以及希望在响应中获取成本元数据的场景。限制包括：斜杠命令与技能无法通过桥接解析；工具沙箱默认只读，需显式放宽才能获得写能力；结构化输出的 schema 最大 20KB；图片每张最大 5MB。
