claude-mcp-bridge

claude-mcp-bridge

将 Claude Code CLI 作为子进程封装的 MCP 服务，并将其功能作为 Model Context Protocol 工具公开。

兼容任何 MCP 客户端：Codex CLI、Gemini CLI、Cursor、Windsurf、VS Code，或任何支持 MCP 的工具。

你需要它吗？

如果你正在使用可访问 Shell 的终端 Agent（Codex CLI、Gemini CLI），可以直接调用 Claude Code CLI：

# Analyze specific files
claude -p --bare --tools Read -- "Analyze src/utils/parse.ts for edge cases"

# With budget cap
claude -p --bare --max-budget-usd 0.50 "Is this retry logic sound?"

--bare 会跳过钩子、记忆和插件，以便干净地用作子进程。--tools 会限制 Claude 可使用的工具；--allowed-tools 只会预先批准权限，其他所有工具（包括 Bash）仍可使用。--max-budget-usd 可防止费用失控。

--tools 接受可变数量的参数，因此请在列表末尾、提示词之前加上 --（或其他标志）。如果不加，提示词会被当作另一个工具名称读取，CLI 会以 "Input must be provided" 退出。

代码审查请参阅使用此 CLI 进行代码审查。

以下情况请改用此 MCP 桥接工具：

• 你的客户端无法访问 Shell（Cursor、Windsurf、Claude Desktop、VS Code）
• 你需要通过原生 --json-schema 验证结构化输出
• 你需要在多次调用之间恢复会话（--resume SESSION_ID）
• 你需要并发管理和安全加固
• 你希望在 MCP 响应中显示费用元数据

快速开始

npx claude-mcp-bridge

前提条件

• 已安装 Claude Code CLI，并且已加入 PATH
• 身份验证方式（二选一）：
  • 订阅（默认）：claude login（使用你的 Pro/Max 套餐，无需 API 额度）
  • API 密钥：设置 ANTHROPIC_API_KEY + CLAUDE_BRIDGE_USE_API_KEY=1（通过 console.anthropic.com 按使用量计费）

Codex CLI

添加到 ~/.codex/config.json：

{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}

Gemini CLI

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}

Cursor / Windsurf / VS Code

添加到 MCP 设置中：

{
  "claude-bridge": {
    "command": "npx",
    "args": ["-y", "claude-mcp-bridge"],
    "env": {
      "ANTHROPIC_API_KEY": "sk-ant-...",
      "CLAUDE_BRIDGE_USE_API_KEY": "1"
    }
  }
}

工具

工具	描述
query	执行提示词，支持文件上下文、会话恢复、工作量控制和预算上限。支持文本和图片。代码审查请参阅使用此 CLI 进行代码审查。
search	通过 Claude CLI 的 WebSearch 和 WebFetch 工具进行网页搜索。返回综合答案及来源。
structured	通过 Claude CLI 原生的 --json-schema 输出经 JSON Schema 验证的结果。
ping	健康检查，返回 CLI 版本、身份验证方式、功能和模型配置。
listSessions	列出活跃会话及累计费用、轮数和时间戳。

query

执行提示词，可选择附带文件上下文。支持通过 sessionId 恢复会话、控制工作量（low/medium/high/max）和设置预算上限（maxBudgetUsd）。每张不超过 5MB 的图片（.png、.jpg、.gif、.webp、.bmp）都会传递给 Claude 的 Read 工具。

主要参数：prompt（必填）、files、model（默认为 sonnet）、sessionId、effort、maxBudgetUsd、workingDirectory、timeout（默认为 60s）。

search

通过 Claude CLI 调用 Anthropic 的 WebSearch 工具进行网络搜索。返回经过综合整理的答案和来源 URL。

关键参数：query（必填）、model（默认值为 sonnet）、maxResponseLength、maxBudgetUsd、timeout（默认值为 120s）。

structured

使用 Claude CLI 原生的 --json-schema 标志生成符合指定架构的 JSON。JSON 将在第一个内容块中干净返回，元数据则位于单独的内容块中，避免干扰 JSON 解析。

关键参数：prompt（必填）、schema（必填，JSON 字符串，最大 20KB）、files、model（默认值为 sonnet）、sessionId、maxBudgetUsd、timeout（默认值为 60s）。

ping

无需参数。返回 CLI 版本、身份验证方式（subscription/api-key/none）、已配置的模型、功能和服务端版本。

listSessions

无需参数。返回带有元数据的活跃会话：sessionId、model、createdAt、lastUsedAt、turnCount、totalCostUsd。

所有工具都会附带执行元数据（_meta），包括 durationMs、model、sessionId、totalCostUsd 和 token 用量明细。详见 DESIGN.md。

配置

模型

变量	默认值	说明
CLAUDE_DEFAULT_MODEL		所有工具共用的默认模型
CLAUDE_QUERY_MODEL	sonnet	query 的默认模型
CLAUDE_STRUCTURED_MODEL	sonnet	structured 的默认模型
CLAUDE_SEARCH_MODEL	sonnet	search 的默认模型
CLAUDE_FALLBACK_MODEL	haiku	配额耗尽时的回退模型（设为 none 可禁用）

模型解析顺序：显式参数 > 工具专用环境变量 > CLAUDE_DEFAULT_MODEL > 内置默认值。

运行时

变量	默认值	说明
CLAUDE_MAX_CONCURRENT	3	并发生成子进程的最大数量
CLAUDE_CLI_PATH	claude	CLI 二进制文件的路径
CLAUDE_MAX_BUDGET_USD		全局费用上限，单位为 USD（每次调用）
ANTHROPIC_API_KEY		API 密钥（仅在 CLAUDE_BRIDGE_USE_API_KEY=1 时转发）
CLAUDE_BRIDGE_USE_API_KEY		设为 1，将 ANTHROPIC_API_KEY 转发给子进程（默认：subscription 身份验证）

努力程度

变量	默认值	说明
CLAUDE_SEARCH_EFFORT	medium	search 的默认努力程度
CLAUDE_QUERY_EFFORT		query 的默认努力程度

工具

每个生成的子进程都会获得一组明确指定的内置工具。默认工具为只读，因此除非按下文扩大授权，否则不会授予 Bash、Write 和 Edit。

变量	默认值	说明
CLAUDE_QUERY_TOOLS	Read Glob Grep	query 的内置工具
CLAUDE_STRUCTURED_TOOLS	Read Glob Grep	structured 的内置工具
CLAUDE_SEARCH_TOOLS	WebSearch WebFetch	search 的内置工具

接受以逗号或空格分隔的列表；设为 default 可使用 CLI 的完整内置工具集，设为空值则不启用任何工具。扩大授权后，子进程将在传入的工作目录中获得实际操作能力。详见 SECURITY.md § 工具沙箱。

选择 Claude Code MCP 服务

你的需求……	可考虑
结构化输出、努力程度／预算控制、会话恢复、费用元数据	此桥接服务
多工具编排（将 read、grep、edit、bash 作为独立 MCP 工具）	mcp-claude-code
支持异步执行的会话连续性	claude-mcp
有维护的轻量封装	@kunihiros/claude-code-mcp
原生 Claude Code MCP（内置，无需封装）	claude mcp serve（文档）

性能

Claude Code CLI 的启动开销极小。总耗时主要由模型推理和 Agent 式探索决定。

场景	典型耗时
简单提示词（sonnet）	5-10s
网页搜索 + 综合整理	15-30s

每次响应都会在 _meta 中返回费用元数据（totalCostUsd、Token 明细）。

Bridge 系列

两个 MCP 服务采用相同的架构，但底层 CLI 不同。每个服务都会将一个终端 Agent 封装为子进程，并将其作为 MCP 工具提供。选择与模型提供商匹配的服务，也可以同时运行两个服务以支持跨模型工作流。

	claude-mcp-bridge	codex-mcp-bridge
CLI	Claude Code	Codex CLI
提供商	Anthropic	OpenAI
工具	query、search、structured、ping、listSessions	codex、search、query、structured、ping、listSessions
代码审查	直接使用 Claude Code 内置功能（不通过此桥接服务），或在非 Claude Code 主机上使用 claude -p	codex review --base <ref>（原生）或使用由调用方提供提示词的 codex 工具
结构化输出	原生 --json-schema（无需 Ajv）	Ajv 验证
会话恢复	原生 --resume	使用支持多轮对话的会话 ID
预算上限	原生 --max-budget-usd	不支持
工作量控制	--effort low/medium/high/max	不支持
冷启动	~1-2s	<100ms（耗时主要由推理决定）
身份验证	claude login（默认）或 ANTHROPIC_API_KEY + 主动启用	OPENAI_API_KEY
费用	订阅（默认）或 API 额度（主动启用）	按 Token 计费
并发数	3（可配置）	3（可配置）
模型回退	自动重试并使用回退模型	自动重试并使用回退模型

两者共用：子进程环境隔离、路径沙箱、输出脱敏、FIFO 并发队列、MCP 工具注解、_meta 响应元数据、进度心跳。

使用此 CLI 进行代码审查

审查提示词由调用方提供。此桥接服务不附带审查提示词（参见 ADR-001）。

• 在 Claude Code 中（交互式 REPL）：使用内置的 /review、/security-review、/ultrareview。这些命令仅适用于 REPL；无法通过 claude -p 或此桥接服务调用。
• 通过此桥接服务（query / structured）：以纯文本形式传入审查提示词。斜杠命令（内置或用户安装在 ~/.claude/commands/ 中的命令）无法通过此桥接服务解析；隔离标志（API 密钥路径上的 --bare、订阅路径上的 --setting-sources ""）按设计会阻止所有技能解析。上游跟踪问题：anthropics/claude-code#37207。
• 直接使用 claude -p（不通过桥接服务）：如果没有隔离标志阻止用户技能，用户技能可通过 /skill-name 解析。要使用子进程隔离进行审查，请使用下方的强化调用方式。

根据使用场景选择方式：

• 已经在 Claude Code 中？ 输入 /review、/security-review 或 /ultrareview。可跳过本节其余内容。
• 从其他 MCP 主机（Cursor、Codex CLI、Gemini CLI、Claude Desktop）调用？ 斜杠命令和技能无法通过此桥接服务调用。将审查提示词以纯文本形式传给 query / structured，或按照下文所述直接调用 claude -p。

直接调用 claude -p（子进程隔离）

对于配备 shell 的使用方（终端 Agent、CI、BYOS 技能），请使用强化隔离标志直接调用 CLI：

claude -p \
  --permission-mode plan \
  --bare \
  --add-dir <repo-root> \
  --strict-mcp-config \
  --mcp-config '{"mcpServers":{}}' \
  --no-session-persistence \
  --max-budget-usd 0.50 \
  "<your review prompt + diff or file references>"

• --permission-mode plan：只读。
• --bare：移除父级的钩子、插件、自动记忆和 CLAUDE.md 自动加载。
• --add-dir <repo-root>：在差异需要时，使仓库的 CLAUDE.md / AGENTS.md 可用。
• --strict-mcp-config --mcp-config '{"mcpServers":{}}'：阻止父级的 MCP 服务泄漏进来。必须包含内部的 mcpServers 键；架构会拒绝裸写的 '{}'。
• --no-session-persistence：一次性审查不生成会话文件。
• --max-budget-usd：设置每次调用的费用上限。

Claude Code 技能模板

对于希望使用可复用命令的 Claude Code 用户，可将以下内容放入 ~/.claude/commands/review-claude.md：

---
description: Code review via subprocess-isolated claude -p
---

Run code review on the diff between origin/main and HEAD.

```bash
claude -p \
  --permission-mode plan \
  --bare \
  --add-dir "$(git rev-parse --show-toplevel)" \
  --strict-mcp-config \
  --mcp-config '{"mcpServers":{}}' \
  --no-session-persistence \
  --max-budget-usd 0.50 \
  "Review the diff below for bugs, missing error handling on user input, tests modified to silence failures, and security issues (injection, missing auth checks, secret leaks). For each finding cite file:line, severity, and a suggested fix. Skip style/formatting.

$(git diff origin/main...HEAD)"
```

具有代表性的审查提示词

以下是一个起点；可随意调整：

Review the following diff:

<diff content>

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

开发

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests (vitest)
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit
npm run smoke        # Smoke test against live CLI

延伸阅读

• DESIGN.md - 架构、会话、费用跟踪、响应元数据、进度通知
• SECURITY.md - 环境隔离、路径沙盒、输出脱敏、工具沙盒
• CHANGELOG.md - 发布历史

许可证

MIT