claude-mcp-bridge

claude-mcp-bridge

Claude Code CLIをサブプロセスとしてラップし、その機能をModel Context Protocolツールとして公開するMCP サーバーです。

Codex CLI、Gemini CLI、Cursor、Windsurf、VS Codeなど、MCPに対応するあらゆるMCPクライアントで利用できます。

これは必要ですか？

シェルにアクセスできるターミナルエージェント（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ブリッジを使用してください：

• クライアントからシェルにアクセスできない（Cursor、Windsurf、Claude Desktop、VS Code）
• ネイティブの--json-schema検証による構造化出力が必要
• 呼び出しをまたいだセッションの再開（--resume SESSION_ID）が必要
• 同時実行管理とセキュリティ強化が必要
• MCPレスポンスにコストのメタデータを表示したい

クイックスタート

npx claude-mcp-bridge

前提条件

• Claude Code CLIがインストールされ、PATH上にあること
• 認証方式（いずれか1つ）：
  • サブスクリプション（デフォルト）：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（デフォルトは60秒）。

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）とともに、アクティブなセッションを返します。

すべてのツールは、durationMs、model、sessionId、totalCostUsd、トークンの内訳を含む実行メタデータ（_meta）を付加します。詳細は 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		サブプロセスに ANTHROPIC_API_KEY を転送するには 1 を設定します（デフォルト：サブスクリプション認証）

労力レベル

変数	デフォルト	説明
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 用の組み込みツール

カンマまたはスペース区切りのリスト、CLI のすべての組み込みツールを指定する default、またはツールを指定しない空の値を受け付けます。これらの範囲を広げると、サブプロセスに渡した作業ディレクトリ内で実際の操作が可能になります。SECURITY.md § Tool Sandboxing を参照してください。

Claude Code MCP サーバーの選び方

必要なもの...	検討するもの
構造化出力、労力／予算の制御、セッションの再開、コストメタデータ	このブリッジ
複数ツールのオーケストレーション（読み取り、grep、編集、bash を個別の MCP ツールとして使用）	mcp-claude-code
非同期実行でのセッション継続	claude-mcp
メンテナンスされている軽量なラッパー	@kunihiros/claude-code-mcp
ネイティブの Claude Code MCP（組み込み、ラッパー不要）	claude mcp serve（ドキュメント）

パフォーマンス

Claude Code CLI の起動時のオーバーヘッドは最小限です。実行時間は主にモデルの推論と、エージェントによる探索に左右されます。

シナリオ	目安時間
単純なプロンプト（sonnet）	5-10s
ウェブ検索と要約	15-30s

コストのメタデータ（totalCostUsd、トークンの内訳）は、すべての応答の _meta に返されます。

ブリッジファミリー

基盤となる CLI が異なる、同じアーキテクチャの MCP サーバーが 2 つあります。それぞれ、ターミナルエージェントをサブプロセスとしてラップし、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 クレジット（オプトイン）	トークン従量課金
同時実行数	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 の直接呼び出し（サブプロセスで分離）

シェルを利用できるコンシューマー（ターミナルエージェント、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