claude-mcp-bridge

MCP server that wraps Claude Code CLI as a subprocess, exposing its capabilities as Model Context Protocol tools.

Works with any MCP client: Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.

Do you need this?

If you're in a terminal agent (Codex CLI, Gemini CLI) with shell access, call Claude Code CLI directly:

# Quick review of current diff
git diff origin/main...HEAD | claude -p --bare "Review this diff for bugs and security issues"

# Agentic review (Claude reads files, follows imports, checks tests)
claude -p --bare --allowed-tools "Read Grep Glob Bash(git diff:*,git log:*,git show:*)" \
  "Review the changes on this branch vs main"

# Analyze specific files
claude -p --bare --allowed-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 skips hooks, memory, and plugins for clean subprocess use. --allowed-tools controls exactly what Claude can access. --max-budget-usd prevents runaway costs.

Use this MCP bridge instead when:

• Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)
• You need structured output with native --json-schema validation
• You need session resume across calls (--resume SESSION_ID)
• You need concurrency management and security hardening
• You want cost metadata surfaced in MCP responses

Quick Start

npx claude-mcp-bridge

Prerequisites

• Claude Code CLI installed and on PATH
• Authentication (one of):
  • Subscription (default): claude login (uses your Pro/Max plan, no API credits needed)
  • API key: set ANTHROPIC_API_KEY + CLAUDE_BRIDGE_USE_API_KEY=1 (billed per use via console.anthropic.com)

Codex CLI

Add to ~/.codex/config.json:

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

Gemini CLI

Add to ~/.gemini/settings.json:

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

Cursor / Windsurf / VS Code

Add to your MCP settings:

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

Tools

query

Execute a prompt with optional file context. Supports session resume via sessionId, effort control (low/medium/high/max), and budget caps (maxBudgetUsd). Images (.png, .jpg, .gif, .webp, .bmp) up to 5MB each are passed to Claude's Read tool.

Key parameters: prompt (required), files, model (default sonnet), sessionId, effort, maxBudgetUsd, workingDirectory, timeout (default 60s).

review

Two modes:

• Agentic (default): Claude runs inside the repo with Read, Grep, Glob, and git commands. It diffs, reads files, follows imports, and checks tests. Timeout auto-scales from diff size.
• Quick (quick: true): Diff-only review, no repo exploration. Faster and cheaper.

Key parameters: uncommitted (default true), base, focus, quick, model (default opus), effort (default high), maxBudgetUsd, workingDirectory, timeout.

search

Web search powered by Anthropic's WebSearch tool via Claude CLI. Returns synthesized answers with source URLs.

Key parameters: query (required), model (default sonnet), maxResponseLength, maxBudgetUsd, timeout (default 120s).

structured

Generate JSON conforming to a provided schema using Claude CLI's native --json-schema flag. Returns clean JSON in the first content block, metadata in a separate block so JSON parsing isn't broken.

Key parameters: prompt (required), schema (required, JSON string, max 20KB), files, model (default sonnet), sessionId, maxBudgetUsd, timeout (default 60s).

ping

No parameters. Returns CLI version, auth method (subscription/api-key/none), configured models, capabilities, and server version.

listSessions

No parameters. Returns active sessions with metadata: sessionId, model, createdAt, lastUsedAt, turnCount, totalCostUsd.

All tools attach execution metadata (_meta) with durationMs, model, sessionId, totalCostUsd, and token breakdowns. See DESIGN.md for details.

Configuration

Models

Model resolution: explicit parameter > tool-specific env var > CLAUDE_DEFAULT_MODEL > built-in default.

Runtime

Effort

Choosing a Claude Code MCP server

Performance

Claude Code CLI has minimal startup overhead. Wall time is dominated by model inference and any agentic exploration.

Cost metadata (totalCostUsd, token breakdowns) is returned in _meta on every response.

Bridge family

Three MCP servers, same architecture, different underlying CLIs. Each wraps a terminal agent as a subprocess and exposes it as MCP tools. Pick the one that matches your model provider, or run multiple for cross-model workflows.

All three share: subprocess env isolation, path sandboxing, output redaction, FIFO concurrency queue, MCP tool annotations, _meta response metadata, progress heartbeats.

Development

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

Further reading

• DESIGN.md - Architecture, sessions, cost tracking, response metadata, progress notifications
• SECURITY.md - Environment isolation, path sandboxing, output redaction, tool sandboxing
• CHANGELOG.md - Release history

License

MIT