hampsterx/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:
--bare skips hooks, memory, and plugins for clean subprocess use. --tools restricts which tools Claude can use at all; --allowed-tools only pre-approves permission and leaves everything else, including Bash, still reachable. --max-budget-usd prevents runaway costs.
--tools is variadic, so end the list with -- (or another flag) before the prompt. Without it the prompt is read as one more tool name and the CLI exits with "Input must be provided".
For code review, see Code review with this CLI.
**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
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:
Gemini CLI
Add to ~/.gemini/settings.json:
Cursor / Windsurf / VS Code
Add to your MCP settings:
Tools
| Tool | Description |
|------|-------------|
| **query** | Execute prompts with file context, session resume, effort control, and budget caps. Supports text and images. For code review, see Code review with this CLI. |
| **search** | Web search via Claude CLI's WebSearch and WebFetch tools. Returns synthesized answers with sources. |
| **structured** | JSON Schema validated output via Claude CLI's native --json-schema. |
| **ping** | Health check with CLI version, auth method, capabilities, and model config. |
| **listSessions** | List active sessions with cumulative cost, turn count, and timestamps. |
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).
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.