{
  "markdown": "# claude-mcp-bridge\n\n[![npm version](https://img.shields.io/npm/v/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)\n[![npm downloads](https://img.shields.io/npm/dm/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)\n[![CI](https://github.com/hampsterx/claude-mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hampsterx/claude-mcp-bridge/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/node/v/claude-mcp-bridge)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io/)\n[![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/claude-mcp-bridge)\n\nMCP server that wraps [Claude Code CLI](https://github.com/anthropics/claude-code) as a subprocess, exposing its capabilities as [Model Context Protocol](https://modelcontextprotocol.io/) tools.\n\nWorks with any MCP client: Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.\n\n## Do you need this?\n\nIf you're in a terminal agent (Codex CLI, Gemini CLI) with shell access, call Claude Code CLI directly:\n\n```bash\n# Analyze specific files\nclaude -p --bare --tools Read -- \"Analyze src/utils/parse.ts for edge cases\"\n\n# With budget cap\nclaude -p --bare --max-budget-usd 0.50 \"Is this retry logic sound?\"\n```\n\n`--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.\n\n`--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\".\n\nFor code review, see [Code review with this CLI](#code-review-with-this-cli).\n\n**Use this MCP bridge instead when:**\n- Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)\n- You need structured output with native `--json-schema` validation\n- You need session resume across calls (`--resume SESSION_ID`)\n- You need concurrency management and security hardening\n- You want cost metadata surfaced in MCP responses\n\n## Quick Start\n\n```bash\nnpx claude-mcp-bridge\n```\n\n### Prerequisites\n\n- [Claude Code CLI](https://github.com/anthropics/claude-code) installed and on PATH\n- Authentication (one of):\n  - **Subscription** (default): `claude login` (uses your Pro/Max plan, no API credits needed)\n  - **API key**: set `ANTHROPIC_API_KEY` + `CLAUDE_BRIDGE_USE_API_KEY=1` (billed per use via console.anthropic.com)\n\n### Codex CLI\n\nAdd to `~/.codex/config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"claude-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude-mcp-bridge\"]\n    }\n  }\n}\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"claude-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude-mcp-bridge\"]\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / VS Code\n\nAdd to your MCP settings:\n```json\n{\n  \"claude-bridge\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"claude-mcp-bridge\"],\n    \"env\": {\n      \"ANTHROPIC_API_KEY\": \"sk-ant-...\",\n      \"CLAUDE_BRIDGE_USE_API_KEY\": \"1\"\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| **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](#code-review-with-this-cli). |\n| **search** | Web search via Claude CLI's WebSearch and WebFetch tools. Returns synthesized answers with sources. |\n| **structured** | JSON Schema validated output via Claude CLI's native `--json-schema`. |\n| **ping** | Health check with CLI version, auth method, capabilities, and model config. |\n| **listSessions** | List active sessions with cumulative cost, turn count, and timestamps. |\n\n### query\n\nExecute 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.\n\nKey parameters: `prompt` (required), `files`, `model` (default `sonnet`), `sessionId`, `effort`, `maxBudgetUsd`, `workingDirectory`, `timeout` (default 60s).\n\n### search\n\nWeb search powered by Anthropic's WebSearch tool via Claude CLI. Returns synthesized answers with source URLs.\n\nKey parameters: `query` (required), `model` (default `sonnet`), `maxResponseLength`, `maxBudgetUsd`, `timeout` (default 120s).\n\n### structured\n\nGenerate 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.\n\nKey parameters: `prompt` (required), `schema` (required, JSON string, max 20KB), `files`, `model` (default `sonnet`), `sessionId`, `maxBudgetUsd`, `timeout` (default 60s).\n\n### ping\n\nNo parameters. Returns CLI version, auth method (subscription/api-key/none), configured models, capabilities, and server version.\n\n### listSessions\n\nNo parameters. Returns active sessions with metadata: `sessionId`, `model`, `createdAt`, `lastUsedAt`, `turnCount`, `totalCostUsd`.\n\nAll tools attach execution metadata (`_meta`) with `durationMs`, `model`, `sessionId`, `totalCostUsd`, and token breakdowns. See [DESIGN.md](DESIGN.md) for details.\n\n## Configuration\n\n### Models\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_DEFAULT_MODEL` | | Shared default for all tools |\n| `CLAUDE_QUERY_MODEL` | `sonnet` | Default for query |\n| `CLAUDE_STRUCTURED_MODEL` | `sonnet` | Default for structured |\n| `CLAUDE_SEARCH_MODEL` | `sonnet` | Default for search |\n| `CLAUDE_FALLBACK_MODEL` | `haiku` | Fallback on quota exhaustion (`none` to disable) |\n\nModel resolution: explicit parameter > tool-specific env var > `CLAUDE_DEFAULT_MODEL` > built-in default.\n\n### Runtime\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_MAX_CONCURRENT` | `3` | Max concurrent subprocess spawns |\n| `CLAUDE_CLI_PATH` | `claude` | Path to CLI binary |\n| `CLAUDE_MAX_BUDGET_USD` | | Global cost cap in USD (per call) |\n| `ANTHROPIC_API_KEY` | | API key (only forwarded when `CLAUDE_BRIDGE_USE_API_KEY=1`) |\n| `CLAUDE_BRIDGE_USE_API_KEY` | | Set to `1` to forward `ANTHROPIC_API_KEY` to the subprocess (default: subscription auth) |\n\n### Effort\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_SEARCH_EFFORT` | `medium` | Default effort for search |\n| `CLAUDE_QUERY_EFFORT` | | Default effort for query |\n\n### Tools\n\nEach spawned subprocess gets an explicit built-in toolset. The defaults are read-only, so `Bash`, `Write` and `Edit` are not granted unless you widen them below.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_QUERY_TOOLS` | `Read Glob Grep` | Built-in tools for query |\n| `CLAUDE_STRUCTURED_TOOLS` | `Read Glob Grep` | Built-in tools for structured |\n| `CLAUDE_SEARCH_TOOLS` | `WebSearch WebFetch` | Built-in tools for search |\n\nAccepts a comma or space separated list, `default` for the CLI's full built-in set, or an empty value for no tools. Widening these gives the subprocess real capability in the working directory you pass it. See [SECURITY.md § Tool Sandboxing](SECURITY.md#tool-sandboxing).\n\n## Choosing a Claude Code MCP server\n\n| You need... | Consider |\n|-------------|----------|\n| Structured output, effort/budget control, session resume, cost metadata | This bridge |\n| Multi-tool orchestration (read, grep, edit, bash as separate MCP tools) | [mcp-claude-code](https://github.com/SDGLBL/mcp-claude-code) |\n| Session continuity with async execution | [claude-mcp](https://github.com/zhendalf/claude-mcp) |\n| Maintained lightweight wrapper | [@kunihiros/claude-code-mcp](https://github.com/KunihiroS/claude-code-mcp) |\n| Native Claude Code MCP (built-in, no wrapper) | `claude mcp serve` ([docs](https://github.com/anthropics/claude-code)) |\n\n## Performance\n\nClaude Code CLI has minimal startup overhead. Wall time is dominated by model inference and any agentic exploration.\n\n| Scenario | Typical time |\n|----------|-------------|\n| Trivial prompt (sonnet) | 5-10s |\n| Web search + synthesis | 15-30s |\n\nCost metadata (`totalCostUsd`, token breakdowns) is returned in `_meta` on every response.\n\n## Bridge family\n\nTwo 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 both for cross-model workflows.\n\n| | [claude-mcp-bridge](https://github.com/hampsterx/claude-mcp-bridge) | [codex-mcp-bridge](https://github.com/hampsterx/codex-mcp-bridge) |\n|---|---|---|\n| **CLI** | Claude Code | Codex CLI |\n| **Provider** | Anthropic | OpenAI |\n| **Tools** | query, search, structured, ping, listSessions | codex, search, query, structured, ping, listSessions |\n| **Code review** | Use Claude Code built-ins directly (not via this bridge), or `claude -p` for non-Claude-Code hosts | `codex review --base <ref>` (native) or `codex` tool with caller-supplied prompt |\n| **Structured output** | Native `--json-schema` (no Ajv) | Ajv validation |\n| **Session resume** | Native `--resume` | Session IDs with multi-turn |\n| **Budget caps** | Native `--max-budget-usd` | Not supported |\n| **Effort control** | `--effort low/medium/high/max` | Not supported |\n| **Cold start** | ~1-2s | <100ms (inference dominates) |\n| **Auth** | `claude login` (default) or `ANTHROPIC_API_KEY` + opt-in | `OPENAI_API_KEY` |\n| **Cost** | Subscription (default) or API credits (opt-in) | Pay-per-token |\n| **Concurrency** | 3 (configurable) | 3 (configurable) |\n| **Model fallback** | Auto-retry with fallback model | Auto-retry with fallback model |\n\nBoth share: subprocess env isolation, path sandboxing, output redaction, FIFO concurrency queue, MCP tool annotations, `_meta` response metadata, progress heartbeats.\n\n## Code review with this CLI\n\nThe reviewer prompt is supplied by the caller. The bridge does not bundle review prompts (see [ADR-001](docs/decisions/001-no-bundled-prompts.md)).\n\n- **In Claude Code (interactive REPL)**: use the built-in `/review`, `/security-review`, `/ultrareview`. REPL-only; not reachable via `claude -p` or this bridge.\n- **Through this bridge** (`query` / `structured`): pass the review prompt as plain text. Slash commands (built-in or user-installed `~/.claude/commands/`) do not resolve through the bridge, the isolation flags (`--bare` on the API-key path, `--setting-sources \"\"` on the subscription path) block all skill resolution by design. Tracked upstream: [anthropics/claude-code#37207](https://github.com/anthropics/claude-code/issues/37207).\n- **Direct `claude -p` (no bridge)**: user skills resolve as `/skill-name` when no isolation flags suppress them. For subprocess-isolated review use the hardened invocation below.\n\nRoute based on where you are:\n\n- **Already in Claude Code?** Type `/review`, `/security-review`, or `/ultrareview`. Skip the rest of this section.\n- **Calling from another MCP host (Cursor, Codex CLI, Gemini CLI, Claude Desktop)?** Slash commands and skills are not reachable through the bridge. Pass your review prompt as plain text to `query` / `structured`, or invoke `claude -p` directly per below.\n\n### Direct `claude -p` invocation (subprocess-isolated)\n\nFor shell-equipped consumers (terminal agents, CI, BYOS skills), invoke the CLI directly with hardened isolation flags:\n\n```bash\nclaude -p \\\n  --permission-mode plan \\\n  --bare \\\n  --add-dir <repo-root> \\\n  --strict-mcp-config \\\n  --mcp-config '{\"mcpServers\":{}}' \\\n  --no-session-persistence \\\n  --max-budget-usd 0.50 \\\n  \"<your review prompt + diff or file references>\"\n```\n\n- `--permission-mode plan`: read-only.\n- `--bare`: strips parent's hooks, plugins, auto-memory, and `CLAUDE.md` autoload.\n- `--add-dir <repo-root>`: makes the repo's `CLAUDE.md` / `AGENTS.md` available where the diff warrants it.\n- `--strict-mcp-config --mcp-config '{\"mcpServers\":{}}'`: blocks parent's MCP servers from leaking in. The inner `mcpServers` key is required; the schema rejects bare `'{}'`.\n- `--no-session-persistence`: no session files for one-off reviews.\n- `--max-budget-usd`: per-call cost cap.\n\n### Claude Code skill template\n\nFor Claude Code users who want a reusable command, drop this into `~/.claude/commands/review-claude.md`:\n\n````markdown\n---\ndescription: Code review via subprocess-isolated claude -p\n---\n\nRun code review on the diff between origin/main and HEAD.\n\n```bash\nclaude -p \\\n  --permission-mode plan \\\n  --bare \\\n  --add-dir \"$(git rev-parse --show-toplevel)\" \\\n  --strict-mcp-config \\\n  --mcp-config '{\"mcpServers\":{}}' \\\n  --no-session-persistence \\\n  --max-budget-usd 0.50 \\\n  \"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.\n\n$(git diff origin/main...HEAD)\"\n```\n````\n\n### Representative review prompt\n\nA starting point; adapt freely:\n\n```text\nReview the following diff:\n\n<diff content>\n\nLook for:\n- Bugs that would surface in production\n- Missing error handling on user-supplied input\n- Tests modified to silence failures rather than verify behaviour\n- Security issues (injection, missing auth checks, secret leaks)\n\nFor each finding cite file:line, severity (high/medium/low), and a suggested fix.\nSkip style/formatting; assume an autoformatter handles those.\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build        # Compile TypeScript\nnpm run dev          # Watch mode\nnpm test             # Run tests (vitest)\nnpm run lint         # ESLint\nnpm run typecheck    # tsc --noEmit\nnpm run smoke        # Smoke test against live CLI\n```\n\n## Further reading\n\n- [DESIGN.md](DESIGN.md) - Architecture, sessions, cost tracking, response metadata, progress notifications\n- [SECURITY.md](SECURITY.md) - Environment isolation, path sandboxing, output redaction, tool sandboxing\n- [CHANGELOG.md](CHANGELOG.md) - Release history\n\n## License\n\nMIT\n",
  "bytes": 14521,
  "sha": "b7214f3e24523aa1aec963188aee65d679fcbb0ab82646868b83aefec682a85e",
  "repo_slug": "hampsterx/claude-mcp-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hampsterx_claude_mcp_bridge_53b52ce8/readme"
}