claude-mcp-bridge

# claude-mcp-bridge

[![npm version](https://img.shields.io/npm/v/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)
[![npm downloads](https://img.shields.io/npm/dm/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)
[![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)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/node/v/claude-mcp-bridge)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io/)
[![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/claude-mcp-bridge)

MCP 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.

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:

```bash
# 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` 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](#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

```bash
npx claude-mcp-bridge
```

### Prerequisites

- [Claude Code CLI](https://github.com/anthropics/claude-code) 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`:
```json
{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`:
```json
{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}
```

### Cursor / Windsurf / VS Code

Add to your MCP settings:
```json
{
  "claude-bridge": {
    "command": "npx",
    "args": ["-y", "claude-mcp-bridge"],
    "env": {
      "ANTHROPIC_API_KEY": "sk-ant-...",
      "CLAUDE_BRIDGE_USE_API_KEY": "1"
    }
  }
}
```

## 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](#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](DESIGN.md) for details.

## Configuration

### Models

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_DEFAULT_MODEL` | | Shared default for all tools |
| `CLAUDE_QUERY_MODEL` | `sonnet` | Default for query |
| `CLAUDE_STRUCTURED_MODEL` | `sonnet` | Default for structured |
| `CLAUDE_SEARCH_MODEL` | `sonnet` | Default for search |
| `CLAUDE_FALLBACK_MODEL` | `haiku` | Fallback on quota exhaustion (`none` to disable) |

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

### Runtime

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_MAX_CONCURRENT` | `3` | Max concurrent subprocess spawns |
| `CLAUDE_CLI_PATH` | `claude` | Path to CLI binary |
| `CLAUDE_MAX_BUDGET_USD` | | Global cost cap in USD (per call) |
| `ANTHROPIC_API_KEY` | | API key (only forwarded when `CLAUDE_BRIDGE_USE_API_KEY=1`) |
| `CLAUDE_BRIDGE_USE_API_KEY` | | Set to `1` to forward `ANTHROPIC_API_KEY` to the subprocess (default: subscription auth) |

### Effort

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_SEARCH_EFFORT` | `medium` | Default effort for search |
| `CLAUDE_QUERY_EFFORT` | | Default effort for query |

### Tools

Each 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.

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_QUERY_TOOLS` | `Read Glob Grep` | Built-in tools for query |
| `CLAUDE_STRUCTURED_TOOLS` | `Read Glob Grep` | Built-in tools for structured |
| `CLAUDE_SEARCH_TOOLS` | `WebSearch WebFetch` | Built-in tools for search |

Accepts 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).

## Choosing a Claude Code MCP server

| You need... | Consider |
|-------------|----------|
| Structured output, effort/budget control, session resume, cost metadata | This bridge |
| Multi-tool orchestration (read, grep, edit, bash as separate MCP tools) | [mcp-claude-code](https://github.com/SDGLBL/mcp-claude-code) |
| Session continuity with async execution | [claude-mcp](https://github.com/zhendalf/claude-mcp) |
| Maintained lightweight wrapper | [@kunihiros/claude-code-mcp](https://github.com/KunihiroS/claude-code-mcp) |
| Native Claude Code MCP (built-in, no wrapper) | `claude mcp serve` ([docs](https://github.com/anthropics/claude-code)) |

## Performance

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

| Scenario | Typical time |
|----------|-------------|
| Trivial prompt (sonnet) | 5-10s |
| Web search + synthesis | 15-30s |

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

## Bridge family

Two 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.

| | [claude-mcp-bridge](https://github.com/hampsterx/claude-mcp-bridge) | [codex-mcp-bridge](https://github.com/hampsterx/codex-mcp-bridge) |
|---|---|---|
| **CLI** | Claude Code | Codex CLI |
| **Provider** | Anthropic | OpenAI |
| **Tools** | query, search, structured, ping, listSessions | codex, search, query, structured, ping, listSessions |
| **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 |
| **Structured output** | Native `--json-schema` (no Ajv) | Ajv validation |
| **Session resume** | Native `--resume` | Session IDs with multi-turn |
| **Budget caps** | Native `--max-budget-usd` | Not supported |
| **Effort control** | `--effort low/medium/high/max` | Not supported |
| **Cold start** | ~1-2s | <100ms (inference dominates) |
| **Auth** | `claude login` (default) or `ANTHROPIC_API_KEY` + opt-in | `OPENAI_API_KEY` |
| **Cost** | Subscription (default) or API credits (opt-in) | Pa