# claude-mcp-bridge

This MCP server exposes Claude Code CLI through tools for prompting, web search, schema-checked JSON, health checks, and session tracking.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: hampsterx
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/hampsterx/claude-mcp-bridge
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/mcp/claude-mcp-bridge

## What it does

claude-mcp-bridge runs Claude Code CLI as a child process and makes its capabilities available to MCP clients. Its tools are `query`, `search`, `structured`, `ping`, and `listSessions`. They cover file-aware prompts, web lookup, JSON Schema output, service checks, and active-session metadata. Responses also include model, duration, token, and cost details.

\`query` accepts files, images, session continuation, effort settings, and a per-call budget limit. `structured` returns JSON checked against a supplied schema, while `search` produces a synthesized answer with source URLs. The Claude Code CLI must be installed on `PATH`, and the process must be authenticated. Authentication uses `claude login`, or `ANTHROPIC_API_KEY` together with `CLAUDE_BRIDGE_USE_API_KEY=1`.

Run the server with `npx` and configure its CLI and model settings through environment variables. The listed clients include Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and other MCP-compatible tools.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `CLAUDE_CLI_PATH`, `CLAUDE_DEFAULT_MODEL`, `CLAUDE_QUERY_MODEL`, `CLAUDE_STRUCTURED_MODEL`, `CLAUDE_SEARCH_MODEL`, `CLAUDE_FALLBACK_MODEL`, `CLAUDE_MAX_CONCURRENT`, `CLAUDE_BRIDGE_USE_API_KEY`, `CLAUDE_MAX_BUDGET_USD`, `CLAUDE_QUERY_TOOLS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env CLAUDE_CLI_PATH=<CLAUDE_CLI_PATH> --env CLAUDE_DEFAULT_MODEL=<CLAUDE_DEFAULT_MODEL> --env CLAUDE_QUERY_MODEL=<CLAUDE_QUERY_MODEL> --env CLAUDE_STRUCTURED_MODEL=<CLAUDE_STRUCTURED_MODEL> --env CLAUDE_SEARCH_MODEL=<CLAUDE_SEARCH_MODEL> --transport stdio claude-mcp-bridge -- npx -y claude-mcp-bridge
```
Replace <…> with your own values. 9 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add claude-mcp-bridge --env CLAUDE_CLI_PATH=<CLAUDE_CLI_PATH> --env CLAUDE_DEFAULT_MODEL=<CLAUDE_DEFAULT_MODEL> --env CLAUDE_QUERY_MODEL=<CLAUDE_QUERY_MODEL> --env CLAUDE_STRUCTURED_MODEL=<CLAUDE_STRUCTURED_MODEL> --env CLAUDE_SEARCH_MODEL=<CLAUDE_SEARCH_MODEL> -- npx -y claude-mcp-bridge
```
Replace <…> with your own values. 9 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "claude-mcp-bridge": {
            "command": "npx",
            "args": [
                "-y",
                "claude-mcp-bridge"
            ],
            "env": {
                "CLAUDE_CLI_PATH": "<CLAUDE_CLI_PATH>",
                "CLAUDE_DEFAULT_MODEL": "<CLAUDE_DEFAULT_MODEL>",
                "CLAUDE_QUERY_MODEL": "<CLAUDE_QUERY_MODEL>",
                "CLAUDE_STRUCTURED_MODEL": "<CLAUDE_STRUCTURED_MODEL>",
                "CLAUDE_SEARCH_MODEL": "<CLAUDE_SEARCH_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 9 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "claude-mcp-bridge": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "claude-mcp-bridge"
            ],
            "env": {
                "CLAUDE_CLI_PATH": "<CLAUDE_CLI_PATH>",
                "CLAUDE_DEFAULT_MODEL": "<CLAUDE_DEFAULT_MODEL>",
                "CLAUDE_QUERY_MODEL": "<CLAUDE_QUERY_MODEL>",
                "CLAUDE_STRUCTURED_MODEL": "<CLAUDE_STRUCTURED_MODEL>",
                "CLAUDE_SEARCH_MODEL": "<CLAUDE_SEARCH_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 9 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CLAUDE_CLI_PATH=<CLAUDE_CLI_PATH> -e CLAUDE_DEFAULT_MODEL=<CLAUDE_DEFAULT_MODEL> -e CLAUDE_QUERY_MODEL=<CLAUDE_QUERY_MODEL> -e CLAUDE_STRUCTURED_MODEL=<CLAUDE_STRUCTURED_MODEL> -e CLAUDE_SEARCH_MODEL=<CLAUDE_SEARCH_MODEL> claude-mcp-bridge npx -y claude-mcp-bridge
```
Replace <…> with your own values. 9 more environment variables are in the server README

## When to use it
- send Claude Code prompts through an MCP client
- resume a session across separate calls
- return JSON that follows a schema
- run web searches through Claude CLI
- inspect CLI authentication and health

## Example prompts
- Use `query` to inspect `src/utils/parse.ts` for edge cases.
- Use `structured` to return the result as JSON matching this schema.
- Use `search` to find current sources on this topic and include their URLs.

## Similar
- [memory-bridge](https://affpapa.org/en/nevibecode/skills/memory-bridge.md) — skill · 2400 installs
- [nemo-mbridge-mlm-bridge-training](https://affpapa.org/en/nevibecode/skills/nemo-mbridge-mlm-bridge-training.md) — skill · 1800 installs
- [cc-connect-ai-bridge](https://affpapa.org/en/nevibecode/skills/cc-connect-ai-bridge.md) — skill · 935 installs
- [experiment-bridge](https://affpapa.org/en/nevibecode/skills/experiment-bridge.md) — skill · 497 installs
- [zotero-obsidian-bridge](https://affpapa.org/en/nevibecode/skills/zotero-obsidian-bridge.md) — skill · 473 installs
- [Codex Bridge](https://affpapa.org/en/nevibecode/mcp/codex-bridge.md) — MCP server · ★ 285

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md