claude-mcp-bridge — Claude Code MCP server: setup
This MCP server exposes Claude Code CLI through tools for prompting, web search, schema-checked JSON, health checks, and session tracking.
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-bridgeWhat claude-mcp-bridge 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.
What it helps with
- 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 for the agent
- Use
queryto inspectsrc/utils/parse.tsfor edge cases. - Use
structuredto return the result as JSON matching this schema. - Use
searchto find current sources on this topic and include their URLs.
How to install claude-mcp-bridge
Platform CLI
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-bridgeReplace <…> with your own values. 9 more environment variables are in the server README
Platform CLI
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-bridgeReplace <…> with your own values. 9 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-bridgeReplace <…> with your own values. 9 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about claude-mcp-bridge
How do I install claude-mcp-bridge in Claude Code?
Run claude mcp add claude-mcp-bridge -- npx -y claude-mcp-bridge.
What does claude-mcp-bridge do?
It wraps Claude Code CLI as an MCP server and exposes tools for prompts, web search, schema-validated JSON, health checks, and session listing.
What does claude-mcp-bridge require?
Claude Code CLI must be installed on PATH and authenticated with claude login, or with ANTHROPIC_API_KEY plus CLAUDE_BRIDGE_USE_API_KEY=1.
