Claude MCP Bridge

What the hampsterx/claude-mcp-bridge MCP server does

The hampsterx/claude-mcp-bridge MCP server makes Claude Code CLI available as MCP tools. It is intended for MCP clients that need Claude Code capabilities without invoking the CLI directly from a shell. The bridge can handle code generation, analysis, refactoring, explanations, file-based tasks, web research, and machine-readable extraction.

The main query tool sends a prompt to Claude Code and can include text or image files, a working directory, model and effort settings, a session ID, and a per-call budget limit. structured produces JSON against a supplied JSON Schema using Claude Code's native schema option. search uses Claude Code's WebSearch and WebFetch tools, returning a synthesized response with source URLs. ping checks local CLI and authentication state, while listSessions reports tracked session metadata.

How it works

The bridge starts Claude Code CLI as a subprocess for each operation. Its MCP responses include execution metadata such as duration, model, session ID, total cost, and token counts. Query and structured calls can continue an earlier conversation by passing the returned session ID. Set noSessionPersistence for one-shot query behavior.

Each tool receives an explicit Claude Code tool set. The default query and structured sets are Read, Glob, and Grep; search defaults to WebSearch and WebFetch. This keeps write, edit, and shell capabilities unavailable unless the configuration is widened. A working directory gives Claude Code project context, and the files parameter supplies targeted text or image context. Images supported by the CLI include PNG, JPG, GIF, WEBP, and BMP files up to 5 MB each.

Setup and configuration

Install the hampsterx/claude-mcp-bridge MCP server with npx -y claude-mcp-bridge. Claude Code CLI must already be installed and available on PATH, and it must be authenticated. The default authentication path uses claude login with a Claude Pro or Max subscription. API-key authentication is also supported by setting ANTHROPIC_API_KEY and CLAUDE_BRIDGE_USE_API_KEY=1.

Model defaults can be set globally or per tool with variables such as CLAUDE_DEFAULT_MODEL, CLAUDE_QUERY_MODEL, CLAUDE_STRUCTURED_MODEL, and CLAUDE_SEARCH_MODEL. Runtime controls include CLAUDE_MAX_CONCURRENT, CLAUDE_CLI_PATH, and CLAUDE_MAX_BUDGET_USD. Tool access is configured through CLAUDE_QUERY_TOOLS, CLAUDE_STRUCTURED_TOOLS, and CLAUDE_SEARCH_TOOLS. The schema passed to structured must be a JSON string no larger than 20 KB.

Tools and capabilities

• query: Run prompts with file context, model and effort selection, session resume, working-directory context, and budget caps.
• structured: Return schema-conforming JSON for extraction, classification, and entity parsing tasks.
• search: Research current information, documentation, APIs, and library comparisons with source URLs.
• listSessions: Inspect active sessions, models, turn counts, timestamps, and cumulative costs.
• ping: Verify CLI installation, authentication, capabilities, versions, and configuration.

Sonnet is the default model, with typical stated costs of roughly $0.01–$0.10 per call for query or structured work and about $0.02–$0.05 per search. maxBudgetUsd limits individual calls, and a fallback model can be configured for quota exhaustion. The hampsterx/claude-mcp-bridge MCP server is useful when an MCP client cannot use a shell, needs validated JSON, or must preserve conversations across calls.