# hampsterx/claude-mcp-bridge [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/hampsterx/claude-mcp-bridge  
**GitHub Stars:** 6  
**npm Downloads (last month):** 429  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hampsterx-claude-mcp-bridge

## Description
Wraps Claude Code CLI as MCP tools (query, search, structured, sessions) with subscription-first auth, cost metadata, budget caps, and granular tool sandboxing.

## Tools
Capabilities this server exposes over MCP:

- **query** — Execute a prompt via Claude Code CLI with optional file context and session resume. Claude is an AI coding agent that can generate, analyze, refactor, and explain code.

Capabilities: code generation and refactoring, code analysis and explanation, file understanding (text and images), multi-turn conversations via sessionId.

Cost: Default model is Sonnet (~$0.01-0.10/call). Use effort="low" for simple tasks, effort="high" + model="opus" for complex analysis. Set maxBudgetUsd to cap per-call cost (recommended for effort="max" or model="opus").

Tips:
- Set workingDirectory to the target repo for project-aware responses.
- Break complex tasks into focused prompts rather than one large request.
- Resume multi-turn conversations with sessionId from a previous response's metadata.
- Include relevant files via the files parameter for targeted context (text files inlined in prompt, images trigger allowed-tools mode).
- Use noSessionPersistence=true for stateless one-shot calls.
- **structured** — Generate JSON conforming to a provided JSON Schema. Uses Claude CLI's native --json-schema flag for validated output (not client-side validation).

Use for: data extraction from text/files, classification, entity parsing, or any task needing machine-parseable output.

Cost: Similar to query (~$0.01-0.10/call). Schema complexity doesn't significantly affect cost.

Tips:
- Pass the JSON Schema as a JSON string in the schema parameter.
- Schema max size: 20KB. Keep schemas focused for reliable output.
- For extraction tasks, include source text via the files parameter or inline in the prompt.
- **search** — Web search via Claude Code CLI using WebSearch and WebFetch tools. Searches the web and synthesizes a comprehensive answer with source URLs.

Use for: current information, documentation lookups, API references, comparing libraries, and research questions.

Cost: Typically ~$0.02-0.05/search with Sonnet.

Tips:
- Ask specific, focused questions for best results.
- Results include source URLs for verification.
- Use maxResponseLength to control response verbosity.
- Increase timeout for complex research queries that may require multiple web fetches.
- **listSessions** — List active Claude CLI sessions tracked by this server. Returns session metadata (IDs, models, timing, turn counts, cumulative cost) for orchestration. Use to check available sessions before resuming with sessionId. No cost (local lookup only).
- **ping** — Health check: verifies Claude CLI is installed and authenticated, reports versions, capabilities, and configuration. No cost (local check only).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "claude-mcp-bridge": {
    "command": "npx",
    "args": ["-y","claude-mcp-bridge"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/hampsterx-claude-mcp-bridge/readme_