claude-bridge-mcp

A production-quality Model Context Protocol (MCP) server that lets ChatGPT — or any MCP client — securely delegate coding tasks to a local Claude Code instance.

ChatGPT plans and orchestrates; Claude Code executes inside git-checkpointed, security-guarded project folders; the bridge returns structured results (summary, diff, changed files, test output, usage) so the conversation can continue with full context.

The bridge orchestrates Claude Code — it does not bypass Claude limits, permissions, or billing. When Claude is unavailable, analysis work (reviews) can fail over to other configured providers.

┌────────────────────────────────────────────┐
│  ChatGPT / any MCP client                  │
│  plans tasks • reads results • iterates    │
└─────────────────────┬──────────────────────┘
                      │ MCP (stdio or Streamable HTTP)
┌─────────────────────▼──────────────────────┐
│  claude-bridge-mcp                         │
│  ┌──────────┐ ┌─────────┐ ┌─────────────┐  │
│  │ Security │ │   Git   │ │  Approvals  │  │
│  │  guard   │ │workspace│ │    queue    │  │
│  └────┬─────┘ └────┬────┘ └──────┬──────┘  │
│       └─────┬──────┴─────────────┘         │
│      ┌──────▼───────┐   ┌───────────────┐  │
│      │   Executor   │   │  Dashboard    │  │
│      │    router    │   │  (localhost)  │  │
│      └──────┬───────┘   └───────────────┘  │
└─────────────┼──────────────────────────────┘
       ┌──────┼──────────┬──────────┐
┌──────▼───┐ ┌▼────────┐ ┌▼───────┐ ┌▼───────┐
│ Claude   │ │ OpenAI  │ │ Gemini │ │ Ollama │
│ Code CLI │ │ (API)   │ │ (API)  │ │ (local)│
│ code+rev │ │ fallback│ │fallback│ │fallback│
└──────────┘ └─────────┘ └────────┘ └────────┘

Features

• delegate_to_claude — run an engineering task with the local Claude Code CLI: validates the project against an allowlist, creates a git checkpoint, executes headless, returns summary + sanitized diff + changed files + exit code + token/cost usage.

• review_changes — structured code review (quality, bugs, security, performance, architecture) of any diff or of a project's pending changes.

• run_tests — detects npm/pnpm/yarn/bun/pytest/cargo/go, installs dependencies if needed, runs tests, returns a structured result.

• status — current project, branch, modified files, latest task, pending approvals, executor health, estimated usage.

• approve_action / rollback_checkpoint — human approval gate for dangerous operations, and one-call rollback to any pre-task checkpoint.

• Multi-provider routing — Claude first; OpenAI / Gemini / Ollama as analysis fallbacks when Claude is unavailable or rate-limited.

• Security by default — approved-project allowlist, blocked-command policy with single-use approval tokens, secret redaction on every output, no shell-interpolated commands, full audit logging.

• Web dashboard — running tasks, logs, token estimates, recent executions, executor health, approval queue with approve/deny buttons.

Related MCP server: cc-agent

Quick start

git clone <this repo> && cd claude-bridge-mcp
npm install && npm run build
cp config.example.yaml config.yaml   # then edit approved_projects
npm start                            # stdio transport by default

Requirements: Node ≥ 20, git, and the Claude Code CLI installed and authenticated (claude --version must work).

See docs/installation.md for connecting from ChatGPT (Streamable HTTP) and Claude Desktop (stdio).

The tools

Every tool returns a structured JSON envelope: success, reason (on failure), payload fields, and next_steps. Tools never crash the server — errors become structured failures.

Typical flow

1. ChatGPT calls delegate_to_claude with a project path and a task.

2. The bridge validates the path, checks the task against the blocked-operation policy, creates a git checkpoint, and runs Claude Code headless.

3. The result comes back with a summary, a sanitized diff, and the changed file list.

4. ChatGPT calls review_changes and run_tests, reads the findings, and either iterates (another delegate_to_claude) or asks for rollback_checkpoint.

Documentation

• Installation & client setup

• Architecture

• Configuration reference

• Security model

• Developer guide

• Usage examples

Development

npm test          # vitest: unit + integration + security tests
npm run typecheck
npm run build

License

MIT