# Claude Code MCP Bridge

A stateless MCP (Model Context Protocol) server that exposes Claude Code's capabilities as individual tools for any MCP-compatible host to consume.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io)
[![Built with FastMCP](https://img.shields.io/badge/built_with-FastMCP-purple.svg)](https://github.com/jlowin/fastmcp)

---

## Why This Exists

Claude Code is a powerful coding agent, but its primary interface is an interactive terminal. Hosting it as an MCP server lets any MCP-compatible agent or application invoke Claude Code's file editing, command execution, and test-running capabilities as discrete, composable tools — without pty management, terminal UI, or session lifecycle.

The stateless architecture was a deliberate tradeoff: each tool call spawns a fresh `claude -p` (print-mode) subprocess instead of maintaining a persistent session. This avoids the fragile prompt-pattern matching, first-run wizards, theme selectors, and pty state management that a persistent session requires. The cost is a ~5s cold-start latency per call; the benefit is zero session-related failures.

## Tools

### cc_execute_command

Run arbitrary commands through Claude Code. It handles shell execution, file system operations, package management, and any terminal-compatible task.

| Parameter | Type | Description |
|-----------|------|-------------|
| `command` | string (required) | The command to execute |
| `workdir` | string (optional) | Working directory (defaults to current) |
| `timeout` | integer (optional) | Max seconds to wait (default 120) |

Returns `exit_code`, `stdout`, `stderr`, and a `truncated` flag if output exceeded limits.

### cc_edit_file

Make targeted edits to files using Claude Code's semantic understanding. Unlike raw sed or regex, this tool identifies the correct location even when indentation or minor formatting varies.

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | string (required) | File to edit |
| `old_string` | string (required) | Existing text to replace |
| `new_string` | string (required) | Replacement text |
| `language` | string (optional) | Language hint for syntax-aware editing |

Returns `success`, `diff` (unified format), `syntax_ok`, and `warnings`.

### cc_run_tests

Run test commands through Claude Code and receive structured results. Parses test output into summary, failure details, and timing.

| Parameter | Type | Description |
|-----------|------|-------------|
| `command` | string (required) | Test command to run |
| `watch` | boolean (optional) | Watch mode (default false) |

Returns `summary` (total/passed/failed/skipped), `failures` array, and `duration_seconds`.

## Quick Start

```bash
# Prerequisites
# - Python 3.11+
# - Claude Code installed and authenticated (claude command in PATH)
# - OPENAI_API_KEY or ANTHROPIC_API_KEY for Claude Code

git clone https://github.com/alexscarano/claude-code-mcp.git
cd claude-code-mcp

# Option A: uv (recommended)
uv sync
uv run python server.py

# Option B: pip
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

# Option C: run.sh (auto-detects uv or pip)
./run.sh
```

The server starts in stdio mode, which is the standard transport for MCP. Configure your MCP host to spawn the server as a subprocess.

## Configuration

| Variable | Default | Notes |
|----------|---------|-------|
| `CLAUDE_BIN` | `claude` | Path to the Claude Code binary |

Set via environment variable:

```bash
export CLAUDE_BIN=/path/to/claude
./run.sh
```

## Architecture

```
MCP Host (e.g. Hermes Agent)
  │  stdio transport
  ▼
server.py (FastMCP entry point)
  │
  ├── cc_edit_file      → session._run() → claude -p ...
  ├── cc_execute_command → session._run() → claude -p ...
  └── cc_run_tests      → session._run() → claude -p ...
```

Each tool call:
1. Builds a prompt from a template (templates.py)
2. Forwards it to `claude -p --dangerously-skip-permissions`
3. Extracts the structured `<mcp-result>` response from stdout
4. Returns a validated dictionary to the caller

> **Note:** The `<mcp-result>` wrapping ensures the MCP host receives structured JSON rather than conversational text. Claude Code is instructed to emit only this tagged block, and `extract_result` parses it with a regex pattern.

## Constraints

- **Cold start**: Each call spawns a fresh subprocess (~5s overhead). Not suited for high-frequency invocation.
- **Permission model**: Uses `--dangerously-skip-permissions`. The tool's host is responsible for access control — review what commands are sent to the server.
- **Timeout handling**: The server imposes a configurable per-call timeout (default 120s). Long-running commands may need adjustment.
- **Prompt size**: Very large prompts (100KB+) increase processing time. The prompt is passed as a CLI argument, constrained by `ARG_MAX` (typically 2MB on Linux).

## When to Use This vs Direct Claude Code

**Use this bridge when:**
- Your primary agent needs occasional code modifications or analysis
- You want composable tool invocations (call edit, then test, then commit)
- You run in an environment where maintaining a persistent pty is impractical
- You need structured, machine-parseable responses

**Use Claude Code directly when:**
- You need an interactive coding session with back-and-forth
- Latency per operation must be under 1 second
- You want the full Claude Code TUI experience

## License

MIT