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 Python 3.11+ MCP Built with 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

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

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:

Builds a prompt from a template (templates.py)
Forwards it to claude -p --dangerously-skip-permissions
Extracts the structured <mcp-result> response from stdout
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