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.

---

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:

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