claude-mcp

MCP server that turns Claude Code into a structured software-engineering worker that an orchestrator (e.g. Hermes) can drive over HTTP: submit a coding task, poll for a normalized result, then resume or review it — instead of shelling out to claude -p.

Milestones 1–7 are complete. For architecture, the full tool/result contract, configuration, and deployment, see docs/system-details.md.

Requirements

• Python 3.12–3.14

• The claude CLI installed and authenticated (claude_health reports whether it is visible and logged in)

Related MCP server: Code Worker MCP

Quick setup

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
./setup.sh

./setup.sh is interactive: it asks for the values that must be set (only workspace.projects_root is required — the rest have defaults), writes your per-machine config/worker.yaml, generates a systemd unit, and can install and start the service. To do it by hand instead:

cp config/worker.yaml.example config/worker.yaml   # then set workspace.projects_root
python -m claude_mcp                                # serves http://127.0.0.1:8765/mcp

config/worker.yaml is per-machine and gitignored; projects_root (where the worker may operate) is the one value with no default. Full configuration and the systemd service are covered in the system details.

Connect an orchestrator

Register the server as a streamable-HTTP MCP server:

{
  "mcpServers": {
    "claude-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Then call claude_health (no arguments). It returns {"status": "ok", ...} plus claude_cli.found and auth.logged_in — gate delegation on both being true.

Usage: the tools

Minimal flow — submit an implement task:

{
  "project": "<projects_root>/myapp",
  "mode": "implement",
  "task": { "objective": "Add a /health endpoint returning 200 {\"status\":\"ok\"}" }
}

It returns {"status": "queued", "job_id": "claude-…"}. Poll claude_get_task(job_id) until the status is terminal (completed, failed, timeout, cancelled, or blocked); a completed result carries summary, files_changed, and commit. The complete input/output schema, error codes, and hands-on recipes are in the system details and the skill references below.

How it works alongside the skill

The MCP server is the mechanism; the companion skill is the playbook. This repo ships an agent skill at skills/claude-mcp-worker/ that teaches an orchestrator when and how to use these tools: the golden rule (delegate any code change to claude_run_task rather than editing files directly), the submit → poll → resume → review flow, and gating on claude_health before delegating. Point your orchestrator at both — the server URL above, and the skill (SKILL.md plus references/{tool-reference,result-schema,testing-recipe}.md).

Test

pytest -v

Learn more

• docs/system-details.md — architecture, milestones & roadmap, full configuration, systemd deployment, and the complete tool/result contract.

• skills/claude-mcp-worker/ — the orchestrator-facing skill and its references.

• docs/superpowers/ — per-milestone specs and plans.