claude-delegate-local-mcp

An MCP server that lets Claude Code hand work to a local model you host yourself.

Bulk, mechanical, read-heavy work — reading a subsystem, writing tests, mechanical refactors, first-pass review — costs cloud tokens even when the reasoning required is modest. This moves that class of work onto your own hardware, where it is effectively free, and keeps Claude for the parts that need it.

See PLAN.md for what is open, and archive/PLAN-milestones.md for the roadmap that closed.

How it works

Two shapes of delegation, and the second is the interesting one:

• One-shot — the server reads the files you name and answers from them in a single prompt, so their contents never reach your context. Good for review, summary and explanation. delegate_readonly() is this shape guaranteed rather than chosen, which is what lets a caller run it where a write would not be allowed.

• Agentic — the local model gets its own tools and iterates: write, run the tests, read the real failure, try again, at no cloud token cost, then hand back a result for Claude to review.

That second loop is why a shell exists, why it is confined by bubblewrap, what happens when bubblewrap is absent, and why the server watches process exit codes rather than the model's account of them.

How each of those works is docs/ARCHITECTURE.md and docs/DISPATCH.md; this file names them and links, and deliberately does not restate them.

Related MCP server: cctx

What it is not

• Not a cloud router. One backend format ships — OpenAI-compatible. Anthropic-compatible endpoints are a planned addition behind an existing seam, not a current feature.

• Not a way to run Claude Code against a different model. It delegates tasks; Claude Code stays Claude Code.

• Not a sandbox for untrusted code. It confines a model you chose to run against a workspace you chose to expose.

Requirements

• A local OpenAI-compatible endpoint (this was built against vLLM serving DeepSeek V4 Flash on two DGX-Spark-class machines, but nothing depends on that specific stack).

• Python 3.11+.

• Linux, or WSL2 on Windows — bubblewrap is Linux-only, so the server runs there even when Claude Code does not (why).

Install

git clone https://github.com/ComputerSaysNull/claude-delegate-local-mcp
cd claude-delegate-local-mcp

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
python scripts/install_hooks.py       # optional, gives the gate at commit time

claude-delegate-local-mcp --init      # writes .env and models.toml from answers
claude-delegate-local-mcp --doctor    # checks the environment; non-zero on any failure
claude-delegate-local-mcp provision . # optional, so a delegation can run this project's tests

--init asks what has no safe default, shows the default for everything else it offers, never overwrites what is already there (what it does with it), and prints the registration block below filled in for this machine. Copying the two .example files by hand still works.

Run the doctor before the first delegation. The server starts whether or not what it needs is there, so a missing root or an unreachable endpoint otherwise surfaces much later, inside whichever delegation happens to reach it (why).

provision is needed only for run_bash to run a Python project's tests. It builds a virtualenv outside the workspace — why there, and what keeps it in step. Reading, writing and reviewing files need none of it.

On Windows plus WSL2 the two interpreters cannot share .venv: a Linux python -m venv .venv overwrites a Windows one in place, and it reads as a corrupted install rather than a collision. Put the WSL one elsewhere, on the native filesystem rather than /mnt/c where creating it is ~27x slower (ADR-0020) — python3 -m venv ~/.venvs/delegate, then ~/.venvs/delegate/bin/pip install -e /mnt/c/path/to/the/repo. That is the runtime only; CONTRIBUTING.md adds [dev] to the same venv for tests.

.env is read by config.load() as a fallback: anything already set in the environment wins, so an explicit override still works. Point DELEGATE_ENV_FILE at another file to use one elsewhere — if it names a file that does not exist, that is an error rather than a silent fall back to defaults. ADR-0027 for why the server reads the file itself instead of taking an env key from your MCP client's configuration.

.env and models.toml are gitignored, deliberately — MODELS.md says why.

On Windows, with the server in WSL2

wsl --install -d Ubuntu-24.04

Then inside Ubuntu — and verify rather than assume, because two of these fail silently:

sudo apt install -y bubblewrap python3 python3-venv git
bwrap --unshare-all --ro-bind /usr /usr --ro-bind /etc /etc --proc /proc \
      --dev /dev --tmpfs /tmp --symlink usr/bin /bin --symlink usr/lib /lib \
      --symlink usr/lib64 /lib64 -- /bin/echo ok      # must print: ok
getent hosts YOUR-HEAD-NODE                           # must resolve in WSL, not just Windows

The usr/lib64 symlink is not optional on x86-64: without it nothing dynamically linked runs, and the error blames the executable rather than the missing loader.

Register with Claude Code

Native Linux:

{ "mcpServers": { "delegate-local": {
    "command": "claude-delegate-local-mcp",
    "timeout": 900000
} } }

Windows, server in WSL2:

{ "mcpServers": { "delegate-local": {
    "command": "wsl.exe",
    "args": ["-d", "Ubuntu-24.04",
             "--cd", "C:\path\to\claude-delegate-local-mcp",
             "-e", "/home/YOU/.venvs/delegate/bin/claude-delegate-local-mcp"],
    "timeout": 900000
} } }

--cd and the script's absolute path are both load-bearing: without them the server starts in the wrong directory or is not found at all, and neither failure names its own cause — TROUBLESHOOTING has both symptoms. Give --cd the Windows form of the path; /mnt/c/... is rejected.

timeout is milliseconds and the wall-clock default is generous. The per-turn progress notification holds off the separate stdio idle timeout but does not extend the wall clock.

Documentation

No configuration default is stated anywhere but src/claude_delegate_local/config.py, which is where they live; docs/CONFIGURATION.md is generated from it and is a rendering, never a source to edit. If you find one repeated elsewhere, that is a bug — CLAUDE.md explains the scheme.

Provenance and licence

MIT. A derivative work, not an independent implementation: substantial code was ported from fegone/claude-code-delegate-local and its mixicz fork, both MIT. The server-side context-prefetch idea comes from fjgbue/claude-delegator-deepseek-mcp. NOTICE records what came from where, feature by feature.