claude-delegate-local-mcp

一个 MCP 服务器,让 Claude Code 可以把工作交给你自己托管的本地模型。

批量、机械性、以读取为主的工作——通读一个子系统、编写测试、机械性重构、首轮审查——即使所需的推理能力并不高,也照样消耗云端 token。这一类工作被放到你自己的计算资源上运行,在那儿使用几乎免费,而 Claude 则只用在真正需要它的部分。

状态:早期。 配置、模型注册表和文档工具均已就绪并通过测试,但委托工具本身尚未构建。实际进展见 STATUS.md,路线见 PLAN.md。

工作原理

委托有两种形态,第二种才是关键:

• 一次性 —— 文件内容在服务器端读取,并内联到单条提示词中。模型作出回答;文件字节从未进入 Claude 的上下文。适合审查、总结、解释。

• 代理式 —— 本地模型获得自己的 read_file、write_file 和 run_bash,并不断迭代。它自己写代码、运行你的测试套件、读取真实失败,修复它,然后再运行——需要多少轮就跑多少轮,零云端 token 成本——然后把结果交还给 Claude 审查。

第二个循环正是 shell 存在的原因,也是 run_bash 为何被 bubblewrap 限制在空根沙箱中、默认关闭网络的原因。如果 bubblewrap 不可用,服务器拒绝运行 shell 命令,而不是不加沙镇地运行。

服务器还会自行精心捕获真实的进程退出码,并单独报告,与模型在回答里声称的任何结果分开。模型经常谎报命令结果;没有基准真值,整个自我验证首先要集体崩溃。

Related MCP server: local-llm-mcp

它不是什么

• 不是云端路由器。随产品附带一种后端格式——兼容 OpenAI。Anthropic 兼容端点属于既有接缝的后续计划,不是当前功能。

• 不是用别的模型去跑 Claude Code 的方法。它委托的是任务;Claude Code 依然是 Claude Code。

• 不是给不受信代码准备的沙箱。它只是约束你选好的模型,面向一个你选择暴露的工作区。

环境要求

• 一个本地 OpenAI 兼容端点(本目标是基于两台 DGX-Spark 级别机器上跑 vLLM 服务、提供 DeepSeek Tree Flash 的环境下开发的,但没有任何东西是必须靠那套特有栈)。

• Python 3.11+。

• Linux,或 Windows 上的 WSL2——bubblewrap 仅支持 Linux,而 Windows 上没有平价的替代方案,所以服务器必须在那⾥运行,即使 Claude Code 不需要在 WSL 里跑。

安装

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

cp .env.example .env                  # then set DELEGATE_WORKSPACE_ROOTS
cp models.toml.example models.toml    # then set your endpoint

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

.env 和 models.toml 都是刻意放进 gitignore 的:它们记录的是某个主机,而主机名和 IP 地址一样,能精确地把机器说出来。

在 Windows 上,服务器位于 WSL2

wsl --install -d Ubuntu-24.04

然后在 Ubuntu 中——请先验证,不要靠猜测,因为其中两条会悄无声息地失败:

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

在 x86-64 上,usr/lib64 的符号链接不是可选项。没有它,任何动态链接的可执行程序都跑不起来,而报错会指着可执行程序,而不是缺失的加载器。

注册到 Claude Code

原生 Linux:

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

Windows,服务器在 WSL2:

{ "mcpServers": { "delegate-local": {
    "command": "wsl.exe",
    "args": ["-d", "Ubuntu-24.04", "-e", "claude-delegate-local-mcp"],
    "timeout": 900000
} } }

timeout 的单位是毫秒。默认的墙钟时长给得很宽松,但一个特别长的委托可能会触碰到单独 30 分钟的 stdio空闲超时——服务器每运行一轮都会发出进度通知,防止被自动触发。详见 docs/TROUBLESHOOTING.md。

文档

所有配置默认值都只写在 docs/CONFIGURATION.md 中，而该文件是从定义它的代码生成的。如果你在别处看到同样的默认值反复出现，那是 bug——CLAUDE.md 解释了整套机制。

来源与许可

MIT。这是一个延续工作，而不是独立重新实现：相当一部分代码移植自 fegone/claude-code-delegate-local 及其 mixicz fork，两者均以 MIT 许可证发布。服务端上下文预取的思路来自 fjgbue/claude-delegator-deepseek-mcp。NOTICE 按特性逐条记录了各自来源来源。