ollama-mcp

将基于 Anthropic 的 Claude Code 会话中的任务委派给 基于 Ollama 的 Claude Code 会话——且两者永不共享环境变量。

ollama launch claude --model <model> 通过将 ANTHROPIC_* 变量导出到你的 shell 中工作。这就是它通常需要单独终端的原因：变量是进程范围内的，因此一个 shell 要么是“Anthropic”要么是“Ollama”，永远不能同时是两者。

此 MCP 服务器将每个委派会话作为子进程生成，并带有显式构建的环境。你的 Opus 会话保留自己的凭据和模型设置；委派者获得 Ollama 的。它们在同一终端中并行运行。

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: ollama-mcp ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=127.0.0.1:11434
                                       ANTHROPIC_AUTH_TOKEN=ollama
                                       → qwen3.5:397b-cloud

目录

• 工作原理

• 前提条件

• 安装

• 配置

• 委派模式

• 工具参考

• 操作指南

• 任务产物

• 故障排除

• 平台支持

• 安全模型

• 开发

Related MCP server: codex-as-mcp

工作原理

Ollama 的服务器暴露了一个兼容 Anthropic 的 POST /v1/messages 端点，因此 Claude Code 可以在指向正确的基础 URL 后未经修改地与它通信。每个委派任务作为 claude -p 在其自己的进程中运行，并带有：

ANTHROPIC_BASE_URL=http://127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>

所有三个模型槽位指向同一个 Ollama 模型，以便别名（opus、sonnet、haiku）以及在委派者内部生成的任何子代理都解析到该模型，而不是静默回退到 Anthropic 的默认值。

子环境是从一个小的、按平台划分的允许列表中构建的。任何匹配 ANTHROPIC_*、CLAUDE_*、AWS_*、GOOGLE_*、AZURE_*、OPENAI_*、BEDROCK_*、VERTEX_* 的内容都会在应用 Ollama 值之前被丢弃，因此你 shell 中残留的 ANTHROPIC_API_KEY 无法泄露到（或计费给）委派运行。

委派者还以 --strict-mcp-config 启动，并且没有 MCP 配置，这可以保持其快速启动，并阻止它们递归调用此服务器。

前提条件

在安装前验证各个组件：

node --version                              # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version  # {"version":"..."}
ollama list                                 # at least one model

云端模型 vs 本地模型。 标记为 :cloud 的模型在 Ollama 的基础设施上运行，需要 ollama signin；它们比大多数笔记本电脑内存所能容纳的模型强大得多，这使得它们成为委派的实际选择。本地模型同样有效，且永远不会离开你的机器。

安装

从 npm 安装（推荐）

无需克隆或构建——npx 按需获取：

claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcp

或者全局安装，这也会将设置 CLI 放入你的 PATH：

npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcp

从源码安装

git clone https://github.com/histonedev/claude-ollama-delegate-mcp.git
cd claude-ollama-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add ollama --scope user -- node "$(pwd)/dist/index.js"

以 node dist/cli.js … 运行设置 CLI，或运行 npm link 将 ollama-mcp-config 放入你的 PATH。

作用域

--scope user 使其在每个项目中可用；--scope project 将其写入当前仓库的 .mcp.json 并与协作者共享；--scope local 将其保留在此机器和此项目中。

确认

claude mcp list        # ollama: ... - ✔ Connected

然后重新启动你的 Claude Code 会话——工具列表在启动时读取。

配置

设置从四个层级解析，后者的优先级更高：

1. 内置默认值

2. 用户配置——~/.ollama-mcp/config.json（使用 $OLLAMA_MCP_CONFIG 覆盖路径）

3. 项目配置——服务器工作目录中的 ./ollama-mcp.config.json

4. 环境变量

{
  "delegationMode": "ondemand",
  "allowedModels": ["qwen3.5:397b-cloud", "gemma4:31b-cloud"],
  "defaultModel": "qwen3.5:397b-cloud",
  "defaultPermissionMode": "auto",
  "baseUrl": "http://127.0.0.1:11434",
  "claudeBin": "claude",
  "stateDir": "~/.ollama-mcp/jobs",
  "jobTimeoutMs": 1800000,
  "maxInlineChars": 60000
}

更改设置

设置从终端更改，绝不能由模型更改：

ollama-mcp-config                              # show current settings + active layers
ollama-mcp-config --mode auto                  # off | ondemand | auto
ollama-mcp-config --allow qwen3.5:397b-cloud   # or: --allow all
ollama-mcp-config --default-model qwen3.5:397b-cloud
ollama-mcp-config --permission-mode acceptEdits
ollama-mcp-config --scope project              # write ./ollama-mcp.config.json

然后重新启动你的 Claude Code 会话，以便服务器重新读取其配置。

这里故意没有 MCP 工具。 参见安全模型。

允许的模型

allowedModels: []（默认值）允许服务器提供的任何模型。如果列表非空：

• delegate_start 会拒绝列表之外的模型，并指出允许的集合，而不是静默替换

• ollama_models 会将排除的模型标记为 BLOCKED by allowedModels

• 允许的列表嵌入在 delegate_start 工具描述中，因此编排器无需额外调用即可知道可用选项

• CLI 拒绝会将 defaultModel 置于新列表之外的更改

委派模式

这控制编排器有多积极地寻求委派，通过重写模型实际读取的工具描述。更改它需要重新启动会话，这是有意设计的。

在 auto 模式下，描述告诉编排器将那些自包含、易于验证且消耗大量上下文的工作委派出去——批量文件摘要、初步搜索、机械性重构、样板代码和测试脚手架、日志或差异分类——而将架构决策、安全敏感变更、模糊需求和最终审查留给自己。它还被告知要验证委派的结果，原因见操作指南。

工具参考

delegate_start

delegate_followup 接受 job_id 或 session_id，加上相同的 prompt/prompt_file 对以及可选的 permission_mode、max_turns、wait_seconds。

操作指南

默认异步

delegate_start 在毫秒级返回 job_id；委派者在后台继续运行。这可以防止长时间任务阻塞你的会话或触发 MCP 客户端超时。

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

在上述任何调用中传递 wait_seconds 以阻塞等待——适用于短任务，此时轮询的往返开销不值得。

双向对话

每个任务都有一个 session_id。将其 job_id 传递给 delegate_followup 会恢复完整历史的会话；session_id 在多次轮次中保持稳定，而每次轮次都会获得一个新的 job_id。

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

当委派者已经加载了相关上下文时，跟进比重新开始要便宜得多。

长提示

每个提示参数都有一个对应的 prompt_file 变体。在内部，提示总是被写入磁盘，并通过 stdin 传递给 CLI——绝不会作为 argv 条目传入，也不会通过 shell 传递。反引号、$(...)、引号、换行符和通配符字符会原样传递，且没有 argv 长度限制。

delegate_start({ prompt_file: "/tmp/refactor-brief.md" })

权限

委托默认使用 defaultPermissionMode（auto）。缩小特定调用的范围：

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

信任委托的输出

每个完成的结果都会报告其工具调用次数。较弱的模型有时会自信地给出答案而不实际运行任何操作——在开发过程中，一个模型曾声称某个环境变量未设置，但从未调用过 Bash；在被推动后，它运行了命令并报告了正确的值。

带有 tool calls: 0 的结果因此被标记为未验证：

tool calls: 0   <- answered without using any tools; treat factual claims as unverified

delegate_status 显示实际的跟踪信息。纯粹的对话式后续交互合法地为零次调用——该标志意味着“没有东西支持这个结果”，而不是“出了什么问题”。

取消

delegate_cancel({ job_id: "A" })

杀死委托及其启动的所有进程，因此正在执行长时间构建的委托不会让构建继续运行。

作业工件

每个作业写入 ~/.ollama-mcp/jobs/<job_id>/：

超过 maxInlineChars 的结果会在工具响应中被截断，完整文本可从 result.txt 读取。不会自动修剪任何内容——你可以随时删除该目录。

故障排除

Cannot reach Ollama at http://127.0.0.1:11434 Ollama 未运行。启动 ollama serve 或打开桌面应用程序。如果它监听在其他地址，请设置 OLLAMA_MCP_BASE_URL。

No models available from Ollama 运行 ollama pull qwen3.5:397b-cloud，并针对 :cloud 模型运行 ollama signin。

<model> was retired at …（HTTP 410） Ollama 已移除该云端模型。ollama list 仍会显示已淘汰模型的本地缓存清单——请检查实际可用的模型并更新 defaultModel。

Model "x" is not in the allowed list 按预期工作。运行 ollama-mcp-config --allow <models>，然后重启。

工具在 Claude Code 中不显示 工具列表在会话启动时读取。重启，或检查 claude mcp list。

委托立即失败并显示启动错误 未找到 CLI。将 OLLAMA_MCP_CLAUDE_BIN 设置为 claude 的绝对路径。

一切都很慢 云端模型每次交互都需要一次往返，而 Claude Code 在每个请求中都会发送一个大型系统提示（约 25k 令牌）。使用 max_turns 限制代理循环，使用 allowed_tools 阻止委托探索超出必要范围。

平台支持

平台差异在 src/platform.ts 中隔离：

二进制解析。 在 POSIX 上，spawn 会搜索 PATH。在 Windows 上，原生安装提供 claude.exe，而 npm 安装提供 claude.cmd，CreateProcess 无法直接执行后者——因此服务器会遍历 PATH × PATHEXT，优先选择 .exe，并退回通过 cmd.exe 路由 .cmd 包装器。

参数转义。 这种回退方案应用了两层：MSVCRT argv 引用，然后对 cmd 自身的元字符（& | < > ^ " ( ) % !）进行脱字符转义。跳过第二层是经典的 .cmd 命令注入漏洞。提示永远不会经过此路径——它们通过 stdin 传输。一个限制是：多行的 append_system_prompt 不能跨越 cmd.exe 命令行，因此服务器会抛出一个清晰的错误，指向 OLLAMA_MCP_CLAUDE_BIN，而不是静默地破坏它。

环境允许列表。 Windows 保留的环境变量集比 POSIX 大得多。SystemRoot 和 windir 不是可选的——移除它们会导致 Winsock 初始化失败，因此子进程即使连接到 localhost 也无法打开套接字。名称匹配时不区分大小写，但复制时使用父进程的原始拼写。

取消。 POSIX 子进程以 detached 方式生成，作为进程组领导者，并通过 process.kill(-pid) 取消；Windows 使用 taskkill /T /F。无论哪种方式，委托自身的子进程都会随之终止。服务器在关闭时也会杀死正在运行的委托。

安全模型

凭据隔离是核心要点。 子环境从头构建，而不是继承，并且在应用 Ollama 值之前会剥离提供者变量。这一点在 test/env-unit.mjs 中有所涵盖，而 test/e2e.mjs 会在父进程中注入一个假的 ANTHROPIC_API_KEY，并断言它永远不会到达委托。

委托策略不可由模型写入。 没有 MCP 工具可以更改 delegationMode 或 allowedModels。早期版本中曾有一个，那是一个错误：一个发现 ondemand 不方便的模型可以在一次调用中将其切换到 auto，然后自由委托。现在设置仅在启动时加载一次，运行时永远不被修改，并且工具描述中说明策略不是模型可以更改的。

这是一个护栏，不是安全边界。 具有 shell 访问权限的代理仍然可以编辑配置文件。移除该工具的意义在于，这样的更改将是一个可见的文件编辑，并且仅在下次重启时生效，而不是在任务中间进行一次静默的单一工具调用。要使其无懈可击，请在 MCP 注册时通过 --env 固定这些值，这会覆盖配置文件：

claude mcp add ollama --scope user \
  --env OLLAMA_MCP_DELEGATION_MODE=ondemand \
  --env OLLAMA_MCP_ALLOWED_MODELS=qwen3.5:397b-cloud \
  -- node /path/to/claude-ollama-delegate-mcp/dist/index.js

委托继承你的文件系统。 它们以你的用户身份在你指定的 cwd 中运行，并带有 defaultPermissionMode。像对待任何 Claude Code 会话一样对待委托会话——在将工作交给你不那么信任的模型时，使用 disallowed_tools 或只读权限模式。

开发

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

测试

node test/env-unit.mjs       # env isolation: no secret leaks, platform vars present
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination
node test/e2e.mjs            # full MCP round trip           (needs Ollama running)
node test/async.mjs          # async polling, prompt_file, cancel  (needs Ollama)
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test 运行三个不需要网络的测试。

发布版本

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

该包是 claude-ollama-delegate-mcp，仅发布 dist/、README.md 和 LICENSE。publishConfig.access 为 public，prepare 在打包前运行 tsc，因此永远不会发布过时的 dist/。在发布前使用 npm pack --dry-run 预览 tarball。

布局

许可证

MIT——参见 LICENSE。