mcp-ollama

MCP 服务器，封装本地 Ollama 模型，用于从按 API 计费的编排器中分流任务。

提供九个工具，将工作交给本地模型处理（文本生成、摘要、代码任务、机械转换、提交/PR/变更日志草拟）。编排器决定哪些任务路由到本地；此服务器负责执行路由。

• 传输方式： stdio

• 运行时： Node 18+

• 默认模型： hermes3:8b（可通过 OLLAMA_MODEL 覆盖）

• Ollama 主机： http://localhost:11434（可通过 OLLAMA_HOST 覆盖）

• 不包含模型权重、无云端调用、无遥测。 每个请求都保留在运行 Ollama 的主机上。

• 许可证： Apache-2.0

为什么使用它

按 Token 计费的编排器（如 Claude Code、Cursor、Anthropic API、Cline、Aider）会对每一次分类、每一个文档字符串、每一条提交信息收费。大部分工作并不需要前沿模型。如果路由到同一台机器上的 Ollama，同样的工作既免费又更快。mcp-ollama 就是这个路由接口。

编排模型决定路由到哪里。此服务器只是管道——它不会试图在任务分类上耍小聪明。选择正确的工具，传入文本，获取结果。

Related MCP server: ProjectBrain

安装

从源码安装

git clone https://github.com/true-alter/mcp-ollama.git
cd mcp-ollama
npm install
npm run build

你还需要一个正在运行的 Ollama 实例，并至少拉取了一个模型：

# Default — 8B, fast, good for classifications and short generations
ollama pull hermes3:8b

# Optional — code-specialised, heavier, better for local_code tasks
ollama pull qwen2.5-coder:32b

Docker

docker build -t mcp-ollama .
docker run -i --rm \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=hermes3:8b \
  mcp-ollama

提供的 Dockerfile 指向 host.docker.internal:11434，以便容器能够访问主机上的 Ollama。

运行 (stdio)

node dist/index.js

Stdio 服务器由 MCP 客户端（Claude Code、Cursor 等）启动——直接运行它仅用于调试。

配置 Claude Code

claude mcp add --transport stdio ollama -- node /absolute/path/to/mcp-ollama/dist/index.js

或者在 ~/.claude/settings.json 中配置：

{
  "mcpServers": {
    "ollama": {
      "transport": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-ollama/dist/index.js"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "hermes3:8b"
      }
    }
  }
}

工具

完整的工具架构通过 MCP 自省暴露——任何支持 MCP 的客户端都会自动枚举它们。

环境变量

任何工具调用都可以显式覆盖 model——环境变量默认值仅在未设置时生效。local_code 通常在每次调用时传入代码专用模型效果更好，而 local_summarize 和 local_draft 使用默认模型即可。

模型选择指南

如果不确定主机上有什么模型，请在会话开始时使用 local_models。

故障排除

调用工具时出现 Ollama error 404。 模型未拉取。运行 ollama pull <name> 或从客户端调用 local_pull。

fetch failed / 连接被拒绝。 Ollama 未运行，或者 OLLAMA_HOST 指向了错误的位置。使用 curl $OLLAMA_HOST/api/tags 进行验证。在容器内，localhost 指的是容器本身——在 macOS/Windows 上使用 host.docker.internal，在 Linux 上使用网桥 IP。

工具调用感觉缓慢。 首次调用冷模型会产生加载开销。在同一个 Ollama 进程内的后续调用会快得多。如果模型大于可用显存，Ollama 会回退到 CPU——观察 ollama ps 以确认。

输出为空或被截断。 每个工具的 max_tokens 默认值为 2048。对于长文本生成，请在工具调用中显式传入 max_tokens。

安全态势

mcp-ollama 除了配置的 OLLAMA_HOST 外，不会进行任何网络调用。它不发送遥测、分析数据或自动更新 ping。工具输入被原样转发到 Ollama 的 HTTP API，响应被中继回来；服务器本身在调用之间是无状态的。

如果你在 localhost（默认）上运行 Ollama，整个循环都保留在主机上。如果你将 OLLAMA_HOST 指向远程端点，请将该端点的安全态势视为权威——将提示词发送到第三方主机的拼写错误是很容易发生的。

要报告安全问题，请参阅 SECURITY.md。

贡献

欢迎提交错误报告和小补丁——请参阅 CONTRIBUTING.md。对于较大的设计变更：请先开启一个 issue，以便我们在你投入时间之前讨论范围。

ALTER 的一部分

mcp-ollama 由 ALTER 维护，作为 AI 经济身份基础设施的一部分。ALTER 身份 MCP 服务器托管在 mcp.truealter.com——请参阅 @truealter/sdk 获取 TypeScript 客户端。

许可证

Apache License 2.0。全文请参阅 LICENSE。版权所有 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049)。