内容
# ollama-mcp-host
## 说明
在本地运行多个MCP服务器，并使用本地Ollama模型（gemma或其他支持工具的模型）。
无需云服务，无需LLM API密钥 — 所有操作都在您的机器上或私有网络内运行。适用于隔离/本地环境。
[](https://www.npmjs.com/package/ollama-mcp-host)
[](./LICENSE)
## 这是什么？（1分钟解释）
本地AI模型（如Google的`gemma`）很智能，但它无法查找信息或访问文件。为了使其有用，您需要为其提供**工具** — 而AI工具的开放标准是**MCP（模型上下文协议）**。
问题在于：**Ollama和MCP服务器不通用。** Ollama不知道如何调用MCP工具，而MCP服务器不知道如何与Ollama通信。您需要在它们之间有一个转换器。
**`ollama-mcp-host`就是这个转换器。** 注册一个或多个MCP服务器，单个Ollama模型将自动选择合适的工具，调用它，并根据实际结果提供答案。
## 要求
| 需要 | 目的 | 设置在 |
|------|---------|-----------|
| **Node.js 20+** | 运行此主机和MCP服务器 | 步骤 1 |
| **Ollama + 支持工具的模型** | 实际AI | 步骤 2 |
| **一个或多个MCP服务器** | 您提供给模型的工具 | 步骤 3 |
## 快速开始
### 步骤 1. 检查 Node.js
```bash
node --version # 需要 v20+；如果没有，请从nodejs.org安装LTS版本
```
### 步骤 2. 安装 Ollama 并拉取模型
[Ollama](https://ollama.com) 在本地免费运行AI模型。
```bash
ollama pull gemma4:e4b # 轻量级，支持工具
ollama serve # 保持运行（默认：http://localhost:11434）
ollama show gemma4:e4b # ★ "Capabilities" 必须列出 `tools`，否则工具调用不会生效
```
### 步骤 3. 获取您的MCP服务器（示例：两个韩国工具）
```bash
# 法律搜索
git clone https://github.com/chrisryugj/korean-law-mcp.git
cd korean-law-mcp && npm install && npm run build && pwd && cd ..
# → 构建 korean-law-mcp/build/index.js （注意完整路径）
# 文档
git clone https://github.com/chrisryugj/kordoc.git
cd kordoc && npm install && npm run build && pwd && cd ..
# → 构建 kordoc/dist/mcp.js （注意完整路径）
```
### 步骤 4. 安装此主机
```bash
npm install -g ollama-mcp-host
# 或运行而无需安装： npx ollama-mcp-host --help
```
### 步骤 5. 编写配置文件 — `mcp.config.json`
在工作文件夹中创建 `mcp.config.json`：
```jsonc
{
"model": "gemma4:e4b",
"ollamaHost": "http://localhost:11434",
"system": "您是韩国法律和官方文档的助手。当存在相关工具时，请始终调用它来获取真实数据，然后再回答。永远不要编造法规或案例编号。",
"maxToolRounds": 8,
"servers": [
{
"name": "law",
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/korean-law-mcp/build/index.js"],
"env": { "LAW_OC": "${LAW_OC}" } // ${ENV} 在运行时替换
},
{
"name": "kordoc",
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/kordoc/dist/mcp.js"] // kordoc 不需要 API 密钥
}
]
}
```
- 您只需要填写两个 `args` 路径（来自步骤 3）。
- `"${VAR}"` 在运行时替换为环境变量，因此 **您永远不会在文件中硬编码密钥**。干净的、无注释的版本位于 [`mcp.config.example.json`](./mcp.config.example.json)。
- `korean-law-mcp` 需要来自 [open.law.go.kr](https://open.law.go.kr) 的免费 API 密钥 (`LAW_OC`)；`kordoc` 不需要。
### 步骤 6. 运行
```bash
LAW_OC=your-key ollama-mcp-host -c mcp.config.json
# Windows: set LAW_OC=your-key （然后运行命令）
```
您应该看到：
```
config: mcp.config.json · model: gemma4:e4b
连接MCP服务器...
connected: law, kordoc · 19 tools
输入问题。/tools 列出工具 · /exit 退出
>
```
### 步骤 7. 使用它
```
> 哪个机构负责监督《道路交通法》？
↳ [law] search_law({"query":"도로교통법"}) ← 模型调用工具
✓ search_law: 3 results … ← 工具返回真实数据
答案： 《道路交通法》由韩国国民警察局监督 …
> 生成一个HWPX报告，内容如下。保存到 /Users/me/result.hwpx
↳ [kordoc] generate_document({...})
✓ generate_document: HWPX created …
答案： 报告已创建在 /Users/me/result.hwpx.
```
聊天命令： `/tools` （列出可用工具）， `/exit` （退出）。
## 在隔离网络中运行
隔离网络通常会阻止所有这些，因此 `ollama pull`、`npm install` 和 `git clone` просто 不起作用：
| 被阻止的网站 | 它通常提供什么 |
|------|------|
| `ollama.com` | Ollama 本身 + AI 模型 |
| `nodejs.org` | Node.js 引擎 |
| `github.com` | 源代码 |
| `registry.npmjs.org` | npm 包 |
计划是： **在有互联网的地方下载 → 携带到网络中 → 在内部提供服务**。混合使用以下两种策略。
### 策略 A — 一个 Ollama 服务器，其他人远程连接（推荐）
模型文件有几个 GB，因此在每台电脑上安装它们是浪费的。 将 Ollama + 模型放在 **一台有能力的机器上**，让其他人通过局域网连接到它。 此主机通过 `ollamaHost` 设置支持它。
**在服务器上（安装模型的机器）** - 让 Ollama 监听所有接口：
- **Linux (systemd):** 添加到 `[Service]` 部分的 `/etc/systemd/system/ollama.service`，然后 `sudo systemctl daemon-reload && sudo systemctl restart ollama`
```ini
Environment="OLLAMA_HOST=0.0.0.0:11434"
```
- **Windows:** 添加系统环境变量 `OLLAMA_HOST = 0.0.0.0:11434`，然后注销/登录。
- **macOS:** `launchctl setenv OLLAMA_HOST "0.0.0.0:11434"`，然后重启 Ollama。
然后 **允许入站端口 `11434`** 在防火墙中。 Ollama **没有内置身份验证**，因此仅在受信任的局域网上公开它 - 绝不公开给公共互联网。为了加强隔离，使用SSH隧道或私有VPN。
**在其他电脑上（客户端）** - 无需模型，只需将 `ollamaHost` 指向服务器：
```jsonc
{
"model": "gemma4:e4b",
"ollamaHost": "http://192.168.0.10:11434", // ← 服务器的 IP
...
}
```
从客户端验证连接：
```bash
curl http://192.168.0.10:11434/api/tags # JSON 模型列表表示已连接
```
## 故障排除
| 症状 | 可能的原因 | 解决方法 |
|------|------|------|
| 模型用文字回答但从不调用工具 | thinking 模式，或模型缺乏工具支持 | 此主机自动禁用思考。仍然失败？检查 `ollama show <model>` 中的 `tools` |
| `Ollama 连接失败` | Ollama 未运行 | 启动 `ollama serve` （或检查 `ollamaHost`） |
| `MCP 服务器 '...' 连接失败` | 错误路径，或服务器未构建 | 验证 `args` 路径并检查是否运行了 `npm run build` |
| 工具运行但返回错误 (`✗`) | 缺少/输入错误的密钥，或防火墙 | 检查 `LAW_OC`；在离线网络上，检查 `law.go.kr` 访问 |
## Docker
在容器中运行所有内容 - 主机 + 两个MCP服务器在一个镜像中，Ollama在另一个镜像中。它们通过 `docker-compose.yml` 连接在一起。
```bash
# 1. 构建并启动（应用程序 + Ollama）
docker compose up -d --build
# 2. 将模型拉取到 Ollama 容器中（一次性）
docker compose exec ollama ollama pull gemma4:e4b
# 3a. 交互式聊天
LAW_OC=your-key docker compose run --rm app
# 3b. 或一次性问题
LAW_OC=your-key docker compose run --rm app --once "哪个机构负责监督《道路交通法》？"
```
## HTTP API
与其使用交互式CLI，不暴露HTTP端点，让其他应用程序提问：
```bash
ollama-mcp-host -c mcp.config.json --serve --port 8080
# 在 Docker 中： docker compose run --rm -p 8080:8080 app --serve --port 8080
```
| 方法 | 路径 | 正文 | 返回 |
|--------|------|------|---------|
| `GET` | `/health` | — | `{status, model, servers, tools}` |
| `GET` | `/tools` | — | 可用的工具列表 |
| `POST` | `/chat` | `{"message": "..."}` | `{answer, toolCalls, messages}` |
| `POST` | `/chat` | `{"messages": [...]}` | 相同 - 用于多轮（发送运行历史） |
```bash
curl -X POST http://localhost:8080/chat \
-H "Content-Type: application/json" \
-d '{"message":"哪个机构负责监督《道路交通法》？"}'
# → {"answer":"...","toolCalls":[{"server":"law","tool":"search_law",...}],"messages":[...]}
```
`toolCalls` 显示了为该答案调用了哪些MCP工具。 服务器是无状态的 - 对于对话，请每次发送完整的 `messages` 数组。
## 用作库
```ts
import { McpHost, loadConfig } from "ollama-mcp-host";
const host = new McpHost(loadConfig("mcp.config.json"));
await host.connect();
const messages = [{ role: "user", content: "显示个人信息保护法第15条" }];
const updated = await host.chat(messages, {
onToolCalls: (i) => console.log(`tool calls: ${i.server}.${i.tool}`),
});
console.log(updated.at(-1)?.content);
await host.close();
```
从源码构建：
```bash
git clone https://github.com/chrisryugj/ollama-mcp-host.git
cd ollama-mcp-host && npm install && npm run build && npm test
```
### CLI 选项
| 选项 | 描述 |
|------|------|
| `-c, --config <path>` | 配置文件（默认为 `mcp.config.json`） |
| `-m, --model <tag>` | 为此运行重写模型 |
| `--once "<question>"` | 回答单个问题并退出（用于脚本） |
| `--serve` | 运行为HTTP API服务器（`POST /chat`, `GET /health`, `/tools`） |
| `--port <n>` | `--serve` 的端口（默认为 8080） |
| `-h, --help` | 帮助 |
### 配置说明
- `"${VAR}"` 在运行时从环境中替换 - 将密钥排除在文件之外。
- 如果两个服务器使用相同的工具名称，则自动命名为 `server__tool`。
- 对于已安装的MCP服务器，可以使用 `"command": "npx", "args": ["-y", "korean-law-mcp"]`（优先使用绝对路径）。
## 验证
`gemma4:e4b`（Ollama 0.30）+ `korean-law-mcp` 4.4.2 + `kordoc` 3.5.1，Node 26 / macOS - 两台服务器一起运行，并确认了实际的工具调用（法律搜索和HWPX生成）。
## 许可证
MIT
