奥拉玛-MCP-桥接器

Name: 奥拉玛-MCP-桥接器
Author: jonigl

作者：jonigl36 星标更新：2025-10-24

安装使用来源：spider==github.com

项目介绍

技术文档摘要

<img src="https://gips1.baidu.com/it/u=1485838760,2248491737&fm=3081&app=3081&f=PNG?w=512&h=512" width="256" /> 在Ollama API前提供一个API层，无缝地添加来自多个MCP服务器的工具，使每个Ollama请求都能透明地访问所有连接的工具。

Ollama MCP Bridge

功能

🚀 预加载服务器：所有MCP服务器在启动时都通过JSON配置文件连接
📝 JSON配置：配置多个服务器及其复杂的命令和环境
🔗 工具集成：自动处理工具调用并整合响应
🔄 多轮工具执行：自动循环多次工具调用直到完成
🛡️ 可配置工具限制：设置最大工具执行轮次以防止过多调用
🛠️ 所有工具可用：Ollama可以同时使用任何连接服务器中的任何工具
🔌 完整的API兼容性：/api/chat端点添加工具，而其他所有Ollama API端点透明代理
🔧 可配置Ollama：通过CLI指定自定义Ollama服务器URL（支持本地和云模型）
☁️ 云模型支持：支持Ollama云模型
🔄 版本检查：自动检查更新并提供升级说明
🌊 流式响应：支持向客户端增量流式传输响应
🤔 思考模式：代理Ollama和MCP工具之间的中间“思考”消息
⚡️ FastAPI后端：现代异步API，带有自动文档
🏗️ 模块化架构：干净地分离CLI、API和MCP管理模块
💻 Typer CLI：具有可配置选项的干净命令行界面
📊 结构化日志：使用loguru进行全面的日志记录
📦 PyPI包：可通过pip或uv从PyPI轻松安装
🗣️ 系统提示配置：允许设置助手行为的系统提示

需求

Python >= 3.10.15
运行中的Ollama服务器（本地或远程）
至少包含一个MCP服务器定义的MCP服务器配置文件（参见下文示例）

安装

你可以根据偏好以多种方式安装ollama-mcp-bridge：

快速开始

使用uvx即时安装：

uvx ollama-mcp-bridge

或，使用pip从PyPI安装

pip install --upgrade ollama-mcp-bridge

或，使用Docker Compose运行

docker-compose up

这会使用包含的docker-compose.yml文件：

使用此Dockerfile从源代码构建桥接
连接到主机机器上运行的Ollama（host.docker.internal:11434）
映射配置文件从./mcp-config.json（包括用于演示的模拟天气MCP服务器）
允许所有CORS来源（可通过CORS_ORIGINS环境变量配置）

或，从源代码安装

# 克隆仓库
git clone https://github.com/jonigl/ollama-mcp-bridge.git
cd ollama-mcp-bridge

# 使用uv安装依赖
uv sync

# 启动Ollama（如果尚未运行）
ollama serve

# 运行桥接（推荐）
ollama-mcp-bridge

如果你想以可编辑模式安装项目（用于开发）：

# 以可编辑模式安装项目
uv tool install --editable .
# 如下运行：
ollama-mcp-bridge

工作原理

启动：配置中定义的所有MCP服务器都被加载并连接
版本检查：启动时，桥接检查是否有新版本，并通知如果有可用更新
工具收集：从所有服务器收集工具并使其对Ollama可用
聊天完成请求（仅/api/chat端点）：当收到/api/chat端点上的聊天完成请求时：
- 请求连同所有可用工具列表一起转发给Ollama（本地或云端）
- 如果Ollama选择调用任何工具，这些工具调用将通过相应的MCP服务器执行
- 工具响应反馈给Ollama
- 过程在一个循环中重复，直到不再需要更多工具调用
- 整个过程中实时流式传输响应到客户端
- 最终响应（包含所有工具结果）返回给客户端
- 这是唯一集成MCP服务器工具的端点。
其他端点：除了/api/chat、/health和/version之外的所有端点都完全代理到底层Ollama服务器，不做修改。
日志：所有操作均使用loguru进行日志记录，用于调试和监控

配置

MCP服务器配置

在mcp-config.json创建你的服务器配置文件：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "./mock-weather-mcp-server",
        "run",
        "main.py"
      ],
      "env": {
        "MCP_LOG_LEVEL": "ERROR"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp"
      ]
    }
  }
}

[!警告] Docker命令限制：在Docker中运行时，MCP服务器应使用容器内可用的命令：

✅ npx用于基于Node.js的MCP服务器

✅ uvx用于基于Python的MCP服务器

✅ 容器内的直接可执行文件

❌ docker命令（除非配置了Docker-in-Docker）

❌ 主机机器上的本地文件路径

CORS配置

配置跨源资源共享（CORS），允许前端应用程序的请求：

# 允许所有来源（默认，不建议用于生产）
ollama-mcp-bridge

# 允许特定来源
CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge

# 允许多个来源及不同端口
CORS_ORIGINS="http://localhost:3000,http://localhost:8080,https://app.example.com" ollama-mcp-bridge

环境变量：

CORS_ORIGINS：允许的来源的逗号分隔列表（默认：*）
- *允许所有来源（日志中显示警告）
- 示例：CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge
MAX_TOOL_ROUNDS：最大工具执行轮次数（默认：不限）
- 可通过--max-tool-roundsCLI参数覆盖（CLI优先）
- 示例：MAX_TOOL_ROUNDS=5 ollama-mcp-bridge
OLLAMA_URL：Ollama服务器的URL（默认：http://localhost:11434）
- 可通过--ollama-urlCLI参数覆盖
- 对于Docker部署和配置管理很有用
- 示例：OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp- bridge
SYSTEM_PROMPT：可选系统提示，附加到所有转发的/api/chat请求
- 可通过SYSTEM_PROMPT环境变量或--system-promptCLI标志设置
- 如果提供，桥接将在/api/chat请求的messages数组开头添加一条系统消息（角色：system），除非请求已经以系统消息开头。
- 示例：SYSTEM_PROMPT="您是一个简洁的助手。" ollama-mcp-bridge

CORS日志：

桥接在启动时记录CORS配置
当使用*（所有来源）时显示警告
正确配置时显示允许的来源

[!警告] 使用CORS_ORIGINS="*"允许所有来源，不建议用于生产。始终指定确切的来源以确保安全。

[!注意] 提供了一个示例MCP服务器脚本在mock-weather-mcp-server/main.py。

用法

启动服务器

# 使用默认设置启动（配置：./mcp-config.json，主机：0.0.0.0，端口：8000）
ollama-mcp-bridge

# 使用自定义配置文件启动
ollama-mcp-bridge --config /path/to/custom-config.json

# 自定义主机和端口
ollama-mcp-bridge --host 0.0.0.0 --port 8080

# 自定义Ollama服务器URL（本地或云端）
ollama-mcp-bridge --ollama-url http://192.168.1.100:11434

# 限制工具执行轮次（防止过多调用）
ollama-mcp-bridge --max-tool-rounds 5

# 设置一个系统提示，附加到所有/api/chat请求
ollama-mcp-bridge --system-prompt "您是一个简洁的助手。"

# 组合选项
ollama-mcp-bridge --config custom.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434 --max-tool-rounds 10

# 检查版本和可用更新
ollama-mcp-bridge --version

[!提示] 如果使用uvx运行桥接，请将命令指定为uvx ollama-mcp-bridge而不是ollama-mcp-bridge。

[!注意] 该桥接支持流式响应和思考模式。你会收到生成时的增量响应，工具调用和中间思考消息会在Ollama和所有连接的MCP工具之间自动代理。

CLI选项

--config：MCP配置文件路径（默认：mcp-config.json）
--host：绑定服务器的主机（默认：0.0.0.0）
--port：绑定服务器的端口（默认：8000）
--ollama-url：Ollama服务器URL（默认：http://localhost:11434）
--max-tool-rounds：最大工具执行轮次（默认：不限）
--reload：启用开发期间的自动重载
--version：显示版本信息，检查更新并退出
--system-prompt：可选系统提示，附加到/api/chat请求（默认：无）

API用法

API可在http://localhost:8000访问。

Swagger UI文档：http://localhost:8000/docs
Ollama兼容端点：
- POST /api/chat — 聊天端点（与Ollama API相同，但带有MCP工具支持）
  - 这是唯一集成MCP服务器工具的端点。 所有工具调用由桥接自动处理并透明合并响应。
- 所有其他端点（除了/api/chat、/health和/version）都完全代理到底层Ollama服务器，不做修改。你可以像平常一样使用现有的Ollama客户端和库。
桥接特定端点：
- GET /health — 健康检查端点（不代理）
- GET /version — 版本信息和更新检查

[!重要] /api/chat是唯一集成MCP工具的端点。所有其他端点都透明代理到Ollama。/health和/version是桥接特有的。

该桥接作为Ollama API的即插即用代理，但所有连接服务器中的所有MCP工具都可用于每个/api/chat请求。桥接自动处理多次工具执行直到完成，并实时流式传输响应。你可以使用现有的Ollama客户端和库，无论是本地还是云端Ollama模型，只需指向这个桥接而不是你的Ollama服务器。

示例：聊天

curl -N -X POST http://localhost:8000/api/chat \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:0.6b",
    "messages": [
      {
        "role": "system",
        "content": "您是一个天气助手。"
      },
      {
        "role": "user",
        "content": "今天巴黎的天气如何？"
      }
    ],
    "think": true,
    "stream": true,
    "options": {
      "temperature": 0.7,
      "top_p": 0.9
    }
  }'

[!提示] 使用/docs进行交互式API探索和测试。

开发

关键依赖项

FastAPI：用于API的现代Web框架
Typer：用于命令行界面的CLI框架
loguru：在整个应用中进行结构化日志记录
ollama：用于Ollama通信的Python客户端
mcp：模型上下文协议客户端库
pytest：用于API验证的测试框架

测试

该项目有两种类型的测试：

单元测试（兼容GitHub Actions）

# 安装测试依赖
uv sync --extra test

# 运行单元测试（无需服务器）
uv run pytest tests/test_unit.py -v

这些测试检查：

配置文件加载
模块导入和初始化
项目结构
工具定义格式

集成测试（需要运行的服务）

# 首先，在一个终端中启动服务器
ollama-mcp-bridge

# 然后，在另一个终端中运行集成测试
uv run pytest tests/test_api.py -v