MCP-Bridge

MCP-Bridge 充当 OpenAI API 与 MCP（MCP）工具之间的桥梁，使开发者能够通过 OpenAI API 接口利用 MCP 工具。

[!NOTE]

我们正在寻找新的维护者来协助该项目。如果您感兴趣，请在 Discord 上联系我们或提交一个问题。

此外，从 v0.6.31 开始，Open WebUI 原生支持 MCP（模型上下文协议），因此现在可以认为 MCP-Bridge 已经被弃用。

概述

MCP-Bridge 旨在促进 MCP 工具与 OpenAI API 的集成。它提供了一组端点，可用于以与 OpenAI API 兼容的方式与 MCP 工具进行交互。这使得您可以在任何客户端上使用任何 MCP 工具，而无需显式支持 MCP。例如，请参阅此示例，展示如何将 Open Web UI 与官方 MCP 获取工具一起使用。

当前功能

已实现的功能：

• 使用 MCP 的非流式聊天完成

• 使用 MCP 的流式聊天完成

• 不使用 MCP 的非流式完成

• MCP 工具

• MCP 抽样

• 用于外部客户端的 SSE 桥接

计划中的功能：

• 流式完成尚未实现

• 计划支持 MCP 资源

安装

推荐使用 Docker 安装 MCP-Bridge。请参阅示例 compose.yml 文件，了解如何设置 Docker。

请注意，这需要一个支持工具调用的推理引擎。我已经成功地使用 vLLM 进行了测试，不过 Ollama 也应该兼容。

Docker 安装

1. 克隆仓库

2. 编辑 compose.yml 文件

您需要在 compose.yml 文件中添加对 config.json 文件的引用。您可以选择以下任一方式：

• 将 config.json 文件与 compose.yml 文件放在同一目录下，并使用卷挂载（您需要手动添加卷）
• 在环境变量中添加一个 HTTP URL，用于从该 URL 下载 config.json 文件
• 直接将 config.json 作为环境变量添加

以下是每种选项的示例：

environment:
  - MCP_BRIDGE__CONFIG__FILE=config.json # 挂载配置文件才能正常工作
  - MCP_BRIDGE__CONFIG__HTTP_URL=http://10.88.100.170:8888/config.json
  - MCP_BRIDGE__CONFIG__JSON={"inference_server":{"base_url":"http://example.com/v1","api_key":"None"},"mcp_servers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}

使用配置文件的挂载点如下所示：

    volumes:
      - ./config.json:/mcp_bridge/config.json

3. 运行服务

docker-compose up --build -d

手动安装（不使用 Docker）

如果您想在不使用 Docker 的情况下运行应用程序，您需要安装依赖项并手动运行应用程序。

1. 克隆仓库

2. 设置依赖项：

uv sync

3. 在根目录下创建 config.json 文件

以下是一个示例 config.json 文件：

{
   "inference_server": {
      "base_url": "http://example.com/v1",
      "api_key": "None"
   },
   "mcp_servers": {
      "fetch": {
        "command": "uvx",
        "args": ["mcp-server-fetch"]
      }
   }
}

4. 运行应用程序：

uv run mcp_bridge/main.py

使用方法

应用程序运行后，您可以使用 OpenAI API 与其交互。

请访问 http://yourserver:8000/docs 查看文档。这里有一个列出服务器上所有可用 MCP 工具的端点，您可以使用它来测试应用程序配置。

REST API 端点

MCP-Bridge 暴露了许多 REST API 端点，用于与所有原生 MCP 基元进行交互。这让您可以将处理 MCP 服务器的复杂性外包给 MCP-Bridge，而不会牺牲功能。请参阅 OpenAPI 文档，了解如何使用这些功能的示例。

SSE 桥接

MCP-Bridge 还为外部客户端提供了 SSE 桥接。这使得具有显式 MCP 支持的外部聊天应用可以将 MCP-Bridge 用作 MCP 服务器。将您的客户端指向 SSE 端点（http://yourserver:8000/mcp-server/sse），您应该能够看到服务器上所有可用的 MCP 工具。

这也使得测试您的配置是否正确变得非常容易。您可以使用 wong2/mcp-cli 来测试您的配置。npx @wong2/mcp-cli --sse http://localhost:8000/mcp-server/sse

如果您想在 claude desktop 或其他仅支持 STDIO 的 MCP 客户端中使用这些工具，可以使用诸如 lightconetech/mcp-gateway 之类的工具来实现。

配置

要添加新的 MCP 服务器，请编辑 config.json 文件。

API 密钥认证

MCP-Bridge 支持 API 密钥认证，以保护您的服务器。要启用此功能，请在您的 config.json 文件中添加类似以下内容：

{
    "security": {
      "auth": {
        "enabled": true,
        "api_keys": [
          {
            "key": "your-secure-api-key-here"
          }
        ]
      }
    }
}

在向 MCP-Bridge 服务器发送请求时，请在 Authorization 头部以 Bearer 令牌的形式包含 API 密钥：

Authorization: Bearer your-secure-api-key-here

如果配置中 api_key 字段为空或不存在，则将跳过身份验证，从而保持向后兼容性。

完整配置示例

一个显式设置了大多数选项的 config.json 文件示例：

{
    "inference_server": {
        "base_url": "http://localhost:8000/v1",
        "api_key": "None"
    },
    "sampling": {
        "timeout": 10,
        "models": [
            {
                "model": "gpt-4o",
                "intelligence": 0.8,
                "cost": 0.9,
                "speed": 0.3
            },
            {
                "model": "gpt-4o-mini",
                "intelligence": 0.4,
                "cost": 0.1,
                "speed": 0.7
            }
        ]
    },
    "mcp_servers": {
        "fetch": {
            "command": "uvx",
            "args": [
                "mcp-server-fetch"
            ]
        }
    },
    "security": {
      "auth": {
        "enabled": true,
        "api_keys": [
          {
            "key": "your-secure-api-key-here"
          }
        ]
      }
    },
    "network": {
        "host": "0.0.0.0",
        "port": 9090
    },
    "logging": {
        "log_level": "DEBUG"
    }
}

部分	描述
inference_server	推理服务器配置
mcp_servers	MCP 服务器配置
network	uvicorn 网络配置
logging	日志记录配置
api_key	用于服务器身份验证的 API 密钥

支持

如果您遇到任何问题，请提交一个问题或加入 Discord 社区。

此外，您还可以在 这里 查阅相关文档。

工作原理

该应用程序位于 OpenAI API 和推理引擎之间。传入的请求会被修改，以包含 MCP 服务器上所有可用工具的定义。随后，请求会被转发到推理引擎，推理引擎会利用这些工具定义来生成工具调用。MCP 桥接器则负责管理这些工具调用。之后，请求会被再次修改，加入工具调用的结果，并返回给推理引擎，以便大模型生成响应。最后，响应会被返回给 OpenAI API。

sequenceDiagram
    participant OpenWebUI as Open Web UI
    participant MCPProxy as MCP Proxy
    participant MCPserver as MCP Server
    participant InferenceEngine as Inference Engine

    OpenWebUI ->> MCPProxy: 请求
    MCPProxy ->> MCPserver: 列出工具
    MCPserver ->> MCPProxy: 工具列表
    MCPProxy ->> InferenceEngine: 转发请求
    InferenceEngine ->> MCPProxy: 响应
    MCPProxy ->> MCPserver: 调用工具
    MCPserver ->> MCPProxy: 工具响应
    MCPProxy ->> InferenceEngine: 大模型使用工具响应
    InferenceEngine ->> MCPProxy: 响应
    MCPProxy ->> OpenWebUI: 返回响应

贡献指南

欢迎为 MCP-Bridge 做出贡献！请按照以下步骤进行：

1. 克隆仓库并创建分支。
2. 创建一个新的分支用于您的功能或错误修复。
3. 进行更改并提交。
4. 将更改推送到您的分支。
5. 向主仓库提交拉取请求。

许可证

MCP-Bridge 采用 MIT 许可证授权。更多信息请参阅 LICENSE 文件。

MCP-Bridge 快速上手指南

MCP-Bridge 是一个桥接工具，允许开发者通过标准的 OpenAI API 接口调用 MCP (Model Context Protocol) 工具。它使得任何支持 OpenAI API 的客户端（如 Open WebUI、LangChain 等）都能无缝使用 MCP 生态中的工具，而无需客户端原生支持 MCP。

注意：Open WebUI v0.6.31+ 已原生支持 MCP，若仅在该场景下使用，可优先考虑原生方案。MCP-Bridge 目前处于软弃用状态，但仍适用于其他需要桥接的场景。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需安装 Docker 或 Python 环境)
• 推理引擎：需要一个支持 Tool Call (工具调用) 的后端，推荐使用 vLLM 或 Ollama。
• 运行方式二选一：
  • Docker (推荐)：需安装 Docker 和 Docker Compose。
  • 手动运行：需安装 Python 3.10+ 及 uv 包管理工具。

安装步骤

方式一：Docker 安装（推荐）

1. 克隆仓库

   git clone https://github.com/your-repo/MCP-Bridge.git
   cd MCP-Bridge
   

2. 配置 compose.yml 编辑 compose.yml 文件，你需要指定配置文件 config.json 的来源。有三种方式：

   • 挂载本地文件（推荐）：将 config.json 放在同级目录，并在 compose.yml 中添加 volume 映射。
   • HTTP URL：通过环境变量指向远程 JSON 文件。
   • 环境变量直接写入：直接将 JSON 内容放入环境变量。

   示例（挂载本地文件）： 确保目录下有 config.json (内容见下文“基本使用”部分)，并在 compose.yml 的 volumes 部分添加：

   volumes:
     - ./config.json:/mcp_bridge/config.json
   

   同时在 environment 中声明：

   environment:
     - MCP_BRIDGE__CONFIG__FILE=config.json
   

3. 启动服务

   docker-compose up --build -d
   

方式二：手动安装（无 Docker）

1. 克隆仓库

   git clone https://github.com/your-repo/MCP-Bridge.git
   cd MCP-Bridge
   

2. 安装依赖 使用 uv 同步环境：

   uv sync
   

3. 创建配置文件 在项目根目录创建 config.json (内容参考下文)。

4. 运行应用

   uv run mcp_bridge/main.py
   

基本使用

1. 配置 MCP 服务器

在项目根目录创建 config.json。以下示例配置了一个名为 fetch 的 MCP 工具（用于抓取网页），并连接本地的推理引擎。

config.json 示例：

{
   "inference_server": {
      "base_url": "http://localhost:11434/v1", 
      "api_key": "None"
   },
   "mcp_servers": {
      "fetch": {
        "command": "uvx",
        "args": ["mcp-server-fetch"]
      }
   },
   "network": {
       "host": "0.0.0.0",
       "port": 8000
   }
}

注：请将 base_url 修改为你实际运行的推理引擎地址（如 Ollama 默认是 http://localhost:11434/v1，vLLM 通常是 http://localhost:8000/v1）。

2. 验证与测试

服务启动后，可以通过浏览器访问 Swagger 文档查看可用接口和测试工具列表：

http://localhost:8000/docs

找到列出所有 MCP 工具的端点进行测试，确认配置生效。

3. 集成到客户端

配置完成后，MCP-Bridge 会暴露标准的 OpenAI API 接口。你只需将现有 AI 客户端的 API 地址指向 MCP-Bridge 即可。

• API Base URL: http://localhost:8000/v1
• API Key: (如果在 config 中未设置认证，可填任意值或留空)

使用示例 (Python OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed" 
)

response = client.chat.completions.create(
    model="your-model-name", # 替换为你的模型名称
    messages=[
        {"role": "user", "content": "请帮我获取 https://example.com 的标题"}
    ],
    # MCP-Bridge 会自动注入可用的 tool definitions
)

print(response.choices[0].message.content)

4. 高级用法：SSE 桥接

如果你使用的客户端（如 Claude Desktop 或其他支持 SSE 的 MCP 客户端）希望直接将 MCP-Bridge 视为一个 MCP 服务器，可以使用 SSE 端点：

• SSE Endpoint: http://localhost:8000/mcp-server/sse

你可以使用 mcp-cli 快速测试连接：

npx @wong2/mcp-cli --sse http://localhost:8000/mcp-server/sse