跳到主要内容

MCP Support

本篇文档介绍了如何轻松设置和部署 Open WebUI 提供的 MCP (Model Context Protocol) 到 OpenAPI 代理服务器 (mcpo)。了解如何使用适用于终端用户和开发人员的标准、熟悉的 OpenAPI 端点来暴露基于 MCP 的工具服务器。

信息

本页介绍的是 mcpo（MCP 到 OpenAPI 桥接器）。如果您想了解 Open WebUI 原生的 MCP 支持，请参阅 Model Context Protocol (MCP)。

⚠️ 凭据持久化的关键提示

如果您使用 API Key 或 Auth Token（身份验证令牌）将 Open WebUI 连接 to 此代理，您 必须 在 Open WebUI Docker 配置中设置 WEBUI_SECRET_KEY。如果该密钥发生变化（例如在容器重启时），Open WebUI 将无法解密为您工具存储的凭据。

📌 什么是 MCP 代理服务器？​

MCP 到 OpenAPI 代理服务器允许您直接通过标准的 REST/OpenAPI API 来使用通过 MCP (Model Context Protocol) 实现的工具服务器——无需管理陌生或复杂的自定义协议。如果您是终端用户或应用程序开发人员，这意味着您可以直接通过熟悉的类似于 REST 的端点，轻松地与强大的基于 MCP 的工具进行交互。

💡 为什么使用 mcpo？​

虽然 MCP 工具服务器功能强大且灵活，但它们通常通过标准输入/输出（stdio）进行通信——通常在您的本地机器上运行，这样它们可以轻松访问您的文件系统、环境变量和其他原生系统功能。

这是一项优势——但也是一项限制。

如果您想在云端部署您的主界面（如 Open WebUI），您很快就会遇到一个问题：您的云端实例无法直接通过 stdio 与您本地机器上运行 of MCP 服务器进行通信。

这就是 mcpo 带来的颠覆性解决方案大显身手的地方。

MCP 服务器通常依赖于原始的 stdio 通信，这具有以下限制：

  • 🔓 跨环境时本质上是不安全的
  • ❌ 与大多数现代工具、UI 或平台不兼容
  • 🧩 缺乏身份验证、文档和错误处理等关键功能

mcpo 代理解决了这些问题：

  • ✅ 立即与现有的 OpenAPI 工具、SDK 和客户端兼容
  • 🛡 用安全、可扩展且基于标准的 HTTP 端点来包裹您的工具
  • 🧠 为每个工具自动生成交互式的 OpenAPI 文档，完全免配置
  • 🔌 使用纯 HTTP——无需设置 Socket、无需管理守护进程，也无需编写平台特定的胶水代码

因此，尽管一开始添加 mcpo 看起来像是“多了一层”——但实际上，它简化了一切，同时为您提供了：

  • 更好的集成 ✅
  • 更好的安全性 ✅
  • 更好的可扩展性 ✅
  • 更满意的开发人员与用户 ✅

✨ 借助 mcpo，您仅在本地可用的 AI 工具将变得具备云就绪性、对 UI 友好，并且能立即实现互操作——通常无需更改您的工具服务器代码。

提示

事件支持：虽然 mcpo 将 MCP 工具暴露为 OpenAPI 端点，但它们仍然可以通过 Open WebUI 的 事件 REST 端点 发送事件（状态更新、通知）。Open WebUI 会自动将所需的 X-Open-WebUI-Chat-Id 和 X-Open-WebUI-Message-Id 响应头传递给您的工具。然而，需要用户输入的交互式事件仅对原生 Python 工具可用。

✅ 快速开始：在本地运行代理​

以下是使用轻量、易用的工具 mcpo (GitHub 仓库) 启动 MCP 到 OpenAPI 代理服务器的简单步骤：

  1. 前提条件

    • 已安装 pip 的 Python 3.8+。
    • 兼容 MCP 的应用程序（例如：mcp-server-time）。
    • （可选但推荐）已安装 uv，以实现更快的启动和零配置的便利性。

  2. 安装 mcpo

使用 uv（推荐）：

uvx mcpo --port 8000 -- your_mcp_server_command

或者使用 pip：

pip install mcpo
mcpo --port 8000 -- your_mcp_server_command
  1. 🚀 运行代理服务器

要启动您的 MCP 到 OpenAPI 代理服务器，您需要一个兼容 MCP 的工具服务器。如果您目前还没有，MCP 社区提供了各种开箱即用的 MCP 服务器实现。

✨ 在哪里可以找到 MCP 服务器？

您可以在以下示例仓库中发现官方支持的 MCP 服务器：

例如，广受欢迎的 Time MCP Server 在此处有详细记录，并且通常在 README 中的 MCP 配置内有明确引用。具体来说，README 指出：

添加到您的 Claude 设置中：

"mcpServers": {
  "time": {
    "command": "uvx",
    "args": ["mcp-server-time", "--local-timezone=America/New_York"]
  }
}

🔑 将此 MCP 设置转化为快速的本地代理命令：

您可以很容易地通过 MCP 到 OpenAPI 代理（mcpo）直接运行推荐的 MCP 服务器（mcp-server-time），如下所示：

uvx mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

就这么简单！您现在已经在本地运行了 MCP 到 OpenAPI 代理，并通过标准的 OpenAPI 端点暴露了强大的 MCP Time Server，可以通过以下地址访问：

您可以随意将 uvx mcp-server-time --local-timezone=America/New_York 替换为您在官方仓库中找到的其他可用 MCP 实现中的首选 MCP 服务器命令。

🤝 要在启动服务器后将其与 Open WebUI 集成，请查看我们的 文档。

🚀 访问生成的 API​

启动后，MCP 代理（mcpo）会自动执行以下操作：

  • 动态发现 MCP 工具并生成 REST 端点。
  • 创建交互式、易读的 OpenAPI 文档，可通过以下地址访问：
    • http://localhost:8000/docs

只需直接通过 HTTP 客户端、AI 智能体（agents）或您偏好的其他 OpenAPI 工具来调用自动生成的 API 端点。

📖 终端用户的示例工作流​

假设您启动了上述服务器命令（uvx mcp-server-time）：

  • 访问您本地位于 http://localhost:8000/docs 的 API 文档。
  • 选择一个生成的端点（例如 /get_current_time）并使用提供的交互式表单。
  • 点击“Execute”并立即收到您的响应。

无需复杂的设置——只需准备好可供使用的 REST API。

🚀 在生产环境中部署（示例）​

部署您的 MCP 到 OpenAPI 代理（由 mcpo 提供支持）非常简单。以下是如何轻松对其进行 Docker 化并将其部署到云端或 VPS 解决方案的方法：

🐳 使用 mcpo 将您的代理服务器 Docker 化​

  1. Dockerfile 示例

在您的部署目录中创建以下 Dockerfile：

FROM python:3.11-slim
WORKDIR /app
RUN pip install mcpo uv

# 替换为您的 MCP 服务器命令；例如：uvx mcp-server-time
CMD ["uvx", "mcpo", "--host", "0.0.0.0", "--port", "8000", "--", "uvx", "mcp-server-time", "--local-timezone=America/New_York"]
  1. 在本地构建并运行容器
docker build -t mcp-proxy-server .
docker run -d -p 8000:8000 mcp-proxy-server
  1. 部署您的容器

推送到 DockerHub 或另一个镜像托管服务：

docker tag mcp-proxy-server yourdockerusername/mcp-proxy-server:latest
docker push yourdockerusername/mcp-proxy-server:latest

使用 Docker Compose、Kubernetes YAML 清单或您喜爱的云容器服务（AWS ECS, Azure Container Instances, Render.com 或 Heroku）进行部署。

✔️ 您的生产级 MCP 服务器现在可以通过 REST API 进行访问了！

🧑‍💻 技术细节与背景​

🍃 工作原理（技术总结）​

  • 动态 Schema 发现与端点生成： 在服务器启动时，代理连接到 MCP 服务器以查询可用的工具。它根据 MCP 工具 schema 自动构建 FastAPI 端点，创建简洁明了在大 REST 端点。

  • OpenAPI 自动文档化： 生成的端点会被无缝记录归档，并可通过 FastAPI 内置的 Swagger UI（/docs）获取。无需编写额外的文档。

  • 异步与高性能：构建在强大的异步库之上，专为多并发用户的速度和可靠性而设计。

📚 底层原理​

  • FastAPI（自动路由与文档生成）
  • MCP 客户端（标准 MCP 集成与 Schema 发现）
  • 基于 HTTP 的标准 JSON（轻松集成）

⚡️ 为什么 MCP 到 OpenAPI 代理更优越？​

以下是为什么通过代理方法利用 OpenAPI 使用 MCP 服务器明显更好，以及为什么 Open WebUI 热烈支持该方法的原因：

  • 用户友好且熟悉的界面：没有自定义客户端；只有您已经熟知的 HTTP REST 端点。
  • 即时集成：立即可与数以千计的现有 REST/OpenAPI 工具、SDK 和服务兼容。
  • 强大且自动化的文档：自动生成、实时更新且易于维护的内置 Swagger UI 文档。
  • 没有新的协议开销：消除了直接处理 MCP 特定协议复杂性和 Socket 通信问题的必要性。
  • 成熟的安全性与稳定性：继承了成熟的 HTTPS 传输、标准身份验证方法（JWT, API keys）、稳固的异步库以及 FastAPI 的强大框架。
  • 面向未来：MCP 代理使用现有的、稳定的、标准的 REST/OpenAPI 格式，拥有广泛的社区支持和持续的演进。

🌟 底部结论： MCP 到 OpenAPI 通过直观、可靠且可扩展的 REST 端点，使您强大的基于 MCP 的 AI 工具能够被广泛访问。Open WebUI 自豪地支持并推荐这种方法。

📢 社区与支持​

祝您集成愉快！🌟🚀

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.