MCP 支持

本文档解释了如何轻松设置和部署 Open WebUI 提供的 MCP (模型上下文协议)-to-OpenAPI 代理服务器 (mcpo)。了解如何使用适合终端用户和开发人员的标准、熟悉的 OpenAPI 端点，毫不费力地暴露基于 MCP 的工具服务器。

持久化关键提示

如果您使用 API 密钥或认证令牌将 Open WebUI 连接到此代理，您必须在 Open WebUI Docker 配置中设置 WEBUI_SECRET_KEY。如果此密钥发生更改（例如在容器重启时），Open WebUI 将无法解密为您的工具存储的凭据。

📌 什么是 MCP 代理服务器？

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

💡 为什么使用 mcpo？

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

这既是优势，也是局限。

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

这正是 mcpo 带来的改变游戏规则的解决方案。

MCP 服务器通常依赖原始的 stdio 通信，这种方式：

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

mcpo 代理自动消除了这些问题：

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

因此，尽管添加 mcpo 起初看起来像是“多了一层”，但实际上它简化了一切，并为您带来：

• 更好的集成 ✅
• 更好的安全性 ✅
• 更好的可扩展性 ✅
• 更快乐的开发人员和用户 ✅

✨ 有了 mcpo，您的仅限本地使用的 AI 工具将变得云就绪、UI 友好且可立即互操作——无需更改工具服务器的一行代码。

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

使用轻量级、易用的工具 mcpo (GitHub 仓库) 启动 MCP-to-OpenAPI 代理服务器非常简单：

1. 前提条件

   • 已安装 Python 3.8+ 和 pip。
   • 兼容 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

3. 🚀 运行代理服务器

要启动您的 MCP-to-OpenAPI 代理服务器，您需要一个兼容 MCP 的工具服务器。如果您还没有，MCP 社区提供了各种现成的 MCP 服务器实现。

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

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

• GitHub 上的 modelcontextprotocol/servers

例如，广受欢迎的 Time MCP Server 文档在这里，通常在 README 提供的 MCP 配置中会有明确引用。具体来说，README 指出：

添加到您的 Claude 设置中：

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

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

您可以直接通过 MCP-to-OpenAPI 代理 (mcpo) 轻松运行推荐的 MCP 服务器 (mcp-server-time)，如下所示：

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

就这样！您现在正在本地运行 MCP-to-OpenAPI 代理，并通过标准 OpenAPI 端点暴露强大的 MCP Time Server，访问地址为：

• 📖 交互式 OpenAPI 文档： http://localhost:8000/docs

您可以随意将 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 代理或其他 OpenAPI 工具直接调用自动生成的 API 端点即可。

📖 终端用户示例工作流

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

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

无需复杂的设置——只需即时可用的 REST API。

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

部署您的 MCP-to-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"]

2. 在本地构建并运行容器

docker build -t mcp-proxy-server .
docker run -d -p 8000:8000 mcp-proxy-server

3. 部署您的容器

推送到 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 轻松使用！

🧑‍💻 技术细节和背景

🍃 工作原理（技术总结）

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

• OpenAPI 自动文档化： 生成的端点通过 FastAPI 内置的 Swagger UI (/docs) 进行无缝文档化。无需额外编写文档。

• 异步且高效：基于强大的异步库构建，确保并发用户的速度和可靠性。

📚 内部机制：

• FastAPI（自动路由和文档生成）
• MCP Client（标准 MCP 集成和架构发现）
• 基于 HTTP 的标准 JSON（易于集成）

⚡️ 为什么 MCP-to-OpenAPI 代理更优越？

以下是为什么通过代理方法利用基于 OpenAPI 的 MCP 服务器要好得多，以及为什么 Open WebUI 热情支持它的原因：

• 用户友好且熟悉的界面：无需自定义客户端；只需您已经熟悉的 HTTP REST 端点。
• 即时集成：立即与数千个现有的 REST/OpenAPI 工具、SDK 和服务兼容。
• 强大且自动生成的文档：内置 Swagger UI 文档自动生成，始终准确且得到维护。
• 无新协议开销：消除了直接处理 MCP 特定协议复杂性和套接字通信问题的必要性。
• 经受过实战检验的安全性和稳定性：继承了成熟的 HTTPS 传输、标准认证方法（JWT、API 密钥）、可靠的异步库以及 FastAPI 经证明的健壮性。
• 面向未来：MCP 代理使用现有的、稳定的、标准的 REST/OpenAPI 格式，保证了长期的社区支持和演进。

🌟 结论： MCP-to-OpenAPI 通过直观、可靠且可扩展的 REST 端点，使您强大的基于 MCP 的 AI 工具变得广泛可访问。Open WebUI 荣幸地支持并推荐这种同类最佳的方法。

📢 社区与支持