⚡️ mcpo

将任何 MCP 工具暴露为兼容 OpenAPI 的 HTTP 服务器——即时完成。

mcpo 是一个极其简单的代理，它接收 MCP 服务器命令，并通过标准的 RESTful OpenAPI 将其公开，从而使您的工具能够与期望 OpenAPI 服务器的 LLM 代理和应用程序无缝协作。

无需自定义协议，无需胶水代码，零 hassle。

🤔 为什么使用 mcpo 而不是原生 MCP？

MCP 服务器通常通过原始的 stdio 进行通信，这种方式：

• 🔓 天然不安全
• ❌ 与大多数工具不兼容
• 🧩 缺乏文档、认证、错误处理等标准功能

mcpo 能够轻松解决这些问题，且无需额外工作：

• ✅ 可立即与 OpenAPI 工具、SDK 和 UI 配合使用
• 🛡 使用成熟的 Web 标准增强安全性、稳定性和可扩展性
• 🧠 自动为每个工具生成交互式文档，无需任何配置
• 🔌 完全基于 HTTP——无需套接字、无需胶水代码、没有任何意外

看似多了一步的操作，实际上却减少了步骤并带来了更好的结果。

mcpo 让您的 AI 工具即刻变得可用、安全且具备互操作性——现在就行动吧，完全无需麻烦。

🚀 快速使用

我们推荐使用 uv，以实现闪电般的启动速度和零配置。

uvx mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command

或者，如果您使用的是 Python：

pip install mcpo
mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command

要使用 SSE 兼容的 MCP 服务器，只需指定服务器类型和端点：

mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse

您还可以为 SSE 连接提供头部信息：

mcpo --port 8000 --api-key "top-secret" --server-type "sse" --header '{"Authorization": "Bearer token", "X-Custom-Header": "value"}' -- http://127.0.0.1:8001/sse

要使用支持流式传输的 HTTP 兼容 MCP 服务器，指定服务器类型和端点：

mcpo --port 8000 --api-key "top-secret" --server-type "streamable-http" -- http://127.0.0.1:8002/mcp

您也可以通过 Docker 运行 mcpo，无需安装：

docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_command

示例：

uvx mcpo --port 8000 --api-key "top-secret" -- uvx mcp-server-time --local-timezone=America/New_York

就是这样。您的 MCP 工具现在可通过 http://localhost:8000 访问，并附带自动生成的 OpenAPI 模式——您可以在 http://localhost:8000/docs 上实时测试。

🤝 要在启动服务器后与 Open WebUI 集成，请查看我们的[文档](https://docs.openwebui.com/openapi-servers/open-webui/）。

🌐 在子路径下提供服务（--root-path）

如果您需要在反向代理后或在子路径下（例如 /api/mcpo）提供 mcpo 服务，请使用 --root-path 参数：

mcpo --port 8000 --root-path "/api/mcpo" --api-key "top-secret" -- your_mcp_server_command

所有路由都将在此指定的根路径下提供服务，例如 http://localhost:8000/api/mcpo/memory。

🔄 使用配置文件

您可以使用遵循 Claude Desktop 格式的单个配置文件来提供多个 MCP 工具的服务。

启用热重载模式 --hot-reload，以自动监视您的配置文件更改并在不停机的情况下重新加载服务器：

通过以下方式启动：

mcpo --config /path/to/config.json

或启用热重载：

mcpo --config /path/to/config.json --hot-reload

示例 config.json：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"],
      "disabledTools": ["convert_time"] // 如需可禁用特定工具
    },
    "mcp_sse": {
      "type": "sse", // 显式定义类型
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer token",
        "X-Custom-Header": "value"
      }
    },
    "mcp_streamable_http": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8002/mcp"
    } // 支持流式传输的 HTTP MCP 服务器
  }
}

每个工具都将通过其独特的路由访问，例如：

• http://localhost:8000/memory
• http://localhost:8000/time

每个工具都配有独立的 OpenAPI 模式和代理处理器。完整的模式 UI 可通过：http://localhost:8000/<tool>/docs 访问（例如 /memory/docs、/time/docs）。

🔐 OAuth 2.1 认证

mcpo 支持需要 OAuth 2.1 认证的 MCP 服务器。实现默认采用 动态客户端注册，因此大多数服务器只需进行最少的配置：

{
  "mcpServers": {
    "oauth-protected-server": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "oauth": {
        "server_url": "http://localhost:8000"
      }
    }
  }
}

OAuth 配置选项

基本选项：

• server_url（必填）：OAuth 服务器基础 URL
• storage_type：“file”（持久存储）或“memory”（仅会话，默认为“file”）
• callback_port：用于 OAuth 回调的本地端口（默认为 3030）
• use_loopback：自动打开浏览器进行认证（默认为 true）

高级选项（很少需要）： 对于不支持动态客户端注册的服务器，您可以指定静态的客户端元数据：

{
  "mcpServers": {
    "legacy-oauth-server": {
      "type": "streamable-http",
      "url": "http://api.example.com/mcp",
      "oauth": {
        "server_url": "http://api.example.com",
        "client_metadata": {
          "client_name": "My MCPO Client",
          "redirect_uris": ["http://localhost:3030/callback"]
        }
      }
    }
  }
}

注意：请勿在配置中设置 scope、authorization_endpoint 或 token_endpoint。这些将在动态注册过程中从服务器的 OAuth 元数据中自动发现。

首次连接时，mcpo 将执行以下操作：

1. 执行动态客户端注册（如果支持）
2. 打开您的浏览器进行授权
3. 自动捕获 OAuth 回调
4. 安全存储令牌（对于文件存储，存储在 ~/.mcpo/tokens/ 中）
5. 在后续的所有请求中使用这些令牌

OAuth 支持 streamable-http 类型的服务器。有关详细信息，请参阅 OAUTH_GUIDE.md 文档。

🔧 要求

• Python 3.8+
• uv（可选，但强烈推荐，以获得更好的性能和打包体验）

🛠️ 开发与测试

如需贡献代码或在本地运行测试：

1. 设置开发环境：

   # 克隆仓库
   git clone https://github.com/open-webui/mcpo.git
   cd mcpo
   
   # 安装依赖（包括开发依赖）
   uv sync --dev
   

2. 运行测试：

   uv run pytest
   

3. 使用本地修改内容本地运行：

   若要使用特定分支（例如 my-feature-branch）中的本地修改来运行 mcpo，请执行以下步骤：

   # 确保当前位于您的开发分支
   git checkout my-feature-branch
   
   # 在 `src/mcpo` 目录或其他位置进行代码修改
   
   # 使用 `uv` 运行 `mcpo`，它将使用您本地修改后的代码
   # 此命令会在端口 8000 上启动 `mcpo`，并代理您的 `mcp_server_command`
   uv run mcpo --port 8000 -- your_mcp_server_command
   
   # 示例：使用一个测试的 MCP 服务器（如 `mcp-server-time`）：
   # uv run mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York
   

   这样您就可以在提交代码或创建拉取请求之前，交互式地测试您的更改。您可以通过 http://localhost:8000 访问本地运行的 mcpo 实例，并通过 http://localhost:8000/docs 查看自动生成的文档。

🪪 许可证

MIT

🤝 贡献指南

我们欢迎并强烈鼓励社区贡献！

无论您是修复 bug、添加新功能、改进文档，还是仅仅分享想法——您的参与都极其宝贵，有助于让 mcpo 更加完善，惠及所有人。

开始贡献非常简单：

• 克隆仓库并创建分支
• 进行代码修改
• 提交拉取请求

如果您不确定从哪里入手，也可以随时开一个议题或提问，我们会很乐意帮助您找到适合的入门任务。

✨ 星标历史

---

✨ 让我们一起构建可互操作的人工智能工具生态吧！

mcpo 快速上手指南

mcpo 是一个极简的代理工具，能将任意 MCP（Model Context Protocol）服务器瞬间转换为兼容 OpenAPI 标准的 HTTP 服务。无需编写胶水代码，即可让 LLM 智能体和各类应用通过标准 RESTful 接口调用你的 MCP 工具。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：Python 3.8 或更高版本
• 推荐工具：uv（用于极速启动和环境管理，强烈推荐使用）

安装步骤

你可以选择使用 uv 直接运行（无需手动安装），或通过 pip 安装。

方式一：使用 uv 直接运行（推荐）

无需预先安装，uvx 会自动处理依赖并运行最新版本的 mcpo：

uvx mcpo --help

方式二：使用 pip 安装

如果你偏好传统安装方式：

pip install mcpo

方式三：使用 Docker（免安装）

无需配置本地 Python 环境：

docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --help

基本使用

1. 启动单个 MCP 服务

将本地的 MCP 命令暴露为 OpenAPI 服务。以下示例将 mcp-server-time 转换为 HTTP 服务，并设置 API 密钥保护：

uvx mcpo --port 8000 --api-key "top-secret" -- uvx mcp-server-time --local-timezone=America/New_York

启动后：

• 服务地址：http://localhost:8000
• 交互式文档：访问 http://localhost:8000/docs 查看自动生成的 Swagger UI 并测试接口。

2. 连接远程 SSE 或 Streamable HTTP 服务

如果目标 MCP 服务是通过 HTTP (SSE 或 Streamable) 运行的，指定 --server-type 即可：

# 连接 SSE 类型的 MCP 服务
mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse

# 连接 Streamable HTTP 类型的 MCP 服务
mcpo --port 8000 --api-key "top-secret" --server-type "streamable-http" -- http://127.0.0.1:8002/mcp

3. 通过配置文件管理多个服务

创建一个 config.json 文件来同时托管多个 MCP 工具（支持热重载）：

config.json 示例：

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

启动命令：

# 普通模式
mcpo --config /path/to/config.json

# 开启热重载模式（修改配置自动生效）
mcpo --config /path/to/config.json --hot-reload

启动后，每个工具将拥有独立的路由，例如：

• 时间服务：http://localhost:8000/time
• 记忆服务：http://localhost:8000/memory
• 对应文档：http://localhost:8000/time/docs