⚡️ mcpo

⚡️ mcpo

即时将任何 MCP 工具转换为兼容 OpenAPI 的 HTTP 服务。

mcpo 是一个极简代理，它接收 MCP 服务命令，并通过标准 RESTful OpenAPI 使其可访问，让你的工具能够直接与需要 OpenAPI 服务的大模型 Agent 和应用协同工作。

无需自定义协议。无需胶水代码。毫不费力。

🤔 为什么使用 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

要使用兼容 Streamable 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 集成，请查看我们的文档。

🌐 在子路径下提供服务（--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"] // Disable specific tools if needed
    },
    "mcp_sse": {
      "type": "sse", // Explicitly define type
      "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"
    } // Streamable HTTP MCP Server
  }
}

每个工具都可以通过各自独有的路由访问，例如：

• 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，并代理 your_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
   

   这样，你就可以在提交或创建拉取请求之前交互式地测试更改。访问本地运行的 mcpo 实例：http://localhost:8000；自动生成的文档位于 http://localhost:8000/docs。

🪪 许可证

MIT

🤝 参与贡献

我们欢迎并大力鼓励社区贡献！

无论你是修复错误、添加功能、改进文档，还是分享想法，你的参与都极其宝贵，能帮助 mcpo 为所有人变得更好。

开始贡献很简单：

• Fork 代码库
• 创建新分支
• 修改代码
• 发起拉取请求

不知道从哪里开始？欢迎提交 issue 或提出问题，我们很乐意帮你找到适合入门的任务。

✨ Star 历史

---

✨ 让我们携手构建可互操作 AI 工具的未来！