# Open WebUI 集成 MCP：MCPO 与 Claw Cloud 部署

在 AI 应用开发领域，模型与工具的无缝集成一直是提升生产力的关键。Open WebUI 作为一款功能丰富的开源界面框架，为大模型提供了直观的交互方式。然而，要充分发挥大模型工具调用能力，我们需要将其与主流的 MCP (Model Context Protocol) 协议集成。本文将详细介绍如何通过 MCPO 实现这一集成，并利用 Claw Cloud Run 的免费容器资源实现零成本部署 MCPO 。

# 架构概览

在深入实施之前，可以先大概了解一下 Open WebUI 与 MCP 的集成架构。以下是一个简化的架构图，展示了 Open WebUI、MCPO 以及 MCP 服务器之间的关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Open WebUI    │───▶│      MCPO       │───▶│  MCP Servers    │
│   (Web Client)  │    │   (Proxy Layer) │    │ (Tools & Data)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │

    User Interface       Protocol Bridge          External APIs
  - Chat Interface     - MCP <-> OpenAPI        - Memory Service
  - Tool Management    - Authentication         - Time Service
  - Model Controls     - Request Routing        - File System
                       - API Documentation      - Database

# MCP 协议概述

Model Context Protocol（MCP）是由 Anthropic 在 2024 年 11 月推出的开放标准，旨在为 AI 应用程序与外部数据源、工具系统之间建立安全、双向的连接。MCP 解决了 AI 模型长期面临的数据孤岛问题，即使是最先进的模型也往往被困在信息孤岛中，无法有效访问外部系统和实时数据。

# 核心架构

MCP 采用客户端-服务器架构，基于 JSON-RPC 2.0 协议构建，提供了一个有状态的会话协议。整个生态系统包含三个核心组件：

• MCP 客户端（MCP Clients）：希望访问外部系统的 AI 应用程序或代理，如 Claude Desktop、IDE 插件等
• MCP 服务器（MCP Servers）：作为 MCP 世界与具体外部系统之间的桥梁，将外部功能按照 MCP 规范进行封装
• MCP 主机（MCP Hosts）：充当多个客户端实例的"容器"或协调器，管理生命周期和安全策略

# 三大核心原语

MCP 通过三种基本构建块为语言模型提供上下文：

1. 工具（Tools）：LLM 可以调用的函数，用于执行特定操作，如天气查询 API
2. 资源（Resources）：LLM 可以访问的数据源，类似于 REST API 中的 GET 端点，提供数据但不执行重要计算
3. 提示（Prompts）：预定义的模板，用于以最优方式使用工具或资源

# 通信方式

MCP 支持两种主要通信方式：

• stdio（标准输入/输出）：当客户端和服务器在同一机器上运行时使用，适合本地集成
• HTTP via SSE（服务器发送事件）：客户端通过 HTTP 连接到服务器，适合远程服务集成

# 生态系统发展

自发布以来，MCP 得到了广泛的行业采用：

• 官方支持：OpenAI、Google DeepMind 等主要 AI 提供商已采用该协议
• 企业集成：Block、Apollo、Zed、Replit、Codeium、Sourcegraph 等公司已实现 MCP 支持
• 开源生态：到 2025 年 2 月，已有超过 1,000 个开源连接器出现
• 服务集成：支持 Google Drive、Slack、GitHub、PostgreSQL 等热门企业系统

# 安全性考量

MCP 在设计时充分考虑了安全性：

• OAuth 2.1 认证：协议要求对远程 HTTP 服务器实施 OAuth 2.1 框架进行身份验证
• 资源指示器：MCP 客户端需要实现资源指示器（RFC 8707），明确指定访问令牌的预期接收者
• 权限控制：支持基于角色的权限管理和用户授权

MCP 的出现将原本的"N×M 问题"（每个数据源都需要自定义连接器）转换为"M+N 问题"，工具创建者构建 N 个 MCP 服务器，应用程序开发者构建 M 个 MCP 客户端，大大简化了 AI 工具集成的复杂性。

# 第一部分：MCPO 简介与本地测试

# 1.1 MCPO 是什么？

MCPO 是一个轻量级代理服务器，它接收 MCP 服务器命令，并通过标准的 RESTful OpenAPI 使其可访问，因此工具可以“开箱即用”地与期望 OpenAPI 服务器的 LLM agents 和应用程序配合使用。简单来说，它充当 Open WebUI 与 MCP 工具服务器之间的翻译层。通过将 MCP 协议转换为标准的OpenAPI 规范，MCPO 使 MCP 服务能够以 RESTful API 的形式被 Open WebUI 访问。

MCPO 的核心优势在于：

• 协议转换：将 MCP 通信转换为 OpenAPI 兼容的HTTP接口
• 安全隔离：在浏览器客户端与本地服务之间建立安全边界
• 多工具支持：可同时代理多个MCP服务器，实现工具扩展
• 自动文档：为每个MCP工具自动生成交互式 OpenAPI 文档

快速使用：

官方最推荐的方式是通过 uv 包管理器进行安装和配置 MCPO ，可以一行启动 MCPO 服务：

1

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

当然也可以使用 Python + pip 安装：

1
2

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

# 1.2 本地测试 MCPO

在本文中，我们使用 Docker 容器来运行 MCPO 服务，并且基于 config.json 文件进行 MCP Servers 的配置。

# 步骤 1：准备配置文件

首先，创建 config.json 文件，内容如下（后续只使用 memory 和 time 工具作为测试）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    },
    "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
  }
}

其中，每个具体的 MCP Server 都有几个可选的字段，最常见的是 command, args, type, url, env 这五个字段。

• command：指定 MCP Server 的启动命令
• args：传递给 MCP Server 的参数列表
• type：指定 MCP Server 的类型 (如 sse, streamable_http 等，默认是 stdio，不用填写)
• url：如果 MCP Server 是通过 sse 或 streamable http 协议提供服务，则需要指定其 URL
• env：指定 MCP Server 的环境变量，一般是用户鉴权信息

# 步骤 2：创建 Docker Compose 文件

接着编写对应的 docker-compose.yml 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

services:
  mcpo:
    image: ghcr.io/open-webui/mcpo:main
    container_name: mcpo
    restart: unless-stopped
    ports:
      - "127.0.0.1:8000:8000"
    volumes: 
      - ./config.json:/app/config.json
    command: --config config.json --api-key "Your Key"

# 步骤 3：启动 MCPO 服务

在当前目录下运行以下命令启动 MCPO 服务：

1

docker compose up -d

# 步骤 4：验证服务运行

运行 CURL 命令测试 MCPO 服务是否正常：

1

curl -X GET "http://127.0.0.1:8000/openapi.json"

正常情况下会返回以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "openapi": "3.1.0",
  "info": {
    "title": "MCP OpenAPI Proxy",
    "description": "Automatically generated API from MCP Tool Schemas\n\n- **available tools**：\n    - [memory](/memory/docs)\n    - [time](/time/docs)\n",
    "version": "1.0"
  },
  "paths": {

  }
}

到此，本地测试 MCPO 服务已经完成。接下来，本文将介绍如何将其部署到 Claw Cloud Run 并接入 Open WebUI。

# 第二部分：Claw Cloud Run 免费部署 MCPO

# 2.1 Claw Cloud Run 平台介绍

Claw Cloud Run 是一个专业的容器化应用部署平台，专注于为开发者提供简单、高效的云原生应用部署体验。与传统的云服务相比，Claw Cloud Run 具有以下特点：

# 平台特色

• 极简部署：支持从 Docker 镜像直接部署，无需复杂的配置
• 弹性扩缩容：支持弹性伸缩，选择合适的资源配置
• 全球加速：具有多个地区节点，提供更快的访问速度
• 开发者友好：提供直观的 Web 控制台和完整的 API 接口

# 免费额度政策

Claw Cloud Run 为注册超过 180 天的 GitHub 用户提供慷慨的免费额度：

• 计算资源：每月 5 美元的免费额度
• 网络流量：包含一定量的出站流量
• 存储空间：提供基础的持久化存储
• 域名服务：免费的 .clawcloudrun.com 子域名

提示

免费额度足以支撑中小型项目的开发和测试需求。对于生产环境，建议根据实际使用情况升级到付费计划。

# 技术架构

Claw Cloud Run 基于 Kubernetes 构建，提供：

• 多区域部署：支持亚太、欧洲、北美等多个区域
• 负载均衡：内置智能负载均衡和故障转移
• 监控告警：实时监控应用状态和性能指标
• 日志管理：集中化的日志收集和分析

# 2.2 前置准备

在开始部署前，请确保已准备好以下账号：

• GitHub 账号：注册时间需超过 180 天（用于免费额度验证）
• Claw Cloud 账号：通过 GitHub 账号授权登录
• 域名（可选）：如需自定义域名，请准备好域名和 DNS 管理权限

# 2.3 创建应用部署

# 步骤 1：登录控制台并查看免费额度

登录 Claw Cloud 控制台，选择 Github 登录，点击右上角的 Plan，可以看到有每个月 5$ 的免费额度。

# 步骤 2：创建应用实例

回到首页，进入 App Launchpad，点击 Create App，填写应用名称（如 mcpo），并完成以下设置：

• 应用名称：mcpo
• 镜像名称：ghcr.io/open-webui/mcpo:main
• 资源大小：0.5vCPU, 1GB 内存
• 端口：8000
• 开启公网访问：是
• 自定义域名：可选，需要配置 CNAME 解析到 Claw Cloud 的域名

# 2.4 配置应用参数

# 步骤 3：设置启动命令

启动命令设置为 mcpo --config config.json，设置 API Key 用于访问控制：

重要

为了确保安全性，请使用强密码作为 API Key，并定期轮换。不要在公开代码中暴露实际的 API Key。

# 步骤 4：配置 MCP Servers

配置 config.json 文件，在 Configmaps 中新增 /app/config.json 文件，内容与本地测试时的 config.json 相同：

警告

在配置远程 SSE 或 Streamable HTTP 类型的 MCP Servers 时，请确保仅添加可信任的服务器。恶意的 MCP Server 可能会执行不安全的操作。

# 步骤 5：配置持久化存储

新增本地存储，挂载 /root 目录，一般来说 5GB 的存储空间足够使用：

# 2.5 部署应用

# 步骤 6：完成配置并部署

完成上述配置后如下所示：

# 步骤 7：部署并验证

接着就可以点击右上角的 Deploy Application 按钮部署 MCPO 服务。显示如下的 running 状态并且通过域名访问 /openapi.json 有正常响应即表示部署成功：

# 第三部分：在 Open WebUI 中连接工具服务器

# 3.1 连接 MCPO 服务器

# 步骤 1：添加工具服务器

将运行中的 MCPO 服务器连接到 Open WebUI：

1. 在浏览器中打开 Open WebUI
2. 打开 ⚙️ 设置
3. 点击 ➕ 工具，添加新的工具服务器
4. 输入运行 OpenAPI 工具服务器的 URL（如 Claw Cloud Run 默认的域名: https://xxx.ap-southeast-1.clawcloudrun.com）
5. 点击 “保存”

警告

在添加工具服务器时，请确保：

• 使用 HTTPS 协议确保数据传输安全
• 验证服务器 URL 的有效性，避免输入错误的地址
• 仅连接到可信任的 MCPO 服务器
• 如果服务器需要 API Key 认证，请在相应字段中输入

# 3.2 用户工具服务器 vs 全局工具服务器

如果是管理员，则可以在后台管理员设置 → 工具 → 管理工具服务器中配置全局的工具服务器。至于这两种方式的区别，可以参考官方的说明：

用户工具服务器和全局工具服务器的主要区别在于，API 连接和请求实际上是在哪里进行的：

用户工具服务器通过浏览器（客户端）直接向工具服务器发出请求。这意味着可以安全地连接到本地主机 URL，甚至可以暴露私人端点或仅用于开发的端点，连接是私有的。

全局工具服务器通过 Open WebUI 后端（服务器）进行连接。后端必须能够访问指定的工具服务器 URL，使用此方法可与部署范围内的其他用户共享工具，请求是由后台发出的，无法通过此方法访问个人本地资源，而且需要慎重考虑安全性。

提示

用户工具服务器适用于个人使用和本地开发测试，可以直接连接到本地主机 URL。而全局工具服务器则适用于生产或共享环境，在这些环境中，每个人都需要访问相同的工具。

# 3.3 使用工具服务器

# 步骤 2：在聊天界面中使用工具

完成上述步骤后，将可以在聊天界面中找到工具服务器（输入框的下方）：

单击该图标可打开一个弹出窗口，可以：

• 查看已连接的工具服务器信息
• 查看哪些工具可用以及由哪个服务器提供
• 必要时调试或断开任何工具

提示

全局工具服务器显示外观有所不同，需要点击消息输入区的 ➕ 按钮才会显示工具信息。

重要

在通过 ➕ 菜单启用之前，它们不会显示在工具指示器弹出窗口中。

每个全局工具都必须单独打开，才能在当前聊天中激活。

一旦开启，其功能与用户工具相同。

管理员可以通过基于角色的权限控制对全局工具的访问。

这非常适合团队设置或共享环境，在这些环境中，常用工具（如文档搜索、网络查询）提供给多个用户集中访问。

# 3.4 启用原生工具模式

# 步骤 3：配置 ReACT 风格的函数调用

想在会话中直接启用 ReACT 风格（推理 + 执行）的本地函数调用，则需要在模型设置页面启用原生工具模式：

1. 进入 ⚙️ Chat Controls（聊天控制）→ Advanced Params（高级参数）
2. 将函数调用参数从 Default 改为 Native

# 第四部分：常见问题与排查

以下是一些比较常见的问题及解决方案：

# 4.1 无法连接到 MCPO 服务器

• 确保 MCPO 服务正在运行，并且端口配置正确。
• 检查防火墙设置，确保允许访问指定端口。
• 如果使用 Claw Cloud Run，请确保已正确配置域名和端口。
• 检查 MCPO 服务的日志，以获取更多错误信息。

# 4.2 工具无法正常工作

• 确保 MCP Server 已正确配置，并且 config.json 文件中的工具配置正确。
• 检查 MCPO 的 OpenAPI 文档，确保工具的 API 路径和参数正确。
• 如果工具需要特定的权限或 API Key，请确保已正确设置。

# 4.3 工具服务器响应慢

• 检查 MCPO 服务的资源配置，确保分配了足够的 CPU 和内存。
• 如果使用 Claw Cloud Run，请检查当前的免费额度是否已用完。
• 确保 MCP Server 的性能良好，必要时可以优化工具的实现。

# 4.4 工具无法在 Open WebUI 中显示

• 确保已正确连接工具服务器，并且工具服务器的 URL 正确。
• 检查 Open WebUI 的设置，确保已启用工具服务器。
• 如果是全局工具服务器，请确保已在管理员设置中正确配置。

# 总结

通过 MCPO 将 MCP 能力集成到 Open WebUI，不仅扩展了 AI 助手的功能性，还通过标准化接口简化了工具管理流程。借助 Claw Cloud Run 的免费额度，开发者可以零成本部署 MCPO 服务，实现云端化访问 MCP 工具。

这种方案的优势在于：

• 灵活性：支持任意 MCP 兼容工具，只需改写 config.json 就能轻松扩展
• 经济性：利用免费容器资源，无需额外的服务器成本
• 安全性：通过代理层隔离本地服务与 Web 界面
• 可扩展性：随业务需求平滑升级资源配置

重要

定期关注 Claw Cloud Run 的免费额度政策和 MCPO 项目更新，以获取最新功能和最佳实践。对于生产环境，建议配置监控告警和定期备份，确保服务稳定运行。