使用 Open MCP Gateway 为本地 MCP 服务构建 OpenAPI 网关

什么是 Open MCP Gateway？

Open MCP Gateway（简称 OMG）是一个高性能网关，可通过符合 OpenAPI 3.1.0 的 HTTP REST 路由公开本地部署的 Model Context Protocol 服务。它使用 Bun 1.4 和 TypeScript 构建，面向 Open WebUI 生态，不过它是一个社区项目，与 Open WebUI 团队没有关联。

该网关位于外部客户端与一个或多个 MCP 服务之间。Open WebUI 等客户端通过 HTTP 或 HTTPS 与网关通信，而网关负责管理底层 MCP 传输，并将这些服务提供的工具转换为兼容 OpenAPI 的接口。

OMG 支持原生二进制 stdio 服务、基于 Node 或 Bun 脚本的 stdio 管道，以及 SSE 或 HTTP 网络传输。因此，使用不同执行和通信模型的 MCP 服务也能通过统一的 HTTP 接口提供服务。

主要功能

• 严格的 OpenAPI 3.1.0 输出：工具输入架构位于 requestBody.content['application/json'].schema 下。生成的 operationId 值保留原始 MCP 工具名称，而不会添加 tool_*_post 等名称。
• 多种 MCP 传输方式：原生二进制 stdio、脚本 stdio、SSE 和 HTTP 服务均可通过一个网关管理。
• 蓝绿会话池：服务会话在 AsyncMutex 后台热切换，可在不中断正在处理的请求的情况下更新配置。
• 生命周期管理：网关为受管理的服务提供协议封装、生命周期自愈和热重载。
• 跨平台 XDG 目录布局：配置、应用数据、运行时状态和缓存文件均保存在源代码仓库之外。
• 独立构建：Bun 可将网关编译为不依赖运行时的原生可执行文件。
• 反向代理支持：网关读取 X-Forwarded-* 标头，使生成的 OpenAPI servers.url 反映客户端看到的外部地址。

前置条件

从源代码运行项目需要 Bun 1.4 或更高版本。你还需要至少注册一个 MCP 服务。该服务可以是本地原生可执行文件、通过 Bun 启动的 JavaScript 或 TypeScript 包，也可以是通过 SSE 或 HTTP 提供的 MCP 服务。

安装并运行网关

从源代码运行

克隆或下载仓库，进入其目录，安装依赖，然后启动开发命令：

bun install
bun run dev

开发进程从平台的 XDG 配置目录读取网关配置，而不是从仓库本身读取。

构建独立可执行文件

要创建原生可执行文件，请运行：

bun run build

在类 Unix 系统上，输出文件位于 build/mcp-gateway；在 Windows 上位于 build/mcp-gateway.exe。部署编译后的二进制文件时，不需要单独安装 Bun 运行时。

了解 XDG 目录布局

Open MCP Gateway 按用途分离文件，从而避免生成数据、已安装插件、日志和缓存污染源代码目录。

• 配置：XDG_CONFIG_HOME 包含主配置文件 mcp-gateway/config.json5。
• 数据：XDG_DATA_HOME 包含外部 MCP 插件仓库及其自身的 package.json。
• 状态：XDG_STATE_HOME 存储运行时状态和持久化日志。
• 缓存：XDG_CACHE_HOME 存储缓存的规范文档和临时运行时数据。

主配置路径为：

$XDG_CONFIG_HOME/mcp-gateway/config.json5

该文件使用 JSON5，因此支持注释和尾随逗号。

配置 MCP 服务

如有必要，请创建配置目录，然后添加 config.json5。以下示例注册了一个原生 MCP 可执行文件和一个基于包的 MCP 服务：

{
    mcpServers: {
        // Native Binary Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // Script Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

mcpServers 中的每个键都用于标识一个 MCP 服务。对于原生二进制文件，请将 command 设置为可执行文件路径。对于基于包的服务，请使用 Bun 作为命令，并通过 args 传入已安装的脚本路径。可以将服务专用的环境变量添加到 env 中。

网关支持路径中的环境变量插值。可用变量包括 ${APP_DATA_DIR}、${XDG_DATA_HOME}、${HOME} 和 %USERPROFILE%。插值让配置更易于在不同计算机之间复用，无需硬编码每个绝对路径。

请保持服务标识符稳定。例如，名为 codebase_memory 的服务会通过获取其 OpenAPI 文档时使用的对应 URL 路径公开。

管理外部 MCP 插件

特定业务的 MCP 包不应安装在网关仓库中。请将其安装并维护在网关的 XDG 数据目录中：

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

要升级已安装的包，请运行：

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

安装完成后，使用 ${APP_DATA_DIR} 在 config.json5 中引用软件包入口点，具体示例请参见脚本 stdio 示例。这样可以将网关依赖与 MCP 扩展依赖分开。

基本用法

1. 安装网关依赖，或构建原生可执行文件。

2. 创建 $XDG_CONFIG_HOME/mcp-gateway/config.json5。

3. 在 mcpServers 下添加一个或多个服务。

4. 使用 bun run dev 启动网关，或运行已编译的可执行文件。

5. 获取已配置服务的 OpenAPI 文档，并将其注册到外部客户端。

对于名为 codebase_memory 的服务，文档规定的 OpenAPI URL 模式为：

http://<gateway-host>:8444/codebase_memory/openapi.json

在此示例中，8444 是外部可访问端口。它可能是反向代理端口，而不是网关的内部端口，例如配置示例中的 9090。

与 Open WebUI 集成

Caddy 或 Nginx 等反向代理可以通过所需的外部主机、端口和协议公开网关。配置代理以发送适当的 X-Forwarded-* 标头。Open MCP Gateway 会读取这些标头来生成 OpenAPI 文档，确保其中的 servers.url 指向公共地址，而不是内部监听地址。

1. 在反向代理后启动 Open MCP Gateway。

2. 打开 Open WebUI 管理面板。

3. 进入 Functions、Tools 或 OpenAPI 区域。

4. 为每个已配置的 MCP 服务注册 OpenAPI 文档 URL：

   http://<gateway-host>:8444/codebase_memory/openapi.json

5. 允许 Open WebUI 加载规范文档。随后，MCP 服务的工具即可通过生成的 OpenAPI 操作作为原生工具使用。

由于操作 ID 保留了原始 MCP 工具名称，客户端可以看到简洁的工具标识符，不会出现网关生成的后缀或前缀。

测试与日志监控

修改网关或其配置后，运行项目的测试命令：

bun run test

在 Windows 上，仓库还提供了 PowerShell 测试脚本：

.\ps1_scripts\test-gateway.ps1

端到端断言涵盖健康检查、MCP 握手和代理源地址一致性。

在类 Unix 系统上，使用以下命令持续查看网关日志：

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

排查进程启动问题、无效的可执行文件路径、MCP 握手失败或反向代理配置问题时，这非常有用。

高级技巧

使用可移植路径

优先使用 ${HOME} 和 ${APP_DATA_DIR} 等插值路径，而不是特定于某台机器的绝对路径。在 Windows 上，可以在适当位置使用 %USERPROFILE%。这样可以更轻松地在不同系统之间共享配置。

将插件置于源代码检出目录之外

将外部 MCP 软件包安装到 $XDG_DATA_HOME/mcp-gateway。这样可以保持源代码树整洁，并允许独立升级网关及其业务扩展。

分离内部地址与外部地址

将网关绑定到 127.0.0.1 可以使内部监听器保持本地访问。随后，反向代理可以提供外部 TLS 端点。确保转发的标头描述公共协议、主机和端口，以便生成的 OpenAPI 文档公布正确的 URL。

利用热更新

蓝绿会话池会交换服务会话，并使用 AsyncMutex 保护切换过程。这种设计允许在不中断正在运行的请求的情况下更新配置。热重载和生命周期自愈机制进一步减少了手动管理进程的需要。

为部署进行编译

当目标服务器不应需要安装 Bun 或项目依赖时，使用 bun run build。将生成的可执行文件与所需的 XDG 配置，以及单独管理的 MCP 二进制文件或软件包一同部署。

结语

Open MCP Gateway 提供了一座从本地 MCP 服务到严格 OpenAPI 3.1.0 路由的统一桥梁。通过结合多传输支持、基于 XDG 的可移植配置、外部插件管理、反向代理感知和独立构建，它为将本地 MCP 工具提供给 Open WebUI 及其他支持 OpenAPI 的客户端提供了实用方案。