🚀 MetaMCP（MCP 聚合器、编排器、中间件、网关一体化 Docker 镜像）

📢 更新： [作者说明：对近期维护延迟表示歉意，但至少会继续合并 PR，更多背景信息 在此]

MetaMCP 是一个 MCP 代理，允许您将多个 MCP 服务器动态聚合为一个统一的 MCP 服务器，并应用中间件。MetaMCP 本身也是一个 MCP 服务器，因此可以轻松接入 任何 MCP 客户端。

---

如需了解更多详情，请访问我们的文档网站：https://docs.metamcp.com

English | 中文

📋 目录

• 🎯 使用场景
• 📖 概念
  • 🖥️ MCP 服务器
    • 🔐 环境变量与密钥（STDIO MCP 服务器）
  • 🏷️ MetaMCP 命名空间
  • 🌐 MetaMCP 端点
  • ⚙️ 中间件
  • 🔍 检查器
  • ✏️ 工具覆盖与注解
• 🚀 快速入门
  • 🐳 使用 Docker Compose 运行（推荐）
  • 📦 使用 Dev Containers 构建开发环境（VSCode/Cursor）
  • 💻 本地开发
• 🔌 MCP 协议兼容性
• 🔗 连接到 MetaMCP
  • 📝 例如：通过 mcp.json 连接 Cursor
  • 🖥️ 连接 Claude Desktop 及其他仅支持 STDIO 的客户端
  • 🔧 API 密钥认证故障排除
• ❄️ 冷启动问题与自定义 Dockerfile
• 🧾 日志级别
• 🔐 认证
• 🚦 流量管理
  • 🚧 MCP 速率限制
• 🔗 OpenID Connect (OIDC) 提供商支持
  • 🛠️ 配置
  • 🏢 支持的提供商
  • 🔒 安全特性
  • 📱 使用方法
• ⚙️ 注册控制
  • 🎛️ 可用的控制选项
  • 🏢 企业级应用场景
  • 🛠️ 配置
• 🌐 自定义部署及 Nginx 的 SSE 配置
• 🏗️ 架构
  • 📊 序列图
• 🗺️ 路线图
• 🌐 i18n
• 🤝 贡献
• 📄 许可证
• 🙏 致谢

🎯 使用场景

• 🏷️ 将多个 MCP 服务器分组到命名空间中，以 MetaMCP 的形式托管，并分配公共端点（SSE 或可流式传输的 HTTP），同时进行身份验证。只需单击即可切换端点对应的命名空间。
• 🎯 在重新组合 MCP 服务器时，只选择所需的工具。 还可以围绕可观ability、安全性等应用其他 可插拔中间件（即将推出）。
• 🔍 用作增强型 MCP 检查器，保存服务器配置，并在本地检查 MetaMCP 端点是否正常工作。
• 🔍 用作 MCP 工具选择的 Elasticsearch（即将推出）

总的来说，开发者可以将 MetaMCP 作为 基础设施，通过统一的端点托管动态组合的 MCP 服务器，并在其之上构建智能代理。

快速演示视频：https://youtu.be/Cf6jVd2saAs

📖 概念

🖥️ MCP 服务器

一个 MCP 服务器配置，用于告知 MetaMCP 如何启动 MCP 服务器。

"HackerNews": {
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-hn"]
}

🔐 环境变量与密钥（STDIO MCP 服务器）

对于 STDIO MCP 服务器，MetaMCP 支持三种处理环境变量和密钥的方式：

1. 原始值 - 直接使用字符串值（不建议用于密钥）：

API_KEY=your-actual-api-key-here
DEBUG=true

2. 环境变量引用 - 使用 ${ENV_VAR_NAME} 语法：

API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}

3. 自动匹配 - 如果你的工具中预期的环境变量名称与容器中的环境变量名称一致，则可以完全省略该变量。MetaMCP 会自动传递匹配的环境变量。

🔒 安全提示：环境变量引用（${VAR_NAME}）会在运行时从 MetaMCP 容器的环境中解析。这样可以确保实际的密钥值不会出现在你的配置文件或 Git 仓库中。

⚙️ 开发提示：在本地开发时，使用 pnpm run dev:docker 命令，请确保你的环境变量已在 turbo.json 的 globalEnv 中列出，以便传递给开发进程。这在生产环境的 Docker 部署中则不需要。

🏷️ MetaMCP 命名空间

• 将一个或多个 MCP 服务器分组到一个命名空间中
• 在命名空间级别启用或禁用 MCP 服务器
• 对 MCP 请求和响应应用中间件
• 按命名空间覆盖工具名称、标题和描述，并附加自定义的 MCP 注解（例如 { "annotations": { "readOnlyHint": false } }）

🌐 MetaMCP 端点

• 创建端点并将命名空间分配给端点
• 命名空间中的多个 MCP 服务器将被聚合并作为 MetaMCP 端点暴露出来
• 可选择 API 密钥认证（通过头部或查询参数）或符合 MCP 规范 2025-06-18 的标准 OAuth 认证
• 通过 SSE 或 可流式 HTTP 传输协议托管，同时提供适用于 Open WebUI 等客户端的 OpenAPI 端点

⚙️ 中间件

• 在命名空间级别拦截并转换 MCP 请求和响应
• 内置示例：“过滤非活跃工具”——为 LLM 优化工具上下文
• 未来设想：工具日志记录、错误追踪、验证、扫描等

🔍 检查器

类似于官方的 MCP 检查器，但带有 已保存的服务器配置——MetaMCP 会自动创建配置，使你能够立即调试 MetaMCP 端点。

✏️ 工具覆盖与注解

• 打开命名空间 → “工具”选项卡，查看来自连接的 MCP 服务器的所有工具。
• 每个已保存的工具都可以展开并直接编辑：更新显示的 名称/标题/描述，或提供包含命名空间特定注解的 JSON 数据块（例如 { "annotations": { "readOnlyHint": false } }）。
• 表格中的标签（“已覆盖”、“注解”）会显示哪些工具当前具有自定义元数据。将鼠标悬停在其上即可查看描述覆盖内容的提示信息。
• 注解覆盖会与上游 MCP 服务器返回的内容合并，因此你可以安全地添加自定义 UI 提示，而不会丢失提供商的元数据。

🚀 快速入门

🐳 使用 Docker Compose 运行（推荐）

克隆仓库，准备 .env 文件，然后使用 Docker Compose 启动：

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d

如果你修改了 APP_URL 环境变量，请确保仅通过该 URL 访问，因为 MetaMCP 会对 URL 强制执行 CORS 策略，其他 URL 将无法访问。

请注意，PostgreSQL 数据卷名称可能会与其他 PostgreSQL 容器冲突，由于它是全局的，请考虑在 docker-compose.yml 中重命名：

volumes:
  metamcp_postgres_data:
    driver: local

📦 使用 Dev Containers 构建开发环境（VSCode/Cursor）

你可以使用 VSCode 或 Cursor 的扩展程序，在容器中构建开发环境。

只需确保你的环境中已安装 Docker 或类似工具（需要 docker 和 docker compose 命令），无需在主机上安装其他依赖组件。

1. 首先，克隆 MetaMCP 源代码，并在 Visual Studio Code 中打开项目。

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
code .

2. 切换到 Dev Containers。打开 VSCode 的命令面板，执行 Dev Containers: Reopen in Container。

VSCode 会在一个新窗口中打开 Dev Containers 项目，在建立运行时环境并根据 Dockerfile 安装工具链后，它会开始连接并最终安装 MetaMCP 的依赖项。

注意 此过程需要稳定的网络连接，并会访问 Docker Hub、GitHub 等站点。请确保网络畅通，否则容器构建可能会失败。

等待几分钟，具体时间取决于网络状况和计算机性能，可能需要几分钟到几十分钟不等。你可以点击右下角的进度条查看实时日志，以确认是否有异常卡顿。

完成后，可以运行 pnpm dev 启动开发服务器。

💻 本地开发

仍建议通过 Docker 运行 PostgreSQL，以便于设置：

pnpm install
pnpm dev

🔌 MCP 协议兼容性

• ✅ 工具、资源和提示 均支持
• ✅ 支持 OAuth 的 MCP 服务器 已测试通过 03-26 版本

如有任何问题，欢迎在 GitHub 上提交 Issue 或 PR。

🔗 连接到 MetaMCP

📝 例如，通过 mcp.json 连接 Cursor

示例 mcp.json：

{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
    }
  }
}

🖥️ 连接 Claude Desktop 和其他仅支持 STDIO 的客户端

由于 MetaMCP 端点仅限远程访问（SSE、可流式 HTTP、OpenAPI），因此仅支持 stdio 服务器的客户端（如 Claude Desktop）需要一个本地代理才能连接。

注意： 虽然有时会建议使用 mcp-remote 来实现这一目的，但它专为基于 OAuth 的认证设计，无法与 MetaMCP 的 API 密钥认证配合使用。根据测试结果，推荐使用 mcp-proxy。

以下是使用 mcp-proxy 配置 Claude Desktop 的可行方案：

使用可流式 HTTP

{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

使用 SSE

{
  "mcpServers": {
    "ehn": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

重要提示：

• 将 <YOUR_ENDPOINT_NAME> 替换为你的实际端点名称
• 将 <YOUR_API_KEY_HERE> 替换为你的 MetaMCP API 密钥（格式：sk_mt_...）

有关更多详细信息和替代方法，请参阅 issue #76。

🔧 API 密钥认证故障排除

• 使用 ?api_key= 参数进行的 API 密钥认证不适用于 SSE。它仅适用于可流式 HTTP 和 OpenAPI。
• 最佳实践是将 API 密钥放在 Authorization: Bearer <API_KEY> 头中。
• 当遇到连接问题时，可以暂时禁用认证，以判断是否为认证问题。

❄️ 冷启动问题与自定义 Dockerfile

• MetaMCP 会为每个配置的 MCP 服务器和 MetaMCP 预分配空闲会话。默认情况下，每个会话的空闲时间为 1，这有助于减少冷启动时间。
• 如果你的 MCP 需要除 uvx 或 npx 之外的依赖项，则需要自定义 Dockerfile 来自行安装这些依赖。
• 请查看 invalidation.md，了解更新过程中空闲会话失效的序列图。

🛠️ 解决方案：自定义 Dockerfile 添加依赖项或预安装软件包，以减少冷启动时间。

🧾 日志级别

MetaMCP 的后端会将日志写入文件，并可以选择性地将部分级别的日志镜像到控制台。可以通过 LOG_LEVEL 环境变量来控制控制台的日志镜像。

• 文件

  • app.log：接收 DEBUG、INFO 和 WARN 级别日志
  • error.log：接收 ERROR 级别日志

• 控制台镜像（LOG_LEVEL）

  • all：将 DEBUG、INFO、WARN 和 ERROR 镜像到控制台
  • info：仅将 INFO 镜像到控制台
  • errors-only：将 WARN 和 ERROR 镜像到控制台
  • none：无控制台输出

• 默认值及示例

  • 默认值（未设置或无效时）：errors-only
  • .env 示例：

    LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none'
    

  • docker-compose.dev.yml 中使用：LOG_LEVEL: ${LOG_LEVEL:-all}

🔐 认证

• 🛡️ 前后端更好的认证（TRPC 流程）
• 🍪 会话 Cookie 强制执行安全的内部 MCP 代理连接
• 🔑 API 密钥认证用于通过 Authorization: Bearer <api-key> 头进行的外部访问
• 🪪 MCP OAuth：公开端点提供了在 MCP 规范 2025-06-18 中使用标准 OAuth 的选项，易于集成。
• 🏢 多租户：专为组织在其自有机器上部署而设计。支持私有和公有访问范围。用户可以为自己或所有人创建 MCP、命名空间、端点和 API 密钥。公共 API 密钥无法访问私有 MetaMCP。
• ⚙️ 独立注册控制：管理员可以通过设置页面分别控制 UI 注册和 SSO/OAuth 注册，从而实现灵活的企业部署场景。

🚦 流量管理

🚧 MCP 速率限制

MCP 速率限制功能允许你设置某个 MCP 工具（即端点）在给定时间窗口内可接受的最大请求数量。有两种不同的策略可以单独或组合使用：

• 端点速率限制（Rate Limiting）：同时适用于所有使用该端点的客户端，共享一个统一的计数器。
• 用户速率限制（Client Rate Limiting）：为每个用户设置独立的计数器。

这两种类型可以共存并相互补充，计数器存储在内存中。在集群环境中，每台机器仅能看到并统计其自身的流量。

端点速率限制

端点速率限制作用于端点可同时处理的事务数量。这种类型的限制保护了服务对所有客户的影响。 当连接到某个端点的用户总数超过设定的 rate-limiting 时，MetaMCP 会开始拒绝连接，并返回状态码 503 Service Unavailable。

端点速率限制选项

• 最大速率：定义在任何给定时刻将接受来自所有用户的多少个请求。网关启动时，令牌桶是满的。随着用户请求的到来，令牌桶中的剩余令牌逐渐减少。同时，速率限制会以设定的速率向桶中补充令牌，直到达到最大容量。
• 最大速率秒数：最大速率生效的时间周期，单位为秒。例如，如果你设置最大速率秒数为 60 秒，速率为 5，则表示每 60 秒允许 5 个请求。

用户速率限制

客户端或用户速率限制为每个用户和端点设置一个独立的计数器。当单个用户连接到某个端点的次数超过其 client-max-rate 时，MetaMCP 会开始拒绝连接，并返回状态码 429 Too Many Requests。

用户速率限制选项

• 客户端最大速率：在你希望的时间间隔内（客户端最大速率秒数），为每个用户添加到令牌桶中的令牌数量（用户配额）。桶中剩余的令牌就是该用户可以发出的请求数量。
• 客户端最大速率秒数：最大速率生效的时间周期，单位为秒。例如，如果你设置每 60 秒允许 5 次请求，则表示每 60 秒允许 5 个请求。
• 客户端最大速率策略：设置用于设定客户端计数器的策略。选择 IP 时，限制将应用于客户的 IP 地址；如果存在能够唯一标识用户的头信息，则将其设置为头信息。该头信息必须通过键条目进行定义。
• 客户端最大速率策略键：包含用户身份识别信息的头字段名称（例如，用于令牌的身份验证头，或用于 IP 的 X-Original-Forwarded-For 头）。

🔗 OpenID Connect（OIDC）提供商支持

MetaMCP 支持 OpenID Connect 认证，用于企业 SSO 集成。这使得组织可以使用现有的身份提供商（Auth0、Keycloak、Azure AD 等）进行认证。

🛠️ 配置

将以下环境变量添加到你的 .env 文件中：

# 必需
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration

# 可选自定义
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true

🏢 支持的提供商

MetaMCP 已在多个流行的 OIDC 提供商上进行了测试：

• Auth0: https://your-domain.auth0.com/.well-known/openid-configuration
• Keycloak: https://your-keycloak.com/realms/your-realm/.well-known/openid-configuration
• Azure AD: https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration
• Google: https://accounts.google.com/.well-known/openid-configuration
• Okta: https://your-domain.okta.com/.well-known/openid-configuration

🔒 安全特性

• 🔐 默认启用 PKCE（代码交换证明密钥）
• 🛡️ 使用自动用户创建的 授权码流程
• 🔄 自动发现 OIDC 端点
• 🍪 与现有认证系统无缝集成的会话管理

📱 使用方法

配置完成后，用户将在登录页面看到一个“使用 OIDC 登录”按钮，与邮箱/密码表单并列。首次登录时，认证流程会自动创建新用户。

有关更详细的配置示例和故障排除，请参阅 CONTRIBUTING.md。

⚙️ 注册控制

MetaMCP 为不同的注册方式提供了独立的控制选项，使管理员能够针对企业部署精细调整用户访问策略。

🎛️ 可用控制

• UI 注册：控制用户是否可以通过注册表单创建账户
• SSO 注册：控制用户是否可以通过 SSO/OAuth 提供商（如 OIDC 等）创建账户

🏢 企业用例

这种分离设计可满足常见的企业场景：

• 禁止 UI 注册，允许 SSO：阻止手动注册，同时允许企业 SSO 用户登录
• 禁止 SSO 注册，允许 UI：允许手动注册，同时限制 SSO 访问
• 两者均禁止：完全禁用新用户注册
• 两者均允许：适用于开放部署的默认行为

🛠️ 配置

通过 MetaMCP 管理界面中的“设置”页面来配置这些控制：

1. 导航至“设置”→“认证设置”
2. 切换“禁用 UI 注册”以控制基于表单的注册
3. 切换“禁用 SSO 注册”以控制 OAuth/OIDC 注册

这两个控制相互独立，为您提供完全灵活的注册策略。

🌐 自定义部署及 Nginx 的 SSE 配置

若要将其部署到线上服务或 VPS 上，至少需要 2GB 至 4GB 的内存。内存越大，性能越好。

由于 MCP 利用 SSE 实现长连接，如果您使用 Nginx 等反向代理，请参考示例配置 nginx.conf.example。

🏗️ 架构

• 前端：Next.js
• 后端：Express.js 结合 tRPC，通过 TS SDK 和内部代理托管 MCP 服务器
• 认证：Better Auth
• 结构：采用 Turborepo 和 Docker 发布的独立单体仓库

📊 序列图

注：提示和资源遵循与工具类似的模式。

sequenceDiagram
    participant MCPClient as MCP 客户端（例如 Claude Desktop）
    participant MetaMCP as MetaMCP 服务器
    participant MCPServers as 已安装的 MCP 服务器

    MCPClient ->> MetaMCP: 请求工具列表

    loop 对于每个列出的 MCP 服务器
        MetaMCP ->> MCPServers: 请求 list_tools
        MCPServers ->> MetaMCP: 返回工具列表
    end

    MetaMCP ->> MetaMCP: 汇总工具列表并应用中间件
    MetaMCP ->> MCPClient: 返回汇总后的工具列表

    MCPClient ->> MetaMCP: 调用工具
    MetaMCP ->> MCPServers: 将 call_tool 请求发送到目标 MCP 服务器
    MCPServers ->> MetaMCP: 返回工具响应
    MetaMCP ->> MCPClient: 返回工具响应

🗺️ 路线图

潜在的下一步：

• 🔌 无头管理 API 访问
• 🔍 在 MetaMCP 端点上动态应用搜索规则
• 🛠️ 更多中间件
• 💬 聊天/代理 Playground
• 🧪 测试与评估，优化 MCP 工具选择
• ⚡ 动态生成 MCP 服务器

🌐 i18n

请参阅 README-i18n.md

目前支持英文和中文本地化，欢迎贡献。

🤝 贡献

我们欢迎各类贡献！详情请参阅 CONTRIBUTING.md。

📄 许可证

MIT

如果您在项目中使用了本代码，请注明并附上链接，我们将不胜感激。

🙏 致谢

部分代码灵感来源于：

• MCP Inspector
• MCP 代理服务器

未直接使用相关代码，但借鉴了其中的思想：

• https://github.com/open-webui/openapi-servers
• https://github.com/open-webui/mcpo

MetaMCP 快速上手指南

MetaMCP 是一个 MCP 代理工具，支持将多个 MCP 服务器动态聚合为统一的 MCP 服务，并提供中间件、网关和编排功能。它本身也是一个 MCP 服务器，可无缝接入任意 MCP 客户端（如 Cursor、Claude Desktop 等）。

环境准备

系统要求

• 操作系统：Linux / macOS / Windows (WSL2)
• Docker 及 Docker Compose（推荐方式）
• 或 Node.js 18+ 与 pnpm（本地开发模式）

前置依赖

• Docker 模式：确保已安装并运行 Docker Desktop 或兼容的容器运行时。
• 本地开发模式：
  • 安装 Node.js (v18+)
  • 安装 pnpm：npm install -g pnpm
  • 本地运行 PostgreSQL（或通过 Docker 启动）

💡 国内开发者提示：如遇 Docker Hub 拉取缓慢，可配置国内镜像加速器（如阿里云、腾讯云、网易云等）。Node.js 依赖可使用淘宝镜像：pnpm config set registry https://registry.npmmirror.com。

安装步骤

方式一：使用 Docker Compose（推荐）

这是最简便的部署方式，一键启动包含数据库在内的完整环境。

# 1. 克隆仓库
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp

# 2. 复制环境变量配置文件
cp example.env .env

# 3. 启动服务
docker compose up -d

注意：

• 启动后请通过 .env 中配置的 APP_URL 访问服务，MetaMCP 启用了严格的 CORS 策略。
• 若本地已有名为 postgres 的卷导致冲突，请在 docker-compose.yml 中修改卷名称（例如改为 metamcp_postgres_data）。

方式二：本地开发环境

适合需要修改源码或调试的开发者。

# 1. 安装依赖
pnpm install

# 2. 确保 PostgreSQL 正在运行（推荐使用 Docker 启动 PG）
# docker run --name pg-metamcp -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

# 3. 启动开发服务器
pnpm dev

方式三：使用 Dev Containers (VSCode/Cursor)

如果你使用 VSCode 或 Cursor，可直接在容器中构建开发环境，无需在宿主机安装任何依赖。

1. 克隆代码并用编辑器打开：

   git clone https://github.com/metatool-ai/metamcp.git
   cd metamcp
   code .
   

2. 按下 F1 或 Ctrl+Shift+P，输入并执行命令：Dev Containers: Reopen in Container。
3. 等待容器构建完成（需联网拉取镜像），完成后在终端运行 pnpm dev 即可。

基本使用

1. 访问管理界面

启动成功后，在浏览器打开 http://localhost:3000（具体端口视 .env 配置而定）。

2. 配置 MCP 服务器 (Namespace)

在管理界面中：

• 创建一个 Namespace（命名空间）。
• 添加 MCP Server 配置。例如，添加一个基于 STDIO 的 HackerNews 服务：

  {
    "type": "STDIO",
    "command": "uvx",
    "args": ["mcp-hn"]
  }
  

• 环境变量处理：敏感信息建议使用 ${VAR_NAME} 格式引用宿主环境变量，避免硬编码密钥。

3. 创建对外端点 (Endpoint)

• 在 Namespace 下创建一个 Endpoint。
• 选择传输协议：SSE 或 Streamable HTTP。
• 设置认证方式：API Key 或 OAuth。

4. 连接客户端 (以 Cursor 为例)

在 Cursor 的 mcp.json 配置文件中添加 MetaMCP 的端点信息：

{
  "mcpServers": {
    "my-metamcp": {
      "url": "http://localhost:3000/sse/your-endpoint-id",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

配置完成后，Cursor 即可通过 MetaMCP 聚合后的统一接口调用底层所有 MCP 工具。你还可以在 MetaMCP 界面中对工具进行重命名、添加描述或启用/禁用特定工具，实现灵活的“工具重组”。