🚀 MetaMCP (MCP Aggregator, Orchestrator, Middleware, Gateway in one docker)

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

MetaMCP 是一款 MCP 代理，可让您动态聚合多个 MCP 服务器为一个统一的 MCP 服务器，并应用 middlewares。MetaMCP 本身就是一个 MCP 服务器，因此可以轻松接入任何 MCP 客户端。

---

有关更多详情，请访问我们的文档网站：[***]

英文 | 中文

📋 目录

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

🎯 用例

• 🏷️ 将 MCP 服务器分组到命名空间，作为元 MCP 托管，并分配公共端点（SSE 或可流式 HTTP），支持身份验证。一键为端点切换命名空间。
• 🎯 在重新组合 MCP 服务器时选择所需工具。 应用其他围绕可观测性、安全性等的可插拔中间件（即将推出）。
• 🔍 用作增强型 MCP 检查器，带有保存的服务器配置，可在内部检查 MetaMCP 端点是否正常工作。
• 🔍 用作 MCP 工具选择的 Elasticsearch（即将推出）

通常，开发人员可以将 MetaMCP 用作基础设施，通过统一端点托管动态组合的 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 请求和响应应用 middlewares
• 按命名空间覆盖工具名称/标题/描述，并附加自定义 MCP 注解（例如 { "annotations": { "readOnlyHint": false } }）

🌐 MetaMCP 端点

• 创建端点并为端点分配命名空间
• 命名空间中的多个 MCP 服务器将被聚合并作为 MetaMCP 端点发布
• 可选择 API-Key 身份验证（在请求头或查询参数中）或 MCP 规范 2025-06-18 中的标准 OAuth
• 通过 MCP 中的SSE或可流式 HTTP传输以及OpenAPI端点托管，供 https://github.com/open-webui/open-webui 等客户端使用

⚙️ 中间件（Middleware）

• 在命名空间级别拦截并转换 MCP 请求和响应
• 内置示例："Filter inactive tools"（过滤非活动工具）- 优化 LLM 的工具上下文
• 未来计划：工具日志记录、错误跟踪、验证、扫描

🔍 检查器（Inspector）

与官方 MCP 检查器类似，但具有保存的服务器配置——MetaMCP 会自动创建配置，以便您立即调试 MetaMCP 端点。

✏️ 工具覆盖与注解（Tool Overrides & Annotations）

• 打开命名空间 → 工具（Tools） 选项卡，查看来自已连接 MCP 服务器的所有工具。
• 每个已保存的工具都可以展开并内联编辑：更新显示名称/标题/描述，或提供包含命名空间特定注解的 JSON 数据（例如 { "annotations": { "readOnlyHint": false } }）。
• 表格中的徽章（"Overridden"、"Annotations"）显示当前哪些工具具有自定义元数据。悬停查看描述覆盖内容的工具提示。
• 注解覆盖会与上游 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 环境变量，请确保仅通过 APP_URL 访问，因为 MetaMCP 会对该 URL 强制执行 CORS 策略，因此其他 URL 无法访问。

[!NOTE] pg 卷名称可能会与您其他的 pg docker 容器冲突（因为卷是全局的），建议在 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 依赖。

[!NOTE] 此过程需要稳定的网络连接，会访问 Docker Hub、GitHub 及其他一些站点。您需要自行确保网络连接正常，否则容器构建可能失败。

等待几分钟，根据网络连接或计算机性能，此过程可能需要几分钟到几十分钟，您可以点击右下角的进度条查看实时日志，以检查是否出现异常卡住。

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

💻 本地开发

仍建议通过 docker 运行 postgres 以简化设置：

pnpm install
pnpm dev

🔌 MCP 协议兼容性

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

如有疑问，欢迎提交 GitHub issues 或 PRs。

🔗 连接到 MetaMCP

📝 示例：通过 mcp.json 连接 Cursor

示例 mcp.json

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

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

由于 MetaMCP 端点仅支持远程访问（SSE、Streamable HTTP、OpenAPI），仅支持 stdio 服务器的客户端（如 Claude Desktop）需要通过本地代理连接。

[!NOTE] 虽然有时会建议使用 mcp-remote 实现此目的，但它专为基于 OAuth 的认证设计，不支持 MetaMCP 的 API 密钥认证。经测试 mcp-proxy 是推荐的解决方案。

以下是使用 mcp-proxy 连接 Claude Desktop 的有效配置：

使用 Streamable HTTP

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

使用 SSE

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

[!IMPORTANT]

• 将 替换为实际的端点名称
• 将 替换为您的 MetaMCP API 密钥（格式：sk_mt_...）

有关更多详细信息和替代方法，请参见 https://github.com/metatool-ai/metamcp/issues/76#issuecomment-3046707532%E3%80%82

🔧 API 密钥认证故障排除

• ?api_key= 参数式 API 密钥认证不适用于 SSE。仅适用于 Streamable HTTP 和 OpenAPI。
• 最佳实践是在 Authorization: Bearer 头中使用 API 密钥。
• 遇到连接问题时，尝试暂时禁用认证以确认是否为认证问题。

❄️ 冷启动问题与自定义 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 头进行外部访问
• 🪪 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。

🔗 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 桌面版）
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: 向目标 MCP 服务器调用 call_tool
MCPServers ->> MetaMCP: 返回工具响应
MetaMCP ->> MCPClient: 返回工具响应

🗺️ 路线图

潜在后续步骤：

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

🌐 国际化（i18n）

参见 README-i18n.md

目前支持 en（英文）和 zh（中文）语言环境，欢迎贡献。

🤝 贡献指南

我们欢迎贡献！详情参见 CONTRIBUTING.md

📄 许可证

MIT

如果您的项目使用了本代码，欢迎提及并添加反向链接。

🙏 致谢

部分代码灵感来源于：

• https://github.com/modelcontextprotocol/inspector
• https://github.com/adamwattis/mcp-proxy-server

未直接使用代码，但借鉴了以下项目的思路：

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