🚀 MetaMCP (MCP 聚合器、编排器、中间件、网关于一个 docker 中)

📢 最新更新： 这个 ai-dev 分支将是未来的持续开发分支，其中包含 AI 代理更改。请先测试，再基于此分支构建镜像。感谢社区，已经有很多 PR，但合并和审查它们的工作量也越来越大。我决定加入 AI 更改。至少到目前为止，核心功能是正常的。还有一个社区维护的分支（非常感谢！）：https://github.com/Umbrella-IT-Group/metamcp

📢 更新： [来自作者：对最近的一些维护延迟表示歉意，但至少会继续合并 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

• 🤝 贡献

• 📄 许可证

• 🙏 致谢

Related MCP server: Master MCP Server

🎯 使用场景

• 🏷️ 将 MCP 服务器分组到命名空间中，将其作为元 MCP 托管，并分配公共端点（SSE 或 Streamable HTTP），支持认证。一键为端点切换命名空间。

• 🎯 在重新组合 MCP 服务器时，只挑选你需要的工具。 围绕可观测性、安全性等应用其他可插拔中间件（即将推出）。

• 🔍 用作增强型 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 Spec 2025-06-18 中的标准 OAuth 之间选择

• 通过 MCP 中的 SSE 或 Streamable 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/fanywebfx/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d
# pulls ghcr.io/fanywebfx/metamcp:ai-dev

如果你修改了 APP_URL 环境变量，请确保只从 APP_URL 访问，因为 MetaMCP 会对该 URL 强制执行 CORS 策略，因此其他 URL 均不可访问。

SQLite 数据存储在 Compose 卷（sqlite_data）中。如果它与另一个项目冲突，请在 docker-compose.yml 中重命名该卷。

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

你可以使用 VSCode/Cursor 扩展在容器中构建开发环境。

它只要求你有一个运行 Docker 或类似替代方案的环境（需要 docker/docker compose 命令），并且你的主机上无需安装其他依赖组件。

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

git clone https://github.com/fanywebfx/metamcp.git
cd metamcp
code .

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

你不需要先创建 .env。容器在创建时会复制 example.env 到 .env.local，然后安装依赖并迁移 SQLite 文件。

VSCode 将在新窗口中打开 Dev Containers 项目，它会根据 Dockerfile 构建运行时并安装工具链，然后启动连接，最后安装 MetaMCP 依赖。

注意 此过程需要可靠的网络连接，并且会访问 Docker Hub、GitHub 和其他一些站点。你需要自行确保网络连接，否则容器构建可能会失败。

等待几分钟，具体取决于网络连接或计算机性能，可能需要几分钟到几十分钟。你可以点击右下角的进度条查看实时日志，以便检查是否异常卡住。

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

💻 本地开发

SQLite 会自动创建在 data/metamcp.db（相对于后端工作目录，除非你设置了 DATABASE_URL）。

cp example.env .env.local
pnpm install
cd apps/backend && pnpm db:migrate:dev && cd ../..
pnpm dev

🔌 MCP 协议兼容性

• ✅ 支持工具、资源和提示词

• ✅ 已针对 03-26 版本测试 支持 OAuth 的 MCP 服务器

如果你有任何疑问，请在 GitHub issues 中提出，或直接提交 PR。

🔗 连接到 MetaMCP

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

mcp.json 示例

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

🖥️ 将 Claude Desktop 及其他仅支持 STDIO 的客户端与 MetaMCP 对接

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

注意： 虽然有时会建议使用 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/<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，它只适用于 Streamable 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}

🔐 认证

• 🛡️ Better Auth 用于前端与后端（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 工具（即一个端点）在给定时间窗口内接受的最大请求数。你可以单独或同时使用以下两种策略来设置限制：

• Endpoint rate-limiting (Rate Limiting)：同时作用于通过该端点的所有客户端，共享同一个计数器。

• User rate-limiting (Client Rate Limiting)：为每个用户分别设置计数器。

两种类型可以共存，并互为补充，但计数均保存在内存中。在集群环境中，每台机器只能感知和计算自己分区内的流量。

端点速率限制

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

端点速率限制选项

• Max Rate：定义你在同一时刻共接受来自所有用户的请求数。当网关启动时，令牌桶是满的。当用户请求到达时，桶内剩余令牌减少；同时，速率限制器按照所需速率重新填充令牌桶，直到达到最大容量。

• Max Rate Seconds：最大速率运行的时间窗口（以秒为单位）。例如，如果 Max Rate Seconds 设为 60 秒、rate-limiting 设为 5，则相当于每 60 秒允许 5 个请求。

用户速率限制

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

用户速率限制选项

• Client Max Rate：在指定的时间区间（Client Max Rate Seconds）内，为每个用户添加的令牌数（用户配额）。桶内剩余令牌数即为该用户剩余可发起的请求数。

• Client Max Rate Seconds：最大速率的时间窗口（以秒）。例如，设置 every 为 60 秒且 rate 为 5，则每 60 秒允许 5 个请求。

• Client Max Rate Strategy：选择用于设置客户端计数的策略。当条件限制作用于客户端 IP 地址时设为 ip，或当存在能唯一标识用户的请求头时设为 header，该 header 必须用 key 条目加以定义。

• Client Max Rate Strategy Key：含有用户标识的请求头名称（例如 token 可使用 Authorization，IP 可使用 X-Original-Forwarded-For）。

🔗 OpenID Connect (OIDC) 提供商支持

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

🛠️ 配置

在 .env 文件中添加以下环境变量：

# Required
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

# Optional customization
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（Proof Key for Code Exchange）

• Authorization Code Flow，自动创建用户

• 🔄 自动发现 OIDC 端点

• 🍪 与现有认证系统实现无缝的会话管理

📱 使用方式

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

如需更多配置示例及故障排除，请参阅 CONTRIBUTING.md。

⚙️ 注册控制

MetaMCP 为不同的注册方式提供独立控制，允许管理员根据企业部署需求调整用户访问策略。

🎛️ 可用控制选项

• UI 注册：控制用户是否可以通过注册表单创建账户

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

🏢 企业应用场景

这种分离方式支持常见的企业场景：

• 禁止 UI 注册，允许 SSO：阻止手动注册，同时允许公司内部 SSO 用户

• 禁止 SSO 注册，允许 UI：允许手动注册，但限制 SSO 访问

• 同时禁止两者：完全关闭新用户注册

• 两者均允许：适合开放部署的默认行为

🛠️ 配置

在 MetaMCP 管理界面中访问 Settings 页面即可配置这些控制项：

1. 进入 Settings → Authentication Settings

2. 切换 “Disable UI Registration” 以控制基于表单的注册

3. 切换 “Disable SSO Registration” 以控制 OAuth/OIDC 注册

两个控制项彼此独立，让你在制定注册策略时拥有完全的自由度。

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

若要部署到在线服务或 VPS，建议实例至少具有 2GB–4GB 内存。内存越大，性能越好。

由于 MCP 的 SSE 依赖长连接，如果使用 nginx 等反向代理，请参考 config 示例 nginx.conf.example。

🏗️ 架构

• 前端：Next.js

• 后端：Express.js 与 tRPC，通过 TS SDK 与内部代理托管 MCP

• 认证：Better Auth

• 结构：独立的 monorepo 项目，使用 Turborepo 与 Docker 发布

📊 时序图

注意：提示词与资源的使用模式与工具类似。

sequenceDiagram
    participant MCPClient as MCP Client (e.g., Claude Desktop)
    participant MetaMCP as MetaMCP Server
    participant MCPServers as Installed MCP Servers

    MCPClient ->> MetaMCP: Request list tools

    loop For each listed MCP Server
        MetaMCP ->> MCPServers: Request list_tools
        MCPServers ->> MetaMCP: Return list of tools
    end

    MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
    MetaMCP ->> MCPClient: Return aggregated list of tools

    MCPClient ->> MetaMCP: Call tool
    MetaMCP ->> MCPServers: call_tool to target MCP Server
    MCPServers ->> MetaMCP: Return tool response
    MetaMCP ->> MCPClient: Return tool response

🗺️ 路线图

可能的下一步：

• 🔌 Headless 管理 API 访问

• 🔍 在 MetaMCP 端点上动态应用搜索规则

• 🛠️ 增加更多中间件

• 💬 聊天/Agent Playground

• 🧪 为 MCP 工具的选择优化提供测试与评估

• ⚡ 动态生成 MCP 服务器

🌐 国际化（i18n）

参见 README-i18n.md

目前支持 en 和 zh 两个 locale，欢迎提供翻译贡献。

🤝 欢迎贡献

欢迎你的贡献！详细信息见 CONTRIBUTING.md

📄 许可证

MIT

如果你的项目使用了本代码，希望你能附上指向本项目的 backlink。

🙏 致谢

部分代码灵感来自：

• MCP Inspector

• MCP Proxy Server

另外还参考了（未直接使用代码，但借鉴了思路）：

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

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