mcp-manager-gateway

技能简介

mcp-manager-gateway 是一款面向团队和企业场景的 MCP（Model Context Protocol）管理网关，通过 Python 实现，提供多用户 MCP 服务的统一管理、Token 授权、工具目录缓存及按会话复用的懒加载运行时。在 AI Agent 技术栈中，MCP 协议正在迅速成为 AI 模型调用外部工具的标准方式——Anthropic、OpenAI、Google 等主流厂商均已支持或计划支持 MCP。然而，在团队使用场景中，MCP 服务的部署和管理面临一系列现实挑战：如何统一管理多个 MCP 服务的启停？如何为不同用户或 Agent 分配不同的 MCP 访问权限？如何避免每次工具调用都重新初始化 MCP 实例以提升响应速度？如何让不支持 MCP 的 Agent（如某些旧版模型或自定义 Agent）也能调用 MCP 工具？mcp-manager-gateway 正是为解决这些挑战而设计的，它提供独立的 Web 管理界面和标准化 REST / MCP 双协议网关，团队管理员可通过可视化界面集中配置所有 MCP 服务、分配用户权限、创建访问令牌，普通开发者或 Agent 则通过统一网关按需调用，无需关心后端 MCP 服务的生命周期管理。该网关以 Python + uv 工具为核心，依赖极简，部署便捷，默认启动于本地 8765 端口，自带 SQLite 数据库存储配置和日志。

核心能力

• 多用户 MCP 统一管理平台：提供独立的 Web 管理后台，支持管理员创建团队成员账号、为不同成员分配不同的 MCP 服务访问权限，实现 MCP 服务的团队级集中管控，而非在每个开发者的本地配置文件中散落管理。
• Token 授权体系：基于 Bearer Token 的认证机制，管理员可为不同用途（开发、测试、生产）创建独立 Token，普通用户仅能在被授权的范围内使用 MCP 服务，Token 值加密存储并支持复制和轮换。
• 工具目录懒加载缓存：系统自动为已启用的 MCP 服务发现并缓存其提供的全部工具目录（tools/list），按服务名称和授权用户独立存储。工具目录在首次查询时按需生成，之后直接返回缓存结果，避免每次调用都触发 MCP 服务启动和工具发现，显著降低响应延迟。
• 按会话复用的 MCP 实例管理：同一 MCP 服务在短时间内的多次调用复用一个运行时实例，而非每次调用都启动新进程，减少资源消耗的同时提升高频调用场景下的性能表现。
• MCP 协议网关（Streamable HTTP）：提供标准 MCP Streamable HTTP 端点（POST/GET/DELETE /mcp），使不支持本地 MCP stdio 模式的 Agent 或外部系统也能通过 HTTP 调用 MCP 工具，打破 MCP 调用的客户端限制。
• 多 MCP 服务批量导入与管理：支持通过 JSON、Codex TOML、Claude 配置格式批量导入 MCP 服务定义，支持诊断、去重、冲突处理和脱敏导出，大幅降低团队迁移和批量配置的运维成本。
• OAuth MCP 服务隔离：对于需要 OAuth 认证的外部 MCP 服务，系统支持按用户隔离授权状态，每个用户独立完成 OAuth 流程，服务配置互不干扰，适合团队共用部分服务但各成员需独立授权的场景。

安装配置

前置条件：Python 3.10+，推荐使用 uv 包管理器。

方式一：PyPI 一键安装（推荐）

uv tool install mcp-manager-gateway
# 安装后提供三个等价命令：mmg、mcp-manager、mcp-manager-gateway
mcp-manager serve

方式二：源码构建安装

# 克隆仓库
git clone https://github.com/zycmeanm/mcp-manager.git
cd mcp-manager
# 使用 uv 构建并安装
uv build
uv tool install ./dist/mcp_manager_gateway-*.whl

启动与初始化

# 默认端口启动
mcp-manager serve
# 自定义端口
mcp-manager serve --port 8766

# 首次启动会自动创建：
# - Windows: C:Users.mcp-manager
# - Linux/macOS: ~/.mcp-manager
# 包含 .env 配置文件、SQLite 数据库和日志文件

环境变量配置（可选）

首次启动后，配置文件位于 ~/.mcp-manager/.env，常用配置项：

PORT=8765                    # Web 服务端口
HOST=127.0.0.1              # 监听地址（远程访问设为 0.0.0.0）
PUBLIC_URL=https://你的域名  # OAuth 回调地址
COOKIE_SECURE=true          # HTTPS 场景下设为 true
MCP_MANAGER_HOME=/自定义目录  # 自定义数据目录

使用步骤

1. 管理员初始化：首次启动后，打开 http://127.0.0.1:8765 ，使用管理员注册页面创建首个账户（默认管理员角色），密码长度至少 10 个字符。

2. 添加 MCP 服务：以管理员身份登录管理后台，点击"MCP 服务" → "添加服务"，填写服务名称、类型（stdio / Streamable HTTP / REST 转 MCP）、服务地址及认证信息。系统将自动探测服务能力并缓存工具目录。

3. 配置 OAuth（可选）：若添加的 MCP 服务需要 OAuth 认证（如 GitHub API、MCP 等），在服务配置中填写 OAuth 相关参数，每个用户后续独立完成各自的授权流程。

4. 分配服务给用户：在"用户管理"中为普通用户分配可用的 MCP 服务范围，普通用户登录后只能看到已被授权的服务。

5. 创建访问令牌：用户进入"访问令牌"页面，创建专属 Token（Bearer Token），Token 值加密保存，可复制使用。

6. 通过网关调用 MCP 工具：在代码或 Agent 中向网关的统一端点发送请求：

   POST /mcp
   Authorization: Bearer mcpm_
   Content-Type: application/json
   
   {"method": "tools/call", "params": {"name": "gateway_search_mcps", "arguments": {"query": "*"}}}

   系统自动路由到对应 MCP 服务并返回结果。

适用场景

• 团队 MCP 资产管理：当团队需要管理多个 MCP 服务（数据库访问、API 调用、文件处理等）时，通过统一后台集中配置，避免每个成员在本地重复配置和管理，降低协作成本。
• AI Agent MCP 接入：企业自研或第三方 AI Agent 若不支持本地 MCP stdio 模式，可通过 mcp-manager-gateway 的 HTTP 网关接入所有已注册的 MCP 服务，扩展 Agent 工具集。
• 多租户 MCP 隔离：在面向不同客户提供 AI 服务的多租户场景中，通过 Token 隔离不同租户的 MCP 访问权限，实现 MCP 服务的安全共享。
• 高频 MCP 调用优化：通过懒加载缓存和实例复用，高频调用同一 MCP 工具时无需重复启动进程，适合生产环境中 Agent 对 MCP 工具的持续调用。
• MCP 服务测试与诊断：管理员可在管理后台对单个 MCP 服务执行工具测试（使用保存的测试参数用例），验证服务配置正确性和工具响应是否符合预期。

适用人群

• 使用多个 MCP 服务构建 AI 应用的企业团队
• 需要为 AI Agent 扩展 MCP 工具调用能力的开发者
• 在多租户场景下提供 AI 服务的产品和平台团队
• 负责 AI 技术选型和架构的企业技术负责人
• 研究 MCP 协议生态、希望集中管理 MCP 资产的个人开发者

工作原理

mcp-manager-gateway 的核心架构分为三层：

管理层（Web 管理后台）：基于 Python + SQLite 的 Web 应用，提供用户管理、MCP 服务配置、Token 生命周期管理和诊断工具。管理员的所有操作实时写入 SQLite 数据库，影响网关层的路由行为。

网关层（MCP / REST 双协议）：系统提供两个访问入口——MCP Streamable HTTP 端点（/mcp）和 REST 风格的工具管理 API。外部 Agent 或客户端通过 HTTP 携带 Bearer Token 发起请求，网关层验证 Token 权限后，从数据库读取该 Token 对应的已授权 MCP 服务列表。

运行时层（懒加载 MCP 实例池）：当工具调用请求到达时，网关根据请求中的服务标识（gateway_name）从缓存中查找对应 MCP 服务的工具目录（已缓存则直接返回；若服务处于 lazy 模式且无运行中实例，则启动新实例、执行工具发现后缓存结果，再将实例保留在内存中一段时间供后续复用）。实例按授权用户隔离，OAuth 状态也按用户独立管理。

缓存策略：工具目录缓存按"服务+用户"组合存储，失败状态统一记录在 cache/catalog.jsonl，日志按日期写入 JSONL 文件，系统数据库和用户目录完全自包含，升级时通过追加写入方式平滑迁移旧版本数据。