MCP Unify

mcp统一

  

在单个端点后统一多个MCP服务器。延迟加载、自动清理、Python插件、基于角色的过滤。

问题

如果你使用Claude Code或任何带有3台以上服务器的MCP客户端，你会得到：

• 多个子流程（每个约50MB）
• 配置重复
• 无集中控制
• 没有完整的MCP服务器，无法添加自定义Python工具

解决方案

mcp-unify 跑 一个过程 按需代理N台MCP服务器：

Claude Code / MCP Client
  │
  ▼
mcp-unify (1 process)
  ├─ [plugin] Python @tool functions     ← in-process, 0 overhead
  ├─ [lazy]   filesystem-server          ← subprocess spawned on first call
  ├─ [lazy]   github-server              ← subprocess spawned on first call
  └─ [lazy]   playwright                 ← subprocess spawned on first call
      ↑
      5 min idle → auto-kill

安装

pip install mcp-unify

快速开始

1.创建 gateway.yaml

servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    enabled: false

idle_timeout: 300

2.跑步

标准 （适用于克劳德代码）：

mcp-unify stdio --config gateway.yaml

上海证券交易所 （对于远程客户端）：

mcp-unify serve --config gateway.yaml --port 8765

3.添加到克劳德代码

{
  "mcpServers": {
    "gateway": {
      "command": "mcp-unify",
      "args": ["stdio", "--config", "/path/to/gateway.yaml"]
    }
  }
}

Python插件

添加零样板的自定义工具：

from mcp_gateway import tool

@tool(description="Add two numbers")
def add(a: float, b: float) -> float:
    return a + b

配置中的参考：

plugins:
  - module: my_tools.calculator

或者以编程方式注册：

from mcp_gateway import MCPGateway

gw = MCPGateway()
gw.register_tool(add)
await gw.serve_stdio()

同步功能通过运行 asyncio.to_thread().Async函数本机运行。模式是根据类型提示自动生成的。

基于角色的筛选

控制每个客户端看到的工具：

roles:
  admin: null        # all tools
  readonly: ["filesystem_*", "gateway_status"]
  developer: ["github_*", "filesystem_*", "gateway_*"]

通过环境变量设置角色：

MCP_GATEWAY_ROLE=readonly mcp-unify stdio

使用球形图案-- filesystem_* 匹配文件系统服务器中的所有工具。

运作原理

1. 懒加载：在调用工具之前，服务器不会启动。每台服务器获得一个 __connect 占位符工具。调用它会生成子流程，并通过以下方式发现真正的工具模式 session.list_tools().

1. 自动清理：后台任务每60秒检查一次，并杀死空闲时间超过60秒的服务器子进程 idle_timeout （默认值：5分钟）。

1. 真实图式：工具模式是通过MCP SDK从实际服务器中发现的，而不是硬编码的。你总是很准确 inputSchema.

1. 插件工具：Python函数装饰有 @tool 在网关进程中运行。类型提示被内省以自动生成JSON模式。

API

from mcp_gateway import MCPGateway, tool

# From YAML
gw = MCPGateway.from_config("gateway.yaml")

# Programmatic
gw = MCPGateway()
gw.register_tool(my_function, name="my_tool", description="...")

# Serve
await gw.serve_stdio()    # stdio mode
await gw.serve_sse()      # SSE mode on :8765

# Context manager
async with MCPGateway() as gw:
    await gw.serve_stdio()

命令行界面

mcp-unify serve [--config FILE] [--host HOST] [--port PORT]
mcp-unify stdio [--config FILE]
mcp-unify list  [--config FILE]

配置发现： --config > ./gateway.yaml > ./mcp-unify.yaml

需求

• Python>=3.10
• mcp >= 1.0.0
• starlette >= 0.27.0
• uvicorn >= 0.23.0
• pyyaml >= 6.0

许可证

麻省理工学院