MCP-Router: 模型上下文协议路由系统#

项目初衷#

在使用多个 MCP（Model Context Protocol）服务器时，我发现了一个常见问题：当不同的 MCP 服务器提供同名工具时，LLM 无法有效区分它们，导致工具调用混乱。此外，管理多个 MCP 服务器的配置和连接也变得复杂。

MCP Router 的诞生就是为了解决这些问题：

• 工具命名冲突：通过实例名称前缀区分同名工具
• 配置管理复杂性：提供统一的配置管理和热加载
• 连接管理：支持多种传输协议，适应不同使用场景
• 动态扩展：允许运行时添加、删除和管理 MCP 实例

这个项目旨在为 MCP 生态系统提供一个强大而灵活的路由层，让开发者能够更轻松地构建复杂的 AI 应用。

简介#

MCP Router 是一个模型上下文协议（MCP）路由/代理系统，作为MCP服务端和客户端，支持动态管理MCP工具配置，解决LLM无法区分同名工具的问题。

TIP

适用于需要管理多个MCP服务器的场景，支持多种传输协议

特性#

• 动态路由: 文件系统路由，使用 mcp_settings.json 配置
• 快速启动: 后台加载客户端，启动时间<0.1秒
• 热加载: 自动检测配置变化并重新加载
• 多传输支持: Stdio、SSE、HTTP 传输协议
• 实时日志: WebSocket实时日志流（可选）
• 权限控制: 可配置的LLM实例管理权限
• 智能端口: 端口占用时自动查找可用端口
• 安全认证: Bearer Token认证，输入验证
• REST API: 完整的HTTP API用于配置管理

安装#

1
pip install mcp-router

1
# 使用 uv (推荐)
2
uv venv .venv
3
uv pip install -e ".[dev]"
4

5
# 或使用 pip
6
python -m venv .venv
7
.venv\Scripts\activate  # Windows
8
source .venv/bin/activate  # Linux/Mac
9
pip install -e ".[dev]"

配置#

编辑 config.json 文件：

1
{
2
  "api": {
3
    "enabled": false,
4
    "port": 8001,
5
    "host": "0.0.0.0"
6
  },
7
  "server": {
8
    "host": "0.0.0.0",
9
    "http": { "enabled": true, "port": 3000 },
10
    "sse": { "enabled": true, "port": 3001 }
11
  },
12
  "security": {
13
    "bearer_token": "",
14
    "enable_validation": true
15
  },
16
  "logging": {
17
    "level": "INFO",
18
    "directory": "logs"
19
  }
20
}

添加MCP配置#

在 data/{provider}/mcp_settings.json 中添加MCP服务器配置：

1
{
2
  "provider": "example",
3
  "isActive": true,
4
  "name": "example_instance",
5
  "type": "stdio",
6
  "command": "python",
7
  "args": ["-m", "example_mcp"],
8
  "env": {}
9
}

运行#

1
# 直接指定传输模式
2
python main.py              # Stdio模式（默认）
3
python main.py stdio        # Stdio模式
4
python main.py http         # HTTP模式
5
python main.py sse          # SSE模式
6
python main.py api          # API服务器模式
7

8
# 查看帮助
9
python main.py help

MCP 工具#

MCP Router 提供以下工具给 LLM 使用：

基础工具 (总是可用):

• mcp.router.list() - 列出所有已注册的MCP客户端实例
• mcp.router.help() - 返回所有实例的工具列表和使用说明
• mcp.router.use(instance_name) - 使用指定的MCP实例
• mcp.router.call(instance_name, tool_name, **kwargs) - 调用指定实例的指定工具

管理工具 (需启用 allow_instance_management):

• mcp.router.add(provider_name, config) - 动态添加新的MCP配置
• mcp.router.remove(instance_name) - 移除MCP配置
• mcp.router.enable(instance_name) - 启用MCP实例
• mcp.router.disable(instance_name) - 禁用MCP实例

与 LLM 集成#

1
{
2
  "mcpServers": {
3
    "mcp_router": {
4
      "command": "uv",
5
      "args": [
6
        "--directory",
7
        "C:/path/to/mcp_router",
8
        "run",
9
        "python",
10
        "main.py"
11
      ],
12
      "transport": "stdio"
13
    }
14
  }
15
}

1
{
2
  "mcpServers": {
3
    "mcp_router_http": {
4
      "url": "http://localhost:3000/mcp",
5
      "transport": "streamableHttp"
6
    }
7
  }
8
}

1
{
2
  "mcpServers": {
3
    "mcp_router_sse": {
4
      "url": "http://localhost:3001/sse",
5
      "transport": "sse"
6
    }
7
  }
8
}

REST API 端点#

当 API 模式启用时，可通过以下端点管理 MCP Router：

实例管理:

• GET /api/instances - 列出所有实例
• GET /api/instances/{name} - 获取实例详情
• POST /api/instances - 添加新实例
• PATCH /api/instances/{name} - 更新实例配置
• DELETE /api/instances/{name} - 删除实例
• POST /api/instances/{name}/enable - 启用实例
• POST /api/instances/{name}/disable - 禁用实例

工具管理:

• GET /api/tools - 列出所有工具
• GET /api/tools/{instance_name} - 获取实例的工具列表
• POST /api/call - 调用工具

项目结构#

1
mcp_router/
2
├── main.py                 # 项目入口
3
├── config.json            # 全局配置文件
4
├── requirements.txt       # 依赖文件
5
├── pyproject.toml         # uv项目配置
6
│
7
├── src/
8
│   ├── core/              # 核心模块
9
│   │   ├── logger.py      # 日志系统
10
│   │   ├── config.py      # 配置管理器
11
│   │   └── exceptions.py  # 自定义异常
12
│   │
13
│   ├── mcp/               # MCP模块
14
│   │   ├── client.py      # MCP客户端管理
15
│   │   ├── server.py      # MCP服务端
16
│   │   ├── router.py      # 路由核心逻辑
17
│   │   └── transport.py   # 传输层
18
│   │
19
│   ├── api/               # API模块
20
│   │   ├── app.py         # FastAPI应用
21
│   │   └── routes.py      # API路由处理
22
│   │
23
│   └── utils/             # 工具模块
24
│       ├── validator.py   # 输入验证
25
│       ├── watcher.py     # 文件监视器
26
│       └── security.py    # 安全工具
27
│
28
├── data/                  # MCP配置目录
29
│   ├── example/
30
│   │   └── mcp_settings.json
31
│   └── ...
32
│
33
└── test/                  # 测试文件
34
    ├── test_router.py
35
    ├── test_api.py
36
    └── test_security.py

开发#

1
# 格式化代码
2
ruff format .
3

4
# 检查代码
5
ruff check .
6

7
# 自动修复
8
ruff check --fix .

1
# 运行所有测试
2
pytest
3

4
# 运行特定测试
5
pytest test/test_router.py
6

7
# 带覆盖率
8
pytest --cov=src --cov-report=html

安全性#

• 输入验证: 防止SQL注入、XSS攻击、路径遍历
• Bearer Token: 可选的API认证
• CORS配置: 灵活的跨域请求控制
• 文件大小限制: 防止DOS攻击
• HTTP安全头: X-Frame-Options, CSP, HSTS等