MCP Aggregator

MCP 聚合器

一个 MCP（Model Context Protocol）聚合器，可将多个 MCP 服务整合到一个界面中。代码大多由 AI 生成。

为什么要将多个 MCP 服务整合到一起？

开发此应用的主要原因是绕过 Cursor 一次只能使用 2 个 MCP 服务的限制。就我的情况而言，无论添加哪一个，第 3 个 MCP 服务都会导致另外两个中的某一个无法使用。

概览

MCP 聚合器充当 Cursor（或任何其他 MCP 客户端）与多个 MCP 服务之间的桥梁。它既是 MCP 服务（与 Cursor 通信时），也是 MCP 客户端（与后端 MCP 服务通信时）。

主要功能：

• 为 Cursor 和其他 MCP 客户端提供 stdio 接口
• 连接多个后端 MCP 服务
• 为后端服务的方法添加前缀（例如，将来自名为 "shortcut" 的 MCP 的 "search_stories" 方法处理为 "shortcut_search_stories"）
• 自动将工具名称中的连字符替换为下划线，以兼容 Cursor
• 可通过环境变量和 JSON 配置文件进行配置
• 支持配置日志级别的调试日志

安装

使用安装脚本（推荐）

你可以使用我们的安装脚本安装最新版本的 combine-mcp：

# Download and run the installation script
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash

# Or install a specific version
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash -s -- -v v1.0.0

脚本将：

• 检测你的操作系统和架构
• 下载相应的预编译二进制文件
• 验证校验和
• 将其安装到 PATH 中合适的位置
• 添加可执行权限

使用 go install（备选方式）

# Install directly from GitHub (binary will be placed in $GOPATH/bin)
go install github.com/nazar256/combine-mcp/cmd/combine-mcp@latest

# Ensure $GOPATH/bin is in your PATH
# For example, add this to your .bashrc or .zshrc:
# export PATH=$PATH:$(go env GOPATH)/bin

使用 Docker（备选方式）

无需在本地安装，即可直接使用 Docker 运行 combine-mcp：

# Run the latest version
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/combine-mcp:latest

# Run a specific version
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/combine-mcp:v1.0.0

# Set environment variables
docker run --rm -v ~/.config/mcp:/config -e MCP_CONFIG=/config/config.json -e MCP_LOG_LEVEL=debug ghcr.io/nazar256/combine-mcp:latest

要在 Cursor 中使用它，你需要将 MCP 服务配置为使用 Docker：

{
  "mcpServers": {
    "aggregator": {
      "command": "docker",
      "args": ["run", "--rm", "-v", "~/.config/mcp:/config", "ghcr.io/nazar256/combine-mcp:latest"],
      "env": {
        "MCP_CONFIG": "/config/config.json"
      }
    }
  }
}

使用 Makefile

项目包含用于执行常见任务的 Makefile：

# Build the binary
make build

# Run tests
make test

# Clean up build artifacts
make clean

用法

配置聚合器

基本上，你可以将现有的 Cursor MCP 配置复制到任意位置，例如 ~/.config/mcp/config.json。配置内容应如下所示：

Cursor 用户还可以使用一个实用功能：筛选 MCP 服务中的工具。你可以管理工具，避免超过 Cursor 的 40 个工具上限，也可以隐藏你不希望 Cursor 使用的工具。

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": ["-y", "@shortcut/mcp"],
      "env": {
        "SHORTCUT_API_TOKEN": "your-shortcut-api-token-here"
      },
      "tools": {
        "allowed": ["search-stories", "get-story", "create-story"]
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"  
      }
    }
  }
}

在 Cursor 中配置聚合器

现在，你可以在 Cursor 配置中只保留一个 MCP 服务：聚合器。配置可能如下所示（假设你已将 combine-mcp 二进制文件安装到 PATH 中，并且有 ~/.config/mcp/config.json 文件）：

{
  "mcpServers": {
    "aggregator": {
      "command": "combine-mcp",
      "env": {
        "MCP_CONFIG": "~/.config/mcp/config.json"
      }
    }
  }
}

环境变量

• MCP_CONFIG：配置文件的路径（必需）
• MCP_LOG_LEVEL：日志级别（error、info、debug、trace）——默认值：info
• MCP_LOG_FILE：日志文件的路径
• MCP_PROTOCOL_VERSION：强制指定协议版本以确保兼容性
• MCP_CURSOR_MODE：启用针对 Cursor 的兼容性调整

使用场景

为多个客户端统一 MCP 配置

一个实用场景是维护一个供不同 MCP 客户端共用的单一 MCP 配置文件（例如 Cursor、Windsurf、Gemini-CLI、Codex、Claude Code、GitHub Copilot agents 等）。

你无需为每个客户端单独配置 MCP 服务列表并重复填写密钥，而是可以：

• 在聚合器配置中一次性配置所有后端 MCP 服务及其密钥。
• 让每个客户端都使用同一个 combine-mcp 二进制文件和同一个 MCP_CONFIG 文件。
• 由聚合器为每个客户端处理工具的前缀添加、筛选和规范化。

这样做有以下好处：

• 对可用的 MCP 服务和工具采用单一事实来源。
• 集中管理密钥——API 令牌和其他凭据仅保存在聚合器配置中。
• 在不同 IDE 和 Agent 之间实现一致的行为，无需针对每个客户端重新配置 MCP。
• 隔离密钥——无需将密钥直接共享给 AI Agent 工具。

工具名称规范化

MCP Aggregator 会自动将工具名称中的连字符替换为下划线。这是必要的，因为 Cursor 存在一个已知问题，无法正确检测或使用名称中带有连字符的工具。

例如：

• 原始工具名称：get-user
• 规范化后的工具名称：get_user
• 带前缀的工具名称（适用于 shortcut 服务）：shortcut_get_user

规范化过程是透明的——使用规范化后的名称调用工具时，聚合器会在将请求转发到后端服务前，将名称映射回原始名称。

工具筛选

MCP Aggregator 支持按服务进行可选的工具筛选。以下情况适合使用此功能：

• 限制公开的工具数量，使其不超过 Cursor 的工具上限（最多 40 个工具）
• 仅公开各个服务中的特定工具
• 避免不同服务之间的工具名称冲突
• 减少需要处理的工具数量，从而提升性能

要启用工具筛选，请在服务配置中添加一个 tools 对象，并使用 allowed 数组列出要公开的工具：

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": ["-y", "@shortcut/mcp"],
      "env": {
        "SHORTCUT_API_TOKEN": "your-shortcut-api-token-here"
      },
      "tools": {
        "allowed": [
          "search-stories",
          "get-story",
          "create-story",
          "assign-current-user-as-owner"
        ]
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"
      },
      "tools": {
        "allowed": [
          "create-pr",
          "list-prs",
          "get-pr",
          "merge-pr"
        ]
      }
    }
  }
}