MCP聚合器

MCP（模型上下文协议）聚合器允许您将多个MCP服务器合并到一个接口中。代码主要是由AI生成的。

为什么将MCP服务器合并为一个？

此应用程序的主要原因是解决Cursor仅能同时使用两个MCP服务器的限制。在我添加第三个MCP服务器时，无论哪种情况，都会破坏其他两个服务器之一的使用能力。

概览

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

关键特性：

• 为Cursor和其他MCP客户端提供标准输入输出接口
• 连接到多个后端MCP服务器
• 在后端服务器的方法前加上前缀（例如，“shortcut_search_stories”用于“search_stories”方法来自“shortcut”MCP）
• 自动清理工具名称以适应Cursor，通过将连字符替换为下划线
• 可通过环境变量和JSON配置文件进行配置
• 具有可配置级别的调试日志记录

安装

使用安装脚本（推荐）

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

# 下载并运行安装脚本
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash

# 或安装特定版本
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash -s -- -v v1.0.0

该脚本会：

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

使用go install（替代方案）

# 直接从GitHub安装（二进制文件将放置在$GOPATH/bin中）
go install github.com/nazar256/combine-mcp/cmd/combine-mcp@latest

# 确保$GOPATH/bin在您的PATH中
# 例如，在您的.bashrc或.zshrc中添加以下内容：
# export PATH=$PATH:$(go env GOPATH)/bin

使用Docker（替代方案）

您可以直接使用Docker运行combine-mcp而不需本地安装：

# 运行最新版本
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/combine-mcp:latest

# 运行特定版本
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/-mcp:v1.0.0

# 设置环境变量
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用于常见任务：

# 构建二进制文件
make build

# 运行测试
make test

# 清理构建工件
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代理等）。

而不是为每个客户端配置自己的MCP服务器列表并重复秘密，您：

• 在聚合器配置中一次配置所有后端MCP服务器及其秘密。
• 指向每个客户端相同的combine-mcp二进制文件和相同的MCP_CONFIG文件。
• 让聚合器处理每个客户端的前缀、过滤和工具规范化。

这有几个好处：

• 单一事实来源，了解哪些MCP服务器和工具可用。
• 集中式秘密管理——API令牌和其他凭证仅存在于聚合器配置中。
• 一致的行为，跨不同IDE/代理无需重新配置每个客户端的MCP。
• 秘密隔离——无需直接与AI代理工具分享秘密。

工具名称清理

MCP聚合器自动清理工具名称，将连字符替换为下划线。这是必要的，因为Cursor有一个已知问题，即无法正确检测或使用名称中含有连字符的工具。

例如：

• 原始工具名称：get-user
• 清理后的工具名称：get_user
• 带前缀的工具名称（针对shortcut服务器）：shortcut_get_user

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

工具过滤

MCP聚合器支持按服务器的可选工具过滤。这在您想要时非常有用：

• 限制暴露的工具数量，以保持在Cursor的工具限制内（最多40个工具）
• 仅从每个服务器暴露特定的工具
• 避免服务器之间的工具名称冲突
• 通过减少要处理的工具数量来提高性能

要启用工具过滤，请在服务器配置中添加一个带有allowed数组的tools对象，列出您希望暴露的工具：

{
  "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"
        ]
      }
    }
  }
}