smart-mcp-proxy/mcpproxy-go · 上手攻略

仓库：smart-mcp-proxy/mcpproxy-go
链接：https://github.com/smart-mcp-proxy/mcpproxy-go
分类：AI 编程工具 · MCP 中间件
作者：Tom
更新：2026-10-06

是什么

MCPProxy 是一个用 Go 编写的本地 MCP（Model Context Protocol）智能代理，位于 AI 客户端（如 Cursor、Claude Desktop、VS Code Copilot、Goose）与多个上游 MCP 服务器之间。它用 BM25 搜索索引所有已连接服务器的 Tool，将 AI 的「需要什么工具」查询转化为精准的 Top-K 返回，而非把成百上千个 Tool Schema 全部塞进上下文窗口。

核心解决两个问题：①突破 IDE 的 Tool 上限（Cursor 限 40 个，OpenAI API 限 128 个函数）；②防御 Tool Poisoning Attack（TPA，新上线的 MCP 服务器默认被隔离审查）。

⚠️ 截至 2026 年 10 月，GitHub 显示约 385 Stars，58 Forks，Release 为 v0.x（最新版本号以 GitHub Releases 页为准）。

解决什么问题

Tool 上下文爆炸：直接连多个 MCP 服务器时，成百上千个 Tool Schema 吃掉大量上下文窗口，导致 AI 响应变慢且费用上升。MCPProxy 用 BM25 索引，只返回最相关的 Top 5 Tool（top_k 可配）。
IDE Tool 数量上限：Cursor 硬上限 40 个 Tool，直接连 MCP 服务器几乎必然触发上限告警。MCPProxy 提供统一的 retrieve_tools 接口，AI 按需查询，突破此限制。
MCP 服务器安全风险：恶意 MCP 服务器可在 Tool 描述中夹带指令，诱导 AI 读取密钥文件并外传（MCP 官方 2025 年初明确警示此攻击面）。MCPProxy 对新上线的服务器自动 quarantine（隔离），须手动审批后才能使用。
多 MCP 服务器管理割裂：每个 MCP 服务器各自维护一套配置和 URL，MCPProxy 提供统一的 HTTP 聚合端点（默认 http://localhost:8080/mcp/），客户端只需配一个地址。

快速安装

macOS（推荐 DMG）

下载最新 DMG（Apple Silicon → mcpproxy-*-darwin-arm64.dmg；Intel → mcpproxy-*-darwin-amd64.dmg）： https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest

macOS（Homebrew）

# 含菜单栏托盘应用（含 CLI）：
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy
# 仅 CLI（无托盘）：
brew install smart-mcp-proxy/mcpproxy/mcpproxy

Linux（Debian/Ubuntu，apt 自动更新）

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update && sudo apt install mcpproxy

⚠️ Debian 包会自动注册 systemd 服务并启动，监听 127.0.0.1:8080。

Linux（Fedora/RHEL/Rocky/AlmaLinux，dnf）

sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
sudo dnf install -y mcpproxy

Linux（Arch Linux，AUR）

yay -S mcpproxy-bin

Windows（推荐 Installer）

下载 mcpproxy-setup-*-amd64.exe 或 mcpproxy-setup-*-arm64.exe（均为 64 位）： https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest

安装程序自动将 mcpproxy.exe（核心）和 mcpproxy-tray.exe（托盘）写入 Program Files，加入 PATH，支持静默安装：

.\mcpproxy-setup.exe /VERYSILENT

Go 一行安装（任意有 Go 1.26+ 的环境）

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest
mcpproxy serve   # 启动 HTTP 服务在 :8080，显示托盘 UI

核心用法

启动服务

mcpproxy serve   # 默认监听 127.0.0.1:8080，Web UI 和托盘同时启动
# 改端口：
mcpproxy serve --listen :8081

服务启动后，配置文件在 macOS/Linux 为 ~/.mcpproxy/mcp_config.json，Linux .deb 安装时为 /etc/mcpproxy/mcp_config.json（系统服务运行）。

连接 Cursor

打开 Cursor Settings → Tools & Integrations
添加 MCP Server，填入： json { "MCPProxy": { "type": "http", "url": "http://localhost:8080/mcp/" } }
重启 Cursor，或在 Settings 里先禁用再重新启用 MCP 服务器
打开聊天窗口问："What tools do you have available?" 验证连接

⚠️ 首次连接时 MCPProxy 会自动生成最小配置文件（若不存在）。

连接 VS Code（需 VS Code ≥1.102，内置 MCP 支持）

在 settings.json 加入：

{
  "mcp": {
    "servers": {
      "mcpproxy": {
        "type": "http",
        "url": "http://localhost:8080/mcp/"
      }
    }
  }
}

或在工作区 .vscode/mcp.json 中配置（后者优先级更高）。

配置上游 MCP 服务器

编辑 ~/.mcpproxy/mcp_config.json，参考文档： https://docs.mcpproxy.app/configuration/upstream-servers/

MCPProxy 支持将上游服务器以 Docker 容器隔离运行（自动检测 Python/Node.js 运行时，透传环境变量）。

安全隔离工作流

新 MCP 服务器加入后自动进入 quarantine（隔离）状态
在 MCPProxy Web UI（http://localhost:8080）或托盘中查看被隔离的服务器
手动审批后才可使用
可选接入 Snyk、Semgrep、Trivy、Cisco 等 Docker 扫描器，Findings 归一化为 SARIF 格式并输出综合风险评分

⚠️ quarantine 默认是二进制（全部阻断），无法细粒度到单个 Tool 级别；若需要更灵活的 ACL，可关注 Kong AI Gateway 的 MCP Tool ACLs（企业方案）。

LAN 暴露（可选，默认仅 localhost）

⚠️ 暴露到 LAN 时必须设置 api_key，否则任何局域网内设备可直接调用你的 MCPProxy。

编辑 /etc/mcpproxy/mcp_config.json（Linux 服务）或 ~/.mcpproxy/mcp_config.json：

{
  "listen": "0.0.0.0:8080",
  "api_key": "your-strong-random-key-here"
}

完整安全检查清单见文档：https://docs.mcpproxy.app/getting-started/installation#network-exposure

典型适用场景

Cursor/Copilot 多 MCP 服务器聚合：同时连接 GitHub、Playwright、Context7、Jira、Slack、PostgreSQL 等多个 MCP 服务器，在 IDE 内用自然语言驱动所有工具，不触发 40 Tool 上限。
Token 成本敏感场景：AI 每次只需获取相关 Top 5 Tool，Schema 不进入上下文，官方博客称 Token 节省约 99%，准确率提升 43%（⚠️ 该数字来源为 MCPProxy 官方博客，未独立第三方验证）。
安全敏感团队：隔离未知来源的 MCP 服务器，用扫描器过一遍再审批，防止恶意工具描述注入攻击。
跨平台 AI 编程：macOS/Windows/Linux 均有官方二进制，团队成员统一用 MCPProxy 聚合端点，降低各端配置差异。
MCP 服务器离线测试：核心二进制完全离线运行，Web UI 嵌在二进制内，无需额外服务。

坑与注意

默认仅监听 localhost：服务绑定 127.0.0.1:8080，其他机器无法直接访问，需要显式改 listen 为 0.0.0.0 并加 api_key。
macOS 首次启动需完全退出 Cursor：仅重启窗口不足以让 Cursor 重新加载 MCP 服务器配置，建议完全退出后重开。
Docker 隔离需 Docker 已启动：若上游服务器配置了 Docker 隔离但 Docker 未运行，该服务器会启动失败。
Homebrew 与 DMG 不能混用托盘：DMG 安装含托盘应用；Homebrew 的 cask 同样含托盘，但 brew install（非 cask）仅 CLI 无托盘。
Windows 安装程序暂无自动签名：正在等待 Authenticode 签名配置完成（⚠️ 截至 2026-10-06，Windows 官方二进制暂未签名，go install 是目前 Windows 用户最可靠的安装方式）。
配置热重载：修改配置文件后需要重启服务（mcpproxy serve），不支持热更新。
BM25 top_k 默认 5：如果 AI 查询工具时未返回足够的 Tool，可能是 top_k 设置过低，或上游服务器的 Tool 描述未含关键词。

与同类对比

维度	MCPProxy（本工具）	直接连接 MCP	Kong AI Gateway MCP Tool ACLs
部署方式	本地单二进制	无中间层	企业网关
Token 节省	BM25 索引，仅返回 Top-K	全量 Schema 入上下文	细粒度 ACL，需额外部署
安全隔离	基础 quarantine + 可选扫描器	无	细粒度授权 + OAuth
多客户端支持	Cursor/Claude/VS Code/Goose 等	受 IDE MCP 实现限制	API Gateway 模式
配置复杂度	低（JSON 配置）	低（直连）	高（Kong 体系）
适用规模	个人/小团队	个人	企业级

⚠️ 直接连接 vs 通过 MCPProxy：MCPProxy 是代理层，会增加一个网络跳点（localhost:8080），在极高频 Tool 调用场景下可能有 <5ms 延迟开销；Token 节省收益通常远大于延迟损失。

一句话推荐结论

如果你在 Cursor 等 IDE 中连接了多个 MCP 服务器、被 40 Tool 上限卡住、或对未知来源的 MCP 工具有安全顾虑，MCPProxy 是目前最轻量、最易部署的开源解法；追求企业级细粒度 ACL 则考虑 Kong AI Gateway。