/ 目录 / 演练场 / mcp-proxy
● 社区 sparfenyuk ⚡ 即开即用

mcp-proxy

作者 sparfenyuk · sparfenyuk/mcp-proxy

连接 stdio MCPs 和 SSE/Streamable HTTP,反向亦然 — 一个小巧的 Python 工具让传输层互操作。

sparfenyuk/mcp-proxy 是个传输层网桥。两种模式:(1) stdio 客户端连接到远程 SSE/HTTP MCP — 让 Claude Desktop 能和远程服务器对话;(2) SSE 服务器包装本地 stdio MCP — 通过 HTTP 暴露它,支持 CORS、认证、多个命名服务器。

为什么要用

核心特性

实时演示

实际使用效果

proxy.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "proxy",
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "proxy": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-proxy"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add proxy -- uvx mcp-proxy

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: mcp-proxy

如何在 Claude Desktop 中使用远程 SSE MCP 服务器

👤 拥有团队托管 MCP 网关的开发者 ⏱ ~10 min beginner

何时使用: 你的团队在 https://mcp.team.internal 上运行网关,但 Claude Desktop 只支持 stdio。

前置条件
  • uv 或 pipx — brew install uv
步骤
  1. 安装 mcp-proxy
    运行:uv tool install mcp-proxy✓ 已复制
    → PATH 中有 mcp-proxy
  2. 配置 Claude Desktop
    添加 MCP 条目:command=mcp-proxy, args=['--headers','Authorization','Bearer $TOKEN','https://mcp.team.internal/sse']。✓ 已复制
    → Claude Desktop 重启后连接
  3. 验证
    在 Claude 中问:你有哪些工具?✓ 已复制
    → 远程工具被列出

结果: 远程服务器可从仅支持 stdio 的客户端使用。

注意事项
  • 认证 Header 没被识别 — 精确使用 --headers 语法;某些客户端会破坏环境变量插值 — 自己展开 token
搭配使用: mcphub

如何通过 HTTP 向远程团队成员暴露本地 stdio MCP

👤 临时共享本地工具的开发者 ⏱ ~15 min intermediate

何时使用: 你构建了自定义 stdio MCP,远程同事想试试。

步骤
  1. 在入站模式下运行代理
    mcp-proxy --sse-host 0.0.0.0 --sse-port 3333 --named-server my-tool 'uvx my-tool-mcp'✓ 已复制
    → SSE 端点在 :3333/my-tool/sse
  2. 建立隧道
    使用 ngrok 或 cloudflared 将 3333 暴露在公网 URL 上。✓ 已复制
    → 可分享的 URL
  3. 团队成员连接
    他们将 URL 添加到他们的客户端(通过 mcp-proxy 或直接,如果他们的客户端支持 SSE)。✓ 已复制
    → 共享会话正常工作

结果: 本地工具的临时共享。

注意事项
  • 默认没有认证 — 使用 --bearer-token 或将其放在 Caddy basic auth 后面

如何从一个代理端口为多个本地 MCPs 服务

👤 自建实验室爱好者 ⏱ ~15 min intermediate

何时使用: 你想要一个网关为 github、filesystem 和 postgres MCPs 服务。

步骤
  1. 用多个 --named-server 参数启动
    mcp-proxy --sse-port 3333 --named-server gh 'uvx mcp-server-github' --named-server fs 'uvx mcp-server-filesystem ~/src'✓ 已复制
    → 端点 /gh/sse 和 /fs/sse
  2. 在客户端中连接每个
    在 MCP 客户端中将每个添加为单独的服务器。✓ 已复制
    → 来自两者的工具都出现了

结果: 一个进程,多个 MCPs。

注意事项
  • 命名服务器共享代理的资源预算 — 不要将重量级 MCPs 和轻量级 MCPs 放在同一个代理中
搭配使用: mcphub

组合

与其他 MCP 搭配,撬动十倍杠杆

proxy + mcphub

用 mcp-proxy 暴露 stdio MCPs,MCPHub 可随后通过 HTTP 聚合它们

用 mcp-proxy 将我的本地 github stdio MCP 桥接到 HTTP,然后在 MCPHub 的 'dev' 组中注册它。✓ 已复制
proxy + unla

在 mcp-proxy 的最后一英里 stdio 网桥基础上使用 Unla 的公网网关

用 mcp-proxy 桥接 stdio MCPs 并将 Unla 作为前置网关以获得 OAuth + 多租户。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
(proxy) stdio-to-sse remote_url, headers?, bearer? 将 stdio 客户端连接到远程 SSE 服务器 free
(proxy) sse-to-stdio named_server spec 通过 HTTP 暴露 stdio MCP free

成本与限制

运行它的成本

API 配额
每次调用 Token 数
没有可测量的开销
费用
免费(MIT)
提示
当你的客户端原生支持另一种传输时跳过代理 — 更少的活动部件。

安全

权限、密钥、影响范围

最小权限: 到远程 URL 的网络出站(出站模式) 入站端口绑定(入站模式)
凭据存储: Headers/tokens 通过 CLI 参数或 env 传递
数据出站: 任何桥接的 MCP 所做的;代理本身是透明的
切勿授予: 不要未经认证就在 0.0.0.0 上暴露入站模式 不要在 shell 历史中记录 tokens — 使用 env 变量

故障排查

常见错误与修复

连接立即关闭

远程 URL 路径错误 — SSE 端点通常以 /sse 结尾。

验证: curl -N <url>
浏览器客户端中的 CORS 错误

启动 mcp-proxy 时使用 --allow-origin,或将其放在具有 CORS headers 的反向代理后面。

即使使用 --bearer-token 也是 401

远程期望 token 在不同的 header 上(如 X-API-Key)。用 --headers 自定义。

SSE 连接在 60 秒后断开

负载均衡器空闲超时。提高它或使用 Streamable HTTP。

替代方案

mcp-proxy 对比其他方案

替代方案何时用它替代权衡
MCPHub你需要多服务器聚合 + 路由,不仅仅是网桥更重 — UI、DB、OAuth 都捆绑在一起
Unla你需要 REST-to-MCP 转换和网关解决不同的问题空间
supergateway你更喜欢使用 JavaScript stdio-to-SSE 网桥Node 依赖

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills