mcp-remote Skill 技能

技能简介

mcp-remote 是一款解决 MCP 生态兼容性痛点的桥接工具。当前市面上大多数 MCP 客户端（如 Claude Desktop、Cursor、Windsurf）只支持本地 stdio 传输的服务器，而许多新兴的远程 MCP 服务器只提供 HTTP + SSE 甚至需要 OAuth 授权，两者无法直接对接。mcp-remote 充当中间的代理层，让只支持本地 stdio 的客户端也能连接远程 MCP 服务器，并完整支持 OAuth 认证流程。

它由 punkpeye 开发，GitHub 已获 1598 星、295 次 fork，npm 月下载量高达 711 万次，是目前 MCP 社区使用最广泛的桥接组件之一，被大量远程 MCP 教程列为标准接入方案。

核心能力

• stdio 转远程：把只支持本地 stdio 的 MCP 客户端，无缝连接到远程 HTTP/SSE MCP 服务器。
• OAuth 认证支持：遵循 MCP 官方授权规范，能完成远程服务器所需的 OAuth 授权流程，无需手动处理令牌。
• 自定义请求头：通过 --header 参数注入自定义请求头（如 Authorization Bearer 令牌），也支持用环境变量传入密钥。
• 一行接入：在客户端配置中把 command 设为 npx、args 传入远程服务器地址即可，无需额外安装步骤。
• 主流客户端兼容：适配 Claude Desktop、Cursor、Windsurf 等使用统一 mcpServers 配置格式的客户端。
• 向后兼容：当客户端未来原生支持远程授权服务器后，可直接移除 mcp-remote，迁移路径平滑。

安装配置

1. 安装方式：无需单独安装，在客户端配置中直接使用 npx 调用 mcp-remote 即可。
2. 基础配置：在 mcpServers 中加入一项，command 填 npx，args 依次填入 mcp-remote 与远程服务器地址。
3. 带认证配置：如需令牌，可在 args 中追加 --header 与 Authorization: Bearer ${AUTH_TOKEN}，并在 env 中定义 AUTH_TOKEN。
4. 兼容性注意：Cursor、Codex-CLI 与 Windows 版 Claude Desktop 存在空格转义 bug，含空格的参数需按官方文档提供的写法绕开。

使用步骤

1. 确认你使用的 MCP 客户端只支持本地 stdio 传输（如 Claude Desktop 默认配置）。
2. 打开客户端的 MCP 配置文件（例如 claude_desktop_config.json）。
3. 在 mcpServers 字段中新增一项，command 设为 npx，args 填入 ["mcp-remote", "https://你的远程服务器地址/sse"]。
4. 若远程服务器需要鉴权，追加 --header 参数传入 Authorization 头，并在 env 中配置对应密钥。
5. 保存配置并重启客户端，即可在工具列表中看到远程 MCP 服务器提供的全部工具。

适用场景

• 接入远程托管的 MCP 服务器：想使用官方或第三方托管的远程 MCP 服务，但本地客户端不支持远程传输时。
• 需要 OAuth 授权的服务：连接要求走 OAuth 授权流程的 MCP 服务器，由 mcp-remote 自动处理。
• 统一企业级 MCP 接入：公司在云端集中部署 MCP 服务器，员工通过配置 mcp-remote 即可统一接入。
• 快速验证远程服务器：在推进远程 MCP 部署时，用 mcp-remote 作为临时桥梁做连通性验证。

适用人群

使用 Claude Desktop、Cursor、Windsurf 等 stdio-only 客户端的开发者，以及希望接入远程托管 MCP 服务器但受限于客户端能力的 MCP 使用者与运维人员。

工作原理

mcp-remote 在本地启动一个 stdio 的 MCP 服务器进程，对客户端而言它就是一个本地服务器；而在另一侧，它作为客户端连接远程 MCP 服务器（HTTP + SSE）。它把本地 stdio 与远程传输之间做双向转发，并在需要时执行 MCP 授权规范定义的 OAuth 流程，从而让传输层差异对最终客户端完全透明。

官方链接

• GitHub：https://github.com/punkpeye/mcp-remote
• npm：https://www.npmjs.com/package/mcp-remote