CVE 2025 6514

mcp-remote

将仅支持本地（stdio）服务器的MCP客户端连接到具有身份验证支持的远程MCP服务器：

注：这是一个有效的概念证明 但应予以考虑 实验性的.

为什么这是必要的？

到目前为止，大多数MCP服务器都是使用stdio传输在本地安装的。这有一些好处：客户端和服务器都可以隐式地相互信任，因为用户已经授予了它们运行的权限。添加像API密钥这样的秘密可以使用环境变量完成，并且永远不会离开您的机器。并在此基础上 npx 和 uvx 也允许用户避免显式的安装步骤。

但大多数软件都有一个原因 _可以_ 移动到网络 _做了_ 迁移到网络：发现和修复bug要容易得多&当你可以通过一次部署向所有用户推送更新时，迭代新功能。

使用最新的MCP 授权规范，我们现在有一种安全的方式与世界共享我们的MCP服务器 _没有_ 在用户的笔记本电脑上运行代码。或者至少，如果所有流行的MCP _客户_ 还支持它。大多数都是性病，那些 _做_ 支持HTTP+SSE还不支持所需的OAuth流。

那就是 mcp-remote 进来。一旦您选择的MCP客户端支持远程授权服务器，您就可以将其删除。在那之前，请加入这一行，为您想要的MCP客户端着装！

用法

所有最流行的MCP客户端（Claude Desktop、Cursor和Windsurf）都使用以下配置格式：

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

自定义头

要绕过身份验证，或在向远程服务器发送的所有请求上发出自定义标头，请传递 --header CLI参数：

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

注： Cursor和Claude Desktop（Windows）内部存在空格错误 args 当它调用时不会逃脱 npx，这最终会破坏这些值。您可以使用以下方法解决此问题：

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer " // spaces OK in env vars
  }
},

旗帜

• 如果 npx 正在产生错误，请考虑添加 -y 作为自动接受安装的第一个参数 mcp-remote 包裹。

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• 强制 npx 始终检查的更新版本 mcp-remote，添加 @latest 标志：

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• 更改哪个端口 mcp-remote 监听OAuth重定向（默认情况下 3334)，在服务器URL后添加一个额外的参数。请注意，无论您指定什么端口，如果它不可用，都会随机选择一个开放端口。

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• 更改主机 mcp-remote 注册为OAuth回调URL（默认情况下 localhost)，添加 --host 旗帜。

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• 要允许在受信任的专用网络中进行HTTP连接，请添加 --allow-http 旗帜。注意：这只应用于无法拦截流量的安全专用网络。

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• 要启用详细的调试日志，请添加 --debug 旗帜。这将把详细日志写入 ~/.mcp-auth/{server_hash}_debug.log 带有时间戳和有关身份验证过程、连接和令牌刷新的详细信息。

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• 要为mcp-remote启用出站HTTP（S）代理，请添加 --enable-proxy 旗帜。启用后，mcp-remote将使用常见环境变量中的代理设置（例如 HTTP_PROXY, HTTPS_PROXY，以及 NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• 要忽略远程服务器中的特定工具，请添加 --ignore-tool 旗帜。这将从两者中筛选出与指定模式匹配的工具 tools/list 响应和阻止 tools/call 请求：支持通配符模式 *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

您可以指定多个 --ignore-tool 标记以忽略不同的模式。示例：

• delete* -忽略所有以“delete”开头的工具（例如。， deleteTask, deleteUser)
• *account -忽略所有以“account”结尾的工具（例如。， getAccount, updateAccount)
• exactTool -仅忽略名为“exactTool”的工具

• 更改OAuth回调的超时时间（默认情况下 30 秒），添加 --auth-timeout 带有秒值的标志。如果服务器端的身份验证过程需要很长时间，这很有用。

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

交通策略

MCP Remote在连接到MCP服务器时支持不同的传输策略。这允许您控制它是使用服务器发送事件（SSE）还是HTTP传输，以及它尝试它们的顺序。

使用指定运输策略 --transport 标志：

npx mcp-remote https://example.remote/server --transport sse-only

可用策略：

• http-first （默认）：首先尝试HTTP传输，如果HTTP失败并出现404错误，则回退到SSE
• sse-first：首先尝试SSE传输，如果SSE失败并出现405错误，则回退到HTTP
• http-only：仅使用HTTP传输，如果服务器不支持则失败
• sse-only：仅使用SSE传输，如果服务器不支持，则失败

静态OAuth客户端元数据

MCP Remote支持提供静态OAuth客户端元数据，而不是使用MCP-Remote默认值。 当连接到需要特定客户端/软件ID或作用域的OAuth服务器时，这很有用。

以JSON字符串或 @ 前缀为的文件路径 --static-oauth-client-metadata 标志：

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

静态OAuth客户端信息

根据 规格, 鼓励但不要求服务器支持 OAuth动态客户端注册.

对于这些服务器，MCP Remote支持提供静态OAuth客户端信息。 当连接到需要预先注册客户端的OAuth服务器时，这很有用。

以JSON字符串或 @ 前缀为的文件路径 --static-oauth-client-info 标志：

export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude桌面版

官方文件

为了将MCP服务器添加到Claude Desktop，您需要编辑位于以下位置的配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

如果它还不存在， 您可能需要在“设置”>“开发人员”下启用它.

重新启动Claude Desktop以获取配置文件中的更改。 重新启动后，您应该在右下角看到一个锤子图标 输入框。

光标

官方文件配置文件位于 ~/.cursor/mcp.json.

截至版本 0.48.0，Cursor直接支持未经授权的SSE服务器。如果您的MCP服务器正在使用官方的MCP OAuth授权协议，您仍然需要添加 “命令” 服务器和呼叫 mcp-remote.

帆板运动

官方文件配置文件位于 ~/.codeium/windsurf/mcp_config.json.

构建远程MCP服务器

有关构建和部署远程MCP服务器的说明，包括充当有效的OAuth客户端，请参阅以下资源：

• https://developers.cloudflare.com/agents/guides/remote-mcp-server/

具体见：

• https://github.com/cloudflare/workers-oauth-provider用于在Cloudflare Workers中定义MCP兼容OAuth服务器
• https://github.com/cloudflare/agents/tree/main/examples/mcp为了定义一个 McpAgent 使用 agents 框架。

有关测试这些服务器的更多信息，请参阅：

• https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

知道你想分享的更多资源吗？请将它们添加到此自述中并发送PR！

故障排除

清除您的 ~/.mcp-auth 目录

mcp-remote 将所有凭据信息存储在内部 ~/.mcp-auth （或无论你在哪里 MCP_REMOTE_CONFIG_DIR 指向）。如果你有持续的问题，试着运行：

rm -rf ~/.mcp-auth

然后重新启动MCP客户端。

检查你的Node版本

确保您安装的Node版本为 18或 更高克劳德 桌面将使用您的系统版本的Node，即使您有更新的 安装在其他地方的版本。

重新启动克劳德

修改时 claude_desktop_config.json 完全重启克劳德可能会有所帮助

VPN证书

如果您使用VPN，可能会遇到问题，您可以尝试设置 NODE_EXTRA_CA_CERTS 指向CA证书文件的环境变量。如果使用 claude_desktop_config.json, 这可能看起来像：

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

检查日志

• 实时关注Claude Desktop的日志
• MacOS/Linux：

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

• 对于WSL上的bash：

tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"

• 动力壳：

Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

调试

除错记录

要解决复杂问题，特别是令牌刷新或身份验证问题，请使用 --debug 标志：

"args": [
  "mcp-remote",
  "https://remote.mcp.server/sse",
  "--debug"
]

这将在中创建详细的日志 ~/.mcp-auth/{server_hash}_debug.log 具有时间戳和关于连接和身份验证过程的每个步骤的完整信息。当您发现令牌刷新问题、笔记本电脑睡眠/恢复问题或身份验证问题时，请在寻求支持时提供这些日志。

身份验证错误

如果您遇到以下错误，由 /callback 网址：

Authentication Error
Token exchange failed: HTTP 400

你可以跑 rm -rf ~/.mcp-auth 清除任何本地存储的状态和令牌。

“客户端”模式

在命令行上运行以下命令（而不是从MCP服务器）：

npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse

这将贯穿整个授权流程，并尝试列出远程URL上的工具和资源。请在运行后重试 rm -rf ~/.mcp-auth 查看过时的凭据是否是您的问题，否则希望这些日志中的问题比MCP客户端中的问题更明显。