CVE-2025-6514

Name: CVE-2025-6514
Author: Cyberency

作者：Cyberency7 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

`mcp-remote`

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

注意：这是一个工作的概念证明，但应被视为实验性。

为什么需要这个？

目前，大多数野外的MCP服务器都是本地安装的，使用stdio传输。这有一些好处：客户端和服务器可以隐式信任彼此，因为用户已经授予它们运行的权限。添加如API密钥之类的秘密可以通过环境变量完成，并且永远不会离开您的机器。基于npx和uvx构建允许用户避免显式的安装步骤。

但是，大多数可以移动到网络上的软件确实都移动到了网络上：当您可以通过一次部署更新所有用户的软件时，查找和修复错误及迭代新功能要容易得多。

随着最新的MCP 授权规范，我们现在有了一个安全的方法来与世界分享我们的MCP服务器，而无需在用户的笔记本电脑上运行代码。至少，在所有的流行MCP客户端都支持它之前是这样。大多数客户端只支持stdio，那些确实支持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）有一个bug，即在调用npx时，args中的空格不会被转义，这会导致这些值被破坏。您可以使用以下方式解决：

{
  // 配置的其余部分...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // 注意':'周围没有空格
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // 环境变量中的空格是可以接受的
  }
},

标志

如果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服务器时使用不同的传输策略。这允许您控制是否使用Server-Sent Events (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服务器时非常有用。

通过--static-oauth-client-metadata标志提供客户端元数据，可以是JSON字符串或以@前缀的文件路径：

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# 使用node读取文件，所以如果您不确定当前工作目录是什么，最好使用绝对路径
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服务器时非常有用。

通过--static-oauth-client-info标志提供客户端元数据，可以是JSON字符串或以@前缀的文件路径：

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\" }"
# 使用node读取文件，所以如果您不确定当前工作目录是什么，最好使用绝对路径
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

官方文档

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

如果尚未存在，您可能需要在设置>开发者中启用它。

重启Claude Desktop以应用配置文件中的更改。重启后，您应在输入框右下角看到锤子图标。

Cursor

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

从版本0.48.0开始，Cursor直接支持未认证的SSE服务器。如果您的MCP服务器使用官方的MCP OAuth认证协议，您仍然需要添加一个**"command"**服务器并调用mcp-remote。

Windsurf

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

构建远程MCP服务器

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

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

特别是：

https://github.com/cloudflare/workers-oauth-provider 定义一个符合MCP的OAuth服务器在Cloudflare Workers中
https://github.com/cloudflare/agents/tree/main/examples/mcp 使用agents框架定义一个McpAgent

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

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

知道更多您想分享的资源吗？请将其添加到此Readme并发送PR！

故障排除

清理您的`~/.mcp-auth`目录

mcp-remote将所有凭证信息存储在~/.mcp-auth（或MCP_REMOTE_CONFIG_DIR指向的位置）。如果您遇到持续问题，可以尝试运行：

rm -rf ~/.mcp-auth

然后重新启动您的MCP客户端。

检查Node版本

确保您已安装的Node版本是18或更高版本。即使您在其他地方安装了较新的版本，Claude Desktop也会使用系统版本的Node。

重启Claude

修改claude_desktop_config.json时，完全重启Claude可能会有所帮助。

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：<br>tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
对于WSL上的bash：<br>tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
PowerShell：<br>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 URL返回：

认证错误
令牌交换失败：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客户端中更明显。