mcp-remote

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

注意：这只是一个可行的概念验证，但应被视为 实验性功能。

为什么需要这个工具？

迄今为止，市面上大多数 MCP 服务器都部署在本地，使用 stdio 传输方式。这种方式有一些优势：由于用户已授予客户端和服务器运行权限，两者可以彼此隐式信任。诸如 API 密钥之类的敏感信息可以通过环境变量进行配置，且始终不会离开用户的机器。此外，借助 npx 和 uvx，用户无需执行显式的安装步骤即可快速上手。

然而，许多原本可以迁移到云端的软件最终确实被迁移到了云端，原因在于：当你可以通过一次部署就为所有用户推送更新时，查找和修复 bug、迭代新功能会变得容易得多。

借助最新的 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 中的空格不会被转义，从而导致这些值被错误解析。对此，可以采用如下 workaround：

{
  // 其余配置...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // 注意冒号前后无空格
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // 环境变量中的空格是允许的
  }
},

多实例运行

若需以不同配置（例如针对不同的 Atlassian 租户）同时运行同一远程服务器的多个实例，可使用 --resource 标志来隔离 OAuth 会话：

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    },
    "atlassian_tenant2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant2.atlassian.net/"
      ]
    }
  }
}

对于每组唯一的服务器 URL、资源标识符和自定义请求头组合，都会维护独立的 OAuth 会话及令牌存储。

标志

• 如果 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"
      ]

• 若要抑制默认日志输出，可添加 --silent 标志。这将阻止日志输出，除非同时传递了 --debug 标志。

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

• 若要为 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 服务器时非常有用。

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

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# 使用 node readfile，因此如果您不确定当前工作目录，最好使用绝对路径
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\" }"
# 使用 node readfile，因此如果您不确定当前工作目录，最好使用绝对路径
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

官方文档

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

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

如果该文件尚未存在，您可能需要在“设置 > 开发者”中启用它，以添加文件系统 MCP 服务器。

重启 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：用于在 Cloudflare Workers 中定义符合 MCP 标准的 OAuth 服务器。
• 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.js 版本

确保你安装的 Node.js 版本为 18 或更高。Claude Desktop 将使用系统自带的 Node.js 版本，即使你在其他地方安装了更新的版本。

重启 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：
  tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
• 在 WSL 上使用 bash 时：
  tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
• PowerShell：
  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 返回以下错误：

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 客户端中的日志更清晰地显示问题所在。

mcp-remote 快速上手指南

mcp-remote 是一个实验性工具，用于将仅支持本地（stdio）连接的 MCP 客户端连接到远程 MCP 服务器，并支持 OAuth 认证。它解决了当前主流客户端（如 Claude Desktop、Cursor）尚未完全支持远程授权协议的问题。

环境准备

• 操作系统：macOS, Windows, Linux
• Node.js：版本需为 18 或更高。
  • 检查版本命令：node -v
  • 如未安装或版本过低，请访问 Node.js 官网 下载最新版。
• 前置依赖：确保系统已安装 npx（通常随 Node.js 自动安装）。
• 网络要求：能够访问目标远程 MCP 服务器地址。如需通过代理访问，需在配置中启用 --enable-proxy 并设置环境变量。

提示：国内开发者若遇到 npx 下载缓慢问题，可临时配置 npm 镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

mcp-remote 无需全局安装，推荐通过 npx 直接在配置文件中按需调用。这种方式可以避免显式的安装步骤，并确保每次运行都使用最新或指定版本的代码。

如果在执行过程中遇到确认安装的提示错误，可在参数中添加 -y 自动确认。

基本使用

大多数主流 MCP 客户端（Claude Desktop, Cursor, Windsurf）均使用 JSON 格式进行配置。你需要编辑对应的配置文件，添加一个指向远程服务器的 mcpServers 条目。

1. 基础配置示例

以下配置将本地的 stdio 请求桥接到远程 SSE 服务器：

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

2. 带认证头的配置（推荐）

如果远程服务器需要自定义 Header（如 Bearer Token），请使用 --header 参数。

注意：Cursor 和 Windows 版 Claude Desktop 存在参数转义 bug，建议将空格放在环境变量中，而非直接写在 args 里：

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization:${AUTH_HEADER}" 
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-auth-token>" 
      }
    }
  }
}

3. 多实例隔离

如果需要连接同一个远程服务的不同租户（例如不同的 Atlassian 租户），请使用 --resource 参数来隔离 OAuth 会话：

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    }
  }
}

4. 常用客户端配置文件路径

配置完成后，请重启对应的客户端以生效：

• Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • 注：如文件不存在，需在设置中开启 Developer 模式。
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

5. 进阶参数速查

在 args 数组中追加以下参数可实现更多功能：

• 强制更新：使用 mcp-remote@latest 代替 mcp-remote。
• 修改回调端口：在 URL 后添加端口号，例如 "9696"（默认 3334）。
• 允许 HTTP：在内网可信环境下添加 "--allow-http"。
• 调试模式：添加 "--debug"，日志将写入 ~/.mcp-auth/{server_hash}_debug.log。
• 忽略特定工具：添加 "--ignore-tool", "delete*" 可过滤匹配的工具。
• 传输策略：添加 "--transport", "sse-only" 强制使用 SSE（默认为 http-first）。