MCP Remote for Go

MCP Remote for Go

此 Go 实现支持仅支持本地（stdio）连接的 MCP 客户端连接到需要身份验证的远程 MCP 服务。

概述

MCP Remote 在以下两者之间进行代理：

• 使用 stdio 传输的本地 MCP 客户端
• 使用 Streamable HTTP 或 Server-Sent Events (SSE) 并进行 OAuth 身份验证的远程 MCP 服务

功能

• Streamable HTTP 传输（MCP 2025-11-25）——通过单端点 POST/GET 实现会话管理
• 传统 SSE 传输（MCP 2024-11-05）——传统的双端点 SSE 连接
• 自动协商——自动检测服务功能并选择最佳传输方式
• 请求元数据标头（MCP 2026-07-28）——根据每条消息生成 Mcp-Method 和 Mcp-Name；对于不符合标头格式要求的值，使用 base64 哨兵编码
• x-mcp-header 镜像（SEP-2243）——将服务指定的工具参数复制到 Mcp-Param-* 标头中；带有格式错误注释的工具不会出现在 tools/list 中
• 流关闭取消（MCP 2026-07-28）——现代客户端发出的 notifications/cancelled 会关闭该请求的响应流，这是该修订版定义的取消信号
• 支持 PKCE 的 OAuth 2.1（RFC 7636）——使用 S256 代码质询进行安全授权
• 自动续期令牌（RFC 6749 §6）——访问令牌即将过期时，会在使用前换取新令牌；如果服务拒绝令牌，也会再次换取。因此，长时间运行的会话可以超出令牌有效期，而无需让任何人重新打开浏览器
• 服务公布的作用域和客户端身份验证——scope 取自 WWW-Authenticate 质询（RFC 6750 §3.1）或受保护资源自身的 scopes_supported（RFC 9728 §2）；令牌端点身份验证方法则取自服务公布的列表，而非客户端自行选择的值
• 同一时间仅进行一次授权——针对同一服务的并发代理通过锁进行协调，因此第二个实例会等待第一个实例获取令牌，而不是为同一账户再打开一个浏览器窗口
• 受 CSRF 保护的回调——state 将每个授权请求与其回调绑定，并按照 RFC 9207 验证发行方，以防止混淆攻击
• 受保护资源元数据（RFC 9728）——从资源端点发现授权服务，包括基于 WWW-Authenticate 的 401 响应发现（§5.1）
• 资源指示符（RFC 8707）——在授权请求和令牌请求中，均将 MCP 服务的规范 URI 作为 resource 发送
• OAuth 发现（RFC 8414）和 OpenID Connect 发现
• 自定义标头和 HTTPS 强制要求

协议修订版支持

代理会转发本地 MCP 客户端使用的修订版；它不会代替客户端选择修订版。使用 2025-11-25 或更早版本的客户端会像以前一样通过 initialize 握手进行转发；使用 2026-07-28 的客户端则会将每个请求的 _meta 镜像到该修订版要求的路由标头中。

因此，双方必须处于 2026-07-28 分界线的同一侧。除一种情况外，所有组合都可正常工作：使用早于 2026-07-28 版本的客户端连接到已完全移除 initialize 握手的服务。规范没有提供让此类客户端进行后续协商的方式，因此只有转换代理才能连接双方——这有意不在此处的范围内。代理会在自动协商期间检测到这种情况，并在启动时给出提示，而不是等到首次调用工具时才以错误的形式暴露出来。

请参阅 test/conformance，了解针对官方 MCP SDK 验证的内容。

安装

桌面扩展（MCPB）

从 GitHub Releases 下载适用于你平台的 .mcpb 文件：

平台	文件
macOS（Apple Silicon）	mcp-remote-go-darwin-arm64.mcpb
macOS（Intel）	mcp-remote-go-darwin-amd64.mcpb
Windows（x64）	mcp-remote-go-windows-amd64.mcpb
Windows（ARM64）	mcp-remote-go-windows-arm64.mcpb

在 Claude Desktop 中打开 .mcpb 文件即可安装。随后会出现配置界面，你可以在其中设置远程服务 URL 和其他选项。

从源代码构建

# Clone the repository
git clone https://github.com/naotama2002/mcp-remote-go.git
cd mcp-remote-go

# Build the binary
make build

使用 Docker

你也可以使用 Docker 运行 mcp-remote-go，它能提供一致的环境，并简化部署。

从 GitHub Container Registry 拉取

# Pull the latest image
docker pull ghcr.io/naotama2002/mcp-remote-go:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/mcp-remote-go:{TAG}

在本地构建

# Build the Docker image
docker build -t mcp-remote-go .

用法

二进制文件用法

# Basic usage (auto-detects transport: tries Streamable HTTP first, falls back to SSE)
mcp-remote-go https://remote.mcp.server/mcp

# Force Streamable HTTP transport
mcp-remote-go https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
mcp-remote-go https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
mcp-remote-go https://remote.mcp.server/mcp 9090

# With a custom header (useful for auth tokens, API keys, etc.)
mcp-remote-go https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Multiple headers — repeat --header as many times as needed
# (Note: there is no --headers plural flag; `--header` takes one Name:Value at a time.)
mcp-remote-go https://remote.mcp.server/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-API-Key: secret" \
  --header "X-Tenant-Id: acme"

# Allow HTTP for trusted networks (normally HTTPS is required)
mcp-remote-go http://internal.mcp.server/mcp --allow-http

# Via HTTP/HTTPS proxy
mcp-remote-go https://remote.mcp.server/mcp --https-proxy http://proxy.example.com:8080

Docker 用法

# Basic usage with Docker (auto-detects transport)
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

# Force Streamable HTTP transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
docker run --rm -it -p 9090:9090 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp 9090

# With custom headers
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Allow HTTP for trusted networks
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest http://internal.mcp.server/mcp --allow-http

# Mount auth directory to persist OAuth tokens
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

MCP 客户端配置

默认情况下，mcp-remote-go 会自动检测传输方式（Streamable HTTP 或 SSE）。你可以使用 --transport 标志强制指定传输方式。

检测会发送 server/discover 请求并读取回复。能对此请求作出响应的服务，其版本为 2026-07-28 或更高版本，且回复还会列出它支持的所有修订版本；如果服务在 JSON-RPC 中拒绝该请求，则表明其版本较早，但仍支持 Streamable HTTP；如果服务完全不响应 POST 请求，则使用已弃用的 SSE 传输方式提供服务。如果服务不再支持 initialize 握手，代理会在启动时记录警告，因为早于 2026-07-28 的 MCP 客户端无法连接到它。

Claude Desktop（MCPB 扩展）

通过 .mcpb 扩展与 Claude Desktop 搭配使用是最简单的方式。安装后，通过图形界面进行配置：

设置	说明	默认值
远程 MCP 服务 URL	远程服务 URL（必填）	—
传输模式	auto、streamable-http 或 sse	auto
OAuth 回调端口	OAuth 回调的本地端口	3334
允许 HTTP	允许不安全的 HTTP 连接	false
HTTP/HTTPS 代理	代理服务 URL（例如 http://proxy:8080）	—
Authorization 标头值	仅填写值部分——请勿在前面加上 Authorization:。示例：Bearer eyJhbGc...、Basic dXNlcjpwYXNz	—
自定义标头 1–5 — 名称 / 值	最多可添加五个额外标头，每个名称/值字段对填写一个。将标头名称（例如 X-API-Key）填入名称字段——该名称会保持可见，便于查看已配置的标头；将值填入值字段，该值会经过加密存储并被遮蔽。名称留空即可跳过该行。Authorization 请填写在上方的字段中。	—

格式说明

根据启动代理的方式，相同的值有三种填写方式。每种方式使用的格式略有不同：

位置	Authorization 标头	其他标头
MCPB 界面（上方）	Authorization Header Value 字段——仅填写值（Bearer xxx）	Custom Header N 字段对——名称和值分别填写
CLI --header（重复该标志）	--header "Authorization: Bearer xxx"	--header "X-API-Key: secret"
环境变量	MCP_AUTH_HEADER="Bearer xxx"（仅填写值）	MCP_HEADERS——每行一个由换行符分隔的 Name: Value（见下方示例）

没有 --headers（复数）标志。 每个标头都要单独传入 --header "Name: Value"；多个标头需要重复使用该标志。

如果 MCP_HEADERS 已包含 Authorization: 行，则会忽略 MCP_AUTH_HEADER，以避免重复。

在不同环境中编写 MCP_HEADERS

在单个环境变量值中嵌入换行符的写法因工具而异。以下所有写法设置的都是相同的两个标头（X-API-Key: secret 和 X-Tenant: acme）：

# bash / zsh — $'...' is ANSI-C quoting that turns \n into a real newline
export MCP_HEADERS=$'X-API-Key: secret\nX-Tenant: acme'

# Portable shell — leave the double quotes open across a real newline
export MCP_HEADERS="X-API-Key: secret
X-Tenant: acme"

// Claude Desktop manual config — JSON \n is interpreted as a real newline
{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": ["https://remote.mcp.server/mcp"],
      "env": {
        "MCP_HEADERS": "X-API-Key: secret\nX-Tenant: acme"
      }
    }
  }
}

# docker-compose — YAML block scalar (|) preserves newlines
services:
  mcp-remote:
    image: ghcr.io/naotama2002/mcp-remote-go:latest
    environment:
      MCP_HEADERS: |
        X-API-Key: secret
        X-Tenant: acme

# docker run — same $'...' trick as bash/zsh
docker run --rm -it \
  -e MCP_HEADERS=$'X-API-Key: secret\nX-Tenant: acme' \
  ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

:: Windows CMD — double quotes don't expand \n, so use the literal escape
::               and the proxy will interpret it (see "Escape fallback" below).
set MCP_HEADERS=X-API-Key: secret\nX-Tenant: acme

# Windows PowerShell — backtick-n is the PowerShell newline escape
$env:MCP_HEADERS = "X-API-Key: secret`nX-Tenant: acme"

MCPB 界面不使用 MCP_HEADERS；每对 Custom Header N 名称/值字段都会单独传递给代理，因此无需在其中使用分隔符。

转义回退（字面量 \n）

当传递给二进制程序的值中不包含真实换行符时，代理会将字面量双字符序列 \n（反斜杠 + n）视为分隔符。这适用于无法嵌入真实换行符的环境：Windows CMD 和使用普通双引号的 shell。一旦存在真实换行符，字面量 \n 就会保持原样，因此值中合法包含 \n 的标头能够原样保留。

空行和不包含 : 的行会被忽略（后者会记录警告），因此某个条目中的拼写错误不会阻止处理其他条目。

Claude Desktop（手动配置）

编辑以下配置文件：

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

使用二进制程序

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

使用 Docker

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

使用 Docker 持久保存 OAuth 令牌：

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "-v",
        "~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Cursor

编辑配置文件 ~/.cursor/mcp.json：

使用二进制程序

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

使用 Docker

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Windsurf

编辑配置文件 ~/.codeium/windsurf/mcp_config.json：

使用二进制程序

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

使用 Docker

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

环境变量

所有选项也可以通过环境变量设置。同时设置时，CLI 标志优先。

变量	说明	对应标志
MCP_SERVER_URL	远程 MCP 服务 URL	--server
MCP_TRANSPORT	传输模式（auto、streamable-http、sse）	--transport
MCP_PORT	OAuth 回调端口	--port
MCP_ALLOW_HTTP	设为 true 以允许使用 HTTP	--allow-http
MCP_HTTPS_PROXY	HTTP/HTTPS 代理 URL	--https-proxy
MCP_AUTH_HEADER	仅包含 Authorization 标头的值（例如 Bearer xxx）——代理会自动添加 Authorization:	--header "Authorization: ..."
MCP_HEADERS	以换行符分隔的任意标头列表，格式为 Name: Value（例如 X-API-Key: secret）	每个条目使用一个 --header "Name: Value"

MCPB 扩展会在内部使用这些环境变量，将通过 GUI 配置的值传递给二进制程序。

身份验证

首次连接到需要身份验证的服务时，系统会提示你在浏览器中打开一个 URL，以授权访问。程序会等待你完成 OAuth 流程，然后建立连接。如果默认端口已被占用，OAuth 身份验证的回调端口会自动使用一个可用端口。

OAuth 实现支持：

• PKCE（RFC 7636），使用 S256 代码质询来增强安全性
• 受保护资源元数据（RFC 9728），用于发现授权服务器；收到 401 时会根据 WWW-Authenticate 查找 PRM（§5.1）
• 资源指示器（RFC 8707）——根据 MCP 身份验证规范，在授权请求和令牌请求中都会将 MCP 服务的规范 URI 作为 resource 发送
• **OAuth 2.0 授权服务器元数据（RFC 8414）**和 OpenID Connect 发现

授权令牌存储在 ~/.mcp-remote-go-auth/ 中，后续连接会重复使用。

故障排除

清除身份验证数据

如果身份验证遇到问题，可以清除已存储的数据：

rm -rf ~/.mcp-remote-go-auth

VPN/证书问题

如果你使用 VPN 并遇到证书问题，可能需要指定 CA 证书：

export SSL_CERT_FILE=/path/to/ca-certificates.crt
mcp-remote-go https://remote.mcp.server/sse

Docker 问题

端口已被占用

如果出现“端口已被占用”错误，请停止冲突的服务或使用其他端口：

# Use a different port
docker run --rm -it -p 3335:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

卷挂载权限问题

如果挂载身份验证目录时遇到权限问题：

# Make sure the directory exists and has proper permissions
mkdir -p ~/.mcp-remote-go-auth
chmod 755 ~/.mcp-remote-go-auth

# Run with volume mount
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

MCP 客户端网络问题

如果 MCP 客户端无法连接到 Docker 容器，请尝试使用主机网络：

# Use host networking mode
docker run --rm -i --net=host ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

许可证

MIT