MCP-OAUTH2-PROXY

mcp-oauth2-proxy

一个本地 stdio MCP 服务，可代理到受 OAuth2 保护的 HTTP MCP 服务。将它添加到 Claude Desktop、Cursor、VS Code Copilot 或任何其他 MCP 客户端中，在浏览器中登录一次即可使用。

MCP client ─stdio (JSON-RPC)─▶ mcp-oauth2-proxy ─HTTP+SSE + Bearer─▶ upstream MCP server
                                      │
                                      └─ OAuth2 token endpoint (IdP)

文档

本文是快速入门指南。完整文档请参阅 Wiki。

页面	内容
入门指南	安装、首次运行，以及如何接入客户端。
配置	所有字段和环境变量。
OAuth2 授权类型与令牌	授权类型、交互式登录、令牌与缓存生命周期。
发现	RFC 9728 / RFC 8414 端点发现。
安全性	威胁模型和内置防护。
远程主机（SSH 端口转发）	代理在远程运行时如何登录。
故障排除	常见问题和 FAQ。
架构 · 桥接 · OAuth2 内部机制	了解其内部工作原理。
贡献与发布	开发环境设置、测试和发布流程。

目录

• 功能
• 工作原理
• 要求
• 安装
• 快速开始
• 接入 MCP 客户端
• 配置
• 安全性
• 开发
• 不在范围内
• 许可证

功能

• 交互式 authorization_code + PKCE 流程，内置本地浏览器回调监听器——无需手动复制和粘贴代码。
• 刷新令牌缓存存储在磁盘上（AES‑256‑GCM，0600），因此每台机器只需打开一次浏览器。
• 支持用于无头或服务间调用的 client_credentials 授权类型。
• 支持从上游发现令牌和授权端点（RFC 9728 + RFC 8414）——通常无需配置 OAuth。
• 主动刷新令牌，支持时钟偏差、请求去重，以及 401 → 失效 → 重试循环。
• 支持上游 Streamable-HTTP：单次 JSON、SSE text/event-stream 响应，以及可选的长连接服务器通知通道。遵循 Mcp-Session-Id。
• 仅向 Stderr 写入日志（pino），并对令牌、密钥和 Authorization 标头进行脱敏——Stdout 始终保持为干净的 JSON-RPC 通道。

工作原理

1. 发现。 可选地获取 RFC 9728/8414 元数据，以填充 tokenUrl、authorizationUrl、scope 和 resource。
2. 令牌管理器。 为配置的 Grant 添加缓存、 刷新偏差、并发请求去重和 401 失效处理。
3. 预取。 在启动时调用一次 getToken()，确保交互式 浏览器流程（如有需要）在收到第一条 MCP 消息前完成。
4. 桥接。 对每一行 stdin JSON-RPC，使用 Bearer 令牌向 upstream.url 发送 POST 请求；单次 JSON 响应会输出为一行，SSE 响应则每个事件输出一行。收到 401 时会触发 invalidate()，并 重试一次。
5. 服务端流。 在 initialize 之后，可选择保持一个 GET text/event-stream 通道打开，以接收服务端发起的通知。

如需了解完整内部机制，请参阅 wiki 页面： 架构、 桥接内部机制 和 OAuth2 内部机制。

要求

• Node.js 20+
• 使用 Streamable HTTP MCP transport 的受 OAuth2 保护的 MCP 服务。
• 在 IdP 注册的 OAuth2 客户端。对于交互式流程，请将 http://127.0.0.1:53682/callback 注册为重定向 URI（或注册你设置的 OAUTH2_CALLBACK_PORT 对应的 URI）。

安装

无需安装任何内容，MCP 客户端可以直接通过 npx 启动代理：

npx -y mcp-oauth2-proxy

如需基于本地检出版本进行开发：

git clone https://github.com/ChengleiYuan/mcp-oauth2-proxy.git
cd mcp-oauth2-proxy
npm install
npm run build

快速开始

交互式登录（面向最终用户的推荐方式）

UPSTREAM_URL=https://mcp.example.com/mcp \
OAUTH2_GRANT=authorization_code \
OAUTH2_CLIENT_ID=<your-client-id> \
  npx -y mcp-oauth2-proxy

首次启动时，代理会发现 OAuth 端点，打开浏览器进行 PKCE 登录，在 http://127.0.0.1:53682/callback 捕获授权码，将刷新令牌（加密后） 缓存在操作系统配置目录下，然后启动桥接。后续启动时会静默复用缓存的令牌。详情： OAuth2 授权类型和令牌。

无头模式 / 服务账户

UPSTREAM_URL=https://mcp.example.com/mcp \
OAUTH2_GRANT=client_credentials \
OAUTH2_TOKEN_URL=https://idp.example.com/oauth2/token \
OAUTH2_CLIENT_ID=my-service \
OAUTH2_CLIENT_SECRET='…' \
OAUTH2_SCOPE='mcp:read mcp:write' \
  npx -y mcp-oauth2-proxy

将其接入 MCP 客户端

{
  "mcpServers": {
    "remote-oauth2-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-oauth2-proxy"],
      "env": {
        "UPSTREAM_URL": "https://mcp.example.com/mcp",
        "OAUTH2_GRANT": "authorization_code",
        "OAUTH2_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

在无法解析 .cmd 垫片（导致 command: "npx" 无法启动）的 Windows 主机上，请使用显式形式：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "mcp-oauth2-proxy"]
}

env 块中的路径必须是绝对路径，并且在所有平台上都使用正斜杠。

配置

代理可通过 JSON 文件（MCP_PROXY_CONFIG）、环境变量或两者组合进行配置——环境变量会覆盖文件中的值，然后验证合并后的结果。最简配置文件示例：

{
  "upstream": { "url": "https://mcp.example.com/mcp" },
  "oauth2": {
    "grant": "authorization_code",
    "clientId": "my-client",
    "scope": "mcp:read mcp:write",
    "resource": "https://mcp.example.com/mcp"
  }
}

更完整的示例请参阅 config.example.json。

最常用的环境变量：

环境变量	映射到
UPSTREAM_URL	upstream.url
OAUTH2_GRANT	oauth2.grant
OAUTH2_CLIENT_ID	oauth2.clientId
OAUTH2_CLIENT_SECRET	oauth2.clientSecret
OAUTH2_TOKEN_URL	oauth2.tokenUrl
OAUTH2_SCOPE	oauth2.scope
OAUTH2_RESOURCE	oauth2.resource
LOG_LEVEL	log.level

完整参考： 每个字段、默认值和环境变量均记录在 wiki 页面 配置 中。端点自动发现的相关说明请参阅 发现。 要在远程计算机上运行代理？请参阅 远程主机（SSH 端口转发）。 遇到问题？请参阅 故障排除。

安全性

• 令牌由代理本身获取；上游的 Authorization 标头始终由代理设置，绝不会透传客户端发送的标头。
• 访问令牌仅存储在内存中。刷新令牌会以加密形式缓存 （AES‑256‑GCM，密钥文件模式为 0600）——可防范随意读取磁盘数据，但无法防范以同一操作系统用户身份运行的进程。
• 启动时会拒绝连接非环回主机的明文 http://（可通过 ALLOW_INSECURE_HTTP=true 覆盖）；始终允许 https:// 和环回地址的 http://。交互式回调监听器会验证 Host 标头，以防范 DNS 重绑定。
• 所有日志均写入 stderr，并会对令牌、密钥和 Authorization 标头进行脱敏；stdout 专用于 JSON-RPC。

完整的威胁模型和防护措施： 安全性。

开发

npm install
npm run build       # compile TS to dist/
npm run dev         # tsx watch
npm test            # vitest (unit + integration)

集成测试会在进程内启动模拟 OAuth2 令牌端点和模拟 MCP 上游，并通过 PassThrough 流驱动真实桥接，无需网络。项目布局、完整的测试策略和自动化发布流程详见 贡献与发布。

不在范围内

• 每个进程支持多个上游 MCP 服务
• 由操作系统密钥链（DPAPI / Keychain / libsecret）保护的刷新令牌存储
• mTLS / JWT 承载令牌 / 设备代码 / ROPC 授权
• HTTP / SSE 入站传输（这是一个 stdio MCP 服务）

许可证

MIT