MCP OAuth 代理

MCP OAuth 代理是一个开源的OAuth 2.1代理服务器，它为MCP（模型上下文协议）服务器添加了身份验证和授权功能。

MCP OAuth 代理是什么？

MCP OAuth 代理充当OAuth提供商（如Google、Microsoft、GitHub）与MCP服务器之间的桥梁，提供以下功能：

• OAuth 2.1合规性 - 完整的OAuth 2.1授权服务器，支持PKCE
• MCP集成 - 无缝地将用户上下文注入到MCP服务器中
• 多提供商支持 - 通过自动发现与任何OAuth 2.0提供商兼容
• 数据库灵活性 - 生产环境使用PostgreSQL，开发环境使用SQLite

架构

该代理位于您的MCP服务器之前，处理OAuth 2.1的身份验证并验证来自外部提供商的用户身份。

以下是其工作原理：

1. OAuth 2.1流程 - 当客户端需要访问时，代理会重定向到外部认证提供商（如Google、Microsoft、GitHub）以验证用户身份
2. 令牌发放 - 认证完成后，代理向客户端发放访问令牌
3. MCP认证合规性 - 遵循MCP认证规范，并与任何兼容的MCP客户端协同工作
4. 请求代理 - 验证访问令牌并将经过认证的请求转发给您的MCP服务器
5. 用户上下文 - 向MCP服务器发送关于用户身份和基于OAuth范围配置的对外部服务访问权限的必要头信息

发送到MCP服务器的头信息

当代理请求到您的MCP服务器时，OAuth代理会自动注入包含用户信息的以下头信息：

头信息	描述	示例
X-Forwarded-User	来自OAuth提供商的用户ID	12345678901234567890
X-Forwarded-Email	用户的电子邮件地址	user@example.com
X-Forwarded-Name	用户的显示名称	John Doe
X-Forwarded-Access-Token	用于外部API调用的OAuth访问令牌	ya29.a0ARrdaM...

这些头信息允许您的MCP服务器：

• 识别发出请求的用户
• 根据用户信息个性化响应
• 使用访问令牌对外部服务进行认证API调用
• 实现特定用户的逻辑和访问控制

快速开始

先决条件

• 系统上安装Docker
• 一个OAuth提供商账户（如Google、Microsoft、GitHub等）
• 一个正在运行的MCP服务器以供代理使用

1. 设置OAuth凭证

OAuth凭证（客户端ID和客户端密钥）由代理用来代表您的用户与外部提供商进行身份验证。

Google OAuth

1. 转到Google Cloud Console并创建一个新的项目
2. 在“API和服务”>“库”中启用Google+ API
3. 配置OAuth同意屏幕并添加授权用户
4. 创建OAuth客户端：
   • 转到“凭据”>“创建凭据”>“OAuth 2.0客户端ID”
   • 选择“Web应用程序”类型
   • 添加http://localhost:8080/callback作为重定向URI
   • 复制您的客户端ID和客户端密钥

Microsoft OAuth

1. 转到Azure门户 > “Azure Active Directory”
2. 注册一个新应用，重定向URI为http://localhost:8080/callback
3. 配置API权限（Microsoft Graph：User.Read，Mail.Read）
4. 创建客户端密钥并复制应用程序（客户端）ID和客户端密钥

GitHub OAuth

1. 转到GitHub设置 > 开发者设置 > OAuth应用
2. 使用回调URL http://localhost:8080/callback 创建OAuth应用
3. 复制客户端ID并生成客户端密钥

2. 设置您的MCP服务器

OAuth代理需要一个可流式传输的HTTP MCP服务器。例如使用Obot的Gmail MCP服务器：

git clone https://github.com/obot-platform/tools
cd google/gmail
uv run python -m obot_gmail_mcp.server

这将在http://localhost:9000/mcp/gmail启动服务器。

3. 运行OAuth代理

选项A：Docker

docker run -d --name mcp-oauth-proxy -p 8080:8080 \
  -e OAUTH_CLIENT_ID="your-client-id" \
  -e OAUTH_CLIENT_SECRET="your-client-secret" \
  -e OAUTH_AUTHORIZE_URL="https://accounts.google.com" \
  -e SCOPES_SUPPORTED="openid,email,profile,https://www.googleapis.com/auth/gmail.readonly" \
  -e MCP_SERVER_URL="http://localhost:9000/mcp/gmail" \
  -e ENCRYPTION_KEY="your-encryption-key" \
  ghcr.io/obot-platform/mcp-oauth-proxy:latest

选项B：CLI二进制文件

1. 从GitHub Releases下载
2. 使用环境变量运行：

export OAUTH_CLIENT_ID="your-client-id"
export OAUTH_CLIENT_SECRET="your-client-secret"
export OAUTH_AUTHORIZE_URL="https://accounts.google.com"
export SCOPES_SUPPORTED="openid,email,profile,https://www.googleapis.com/auth/gmail.readonly"
export MCP_SERVER_URL="http://localhost:9000/mcp/gmail"
export ENCRYPTION_KEY="your-encryption-key"

./mcp-oauth-proxy

环境变量

变量	必需	描述
OAUTH_CLIENT_ID	✅	提供商处的OAuth客户端ID
OAUTH_CLIENT_SECRET	✅	OAuth客户端密钥
OAUTH_AUTHORIZE_URL	✅	提供商的基础URL（例如，https://accounts.google.com）
SCOPES_SUPPORTED	✅	逗号分隔的OAuth范围
MCP_SERVER_URL	✅	您的MCP服务器端点
DATABASE_DSN	❌	数据库连接字符串（默认为SQLite）
ENCRYPTION_KEY	✅	基于64编码的32字节AES密钥

您应该使用以下命令生成一个随机的32字节AES密钥作为ENCRYPTION_KEY环境变量：

openssl rand -base64 32

不同的认证提供商URL：

• Google: https://accounts.google.com
• Microsoft: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
• GitHub: https://github.com/login/oauth/authorize

VSCode设置

在您的工作区创建一个.vscode/mcp.json文件：

{
  "servers": {
    "oauth-gmail": {
      "type": "http",
      "url": "http://localhost:8080/mcp/gmail"
    }
  }
}

认证流程：

• VSCode打开浏览器进行OAuth认证
• 使用您的账户登录并授予权限
• VSCode接收访问令牌并与Gmail MCP服务器通信
• 使用Copilot面板与您的邮件互动

许可证

本项目根据Apache许可证2.0版发布。