Oauth2 MCP Library

集成Claude.ai的OAuth2 MCP库

用于MCP服务器的增强型OAuth2身份验证库，具有完整的 Claude.ai兼容性.

✨ 特性

• 完整的Claude.ai集成支持 -专门设计用于与Claude.ai的MCP服务器OAuth2流配合使用
• OAuth2代理架构 -使用Google OAuth2处理域验证问题
• 域限制访问 -可配置的电子邮件域限制
• 简单集成 -易于添加到现有的MCP服务器
• 安全功能 -会话管理、令牌验证和安全状态处理
• 多提供商支持 -为Google OAuth2构建，可扩展到其他提供商

🚀 Claude.ai快速入门

1.谷歌OAuth2设置

1. 首选 谷歌云控制台>API和服务>凭据
2. 为“Web应用程序”创建新的OAuth2客户端ID
3. 添加这些 三 授权重定向URI：

   https://your-service-url.run.app/oauth/callback
   https://claude.ai/oauth/callback
   https://claude.ai/api/mcp/auth_callback

2.环境变量

OAUTH2_CLIENT_ID=your-google-oauth2-client-id
OAUTH2_CLIENT_SECRET=your-google-oauth2-client-secret
OAUTH2_REDIRECT_URL=https://your-service-url.run.app/oauth/callback
OAUTH2_ALLOWED_DOMAINS=yourdomain.com,anotherdomain.com

3.实施

import express from 'express';
import OAuth2Handler from '@hundredx/oauth2-mcp';

const app = express();
app.use(express.json());

// Initialize OAuth2 handler
const oauth2Handler = new OAuth2Handler({
  redirectUrl: process.env.OAUTH2_REDIRECT_URL,
  allowedDomains: ['yourdomain.com']
});

// Health endpoint (public)
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    authentication: oauth2Handler.getAuthStatus()
  });
});

// OAuth2 endpoints (required for Claude.ai)
app.get('/authorize', (req, res) => {
  oauth2Handler.handleAuth(req, res);
});

app.get('/oauth/callback', (req, res) => {
  oauth2Handler.handleCallback(req, res);
});

// Token endpoint for OAuth2 flow
app.post('/token', express.urlencoded({ extended: true }), async (req, res) => {
  // Handle token exchange - see full example in documentation
});

// Protected MCP endpoint
app.post('/mcp', oauth2Handler.middleware(), async (req, res) => {
  // Your MCP server logic here
});

app.listen(3000);

4.claude.ai配置

在Claude.ai中，添加您的MCP服务器：

• 服务器URL: https://your-service-url.run.app/mcp
• 授权URL: https://your-service-url.run.app/authorize
• 身份验证类型：OAuth2

🔧 高级配置

OAuth2Handler选项

const oauth2Handler = new OAuth2Handler({
  clientId: 'your-client-id',           // Optional: defaults to env var
  clientSecret: 'your-client-secret',   // Optional: defaults to env var
  redirectUrl: 'https://...',           // Optional: defaults to env var
  allowedDomains: ['domain.com'],       // Optional: domain restrictions
  scopes: ['openid', 'email', 'profile'] // Optional: OAuth2 scopes
}, {
  skipPaths: ['/oauth/', '/health'],    // Optional: paths to skip auth
  publicPaths: ['/health'],             // Optional: always public paths
  sessionDuration: 3600                 // Optional: token duration in seconds
});

Claude.ai兼容性特征

• 代理OAuth2流：处理谷歌的域名验证要求
• 范围映射：自动将Claude.ai的“claudeai”作用域映射到有效的Google作用域
• 国家保护：在整个流程中维护Claude.ai的状态参数
• 参数消毒：处理Claude.ai中格式错误的client_id参数

🛡️ 安全功能

• 域验证：只有来自指定域的用户才能进行身份验证
• 会话管理：过期的安全会话令牌
• 国家保护：加密状态参数以防止CSRF攻击
• 令牌验证：内置令牌验证和续订

📖 完整示例

请参阅 /examples 目录：

• 带有OAuth2的基本MCP服务器
• 使用OAuth2进行云运行部署
• Claude.ai集成示例
• 高级配置模式

🐛 故障排除

常见问题

1. redirect_uri_mismatch

- 确保将所有三个重定向URI添加到Google OAuth2客户端 - 检查URL中的拼写错误

1. 无效范围

- 库自动处理Claude.ai的自定义作用域 - 确保Google OAuth2客户端已启用所需的作用域

1. 出了点问题（谷歌）

- 通常表示域验证问题 - 此库中的代理方法解决了这个问题

1. 认证失败

- 检查环境变量是否设置正确 - 验证域限制是否与用户的电子邮件域匹配

🚀 部署

谷歌云运行

gcloud run deploy your-mcp-server \
  --source . \
  --region us-central1 \
  --set-env-vars OAUTH2_CLIENT_ID="your-id" \
  --set-env-vars OAUTH2_CLIENT_SECRET="your-secret" \
  --set-env-vars OAUTH2_ALLOWED_DOMAINS="yourdomain.com" \
  --allow-unauthenticated

码头工人

FROM node:18-slim
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

📝 api参考

OAuth2Handler类

方法

• handleAuth(req, res) -启动OAuth2流
• handleCallback(req, res) -处理OAuth2回调
• getUserInfo(accessToken) -检索用户信息
• validateToken(token) -验证会话令牌
• middleware() -用于保护的Express中间件
• getAuthStatus() -返回身份验证状态

事件

OAuth2Handler发出用于监视的事件：

• auth_started -OAuth2流已启动
• auth_completed -用户已成功通过身份验证
• auth_failed -身份验证失败
• token_validated -已进行令牌验证

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🙏 鸣谢

• 最初的概念：HundreX，股份有限公司。
• Claude.ai兼容性：通过真实世界的集成测试得到增强
• Google OAuth2集成：基于Google的OAuth2文档

📞 支持

• 问题:
• 文档: API完整文档
• 例子: 示例实现

______________________________________________________________________

🎉 已成功测试Claude.ai MCP服务器集成！