使用说明

🔐 通过Auth0进行OAuth身份验证的MCP服务器

🚀 一个生产就绪的模型上下文协议（MCP）服务器，使用FastMCP内置的OIDC代理和Auth0作为身份提供者进行OAuth 2.1身份验证。

✨ 特征

🔒 FastMCP OIDC代理：通过内置OAuth身份验证 FastMCP的OIDCProxy
🌐 Auth0集成：用于无缝身份验证的预配置Auth0提供程序
🔄 动态客户端注册：代理Auth0的DCR与Claude.ai协同工作
🛠️ 演示工具：用于测试的计算器和笔记管理工具
📡 HTTP/SSE传输：内置服务器，具有自动路由和身份验证功能

🏗️ 建筑

FastMCP的OIDC代理充当Claude.ai和Auth0之间的桥梁：

┌─────────────┐
│  Claude.ai  │
│   Client    │
└──────┬──────┘
       │
       │ 1. DCR Request
       ↓
┌──────────────────────────────────┐
│   FastMCP Server (OIDC Proxy)    │
│  - Proxies DCR                   │
│  - Handles OAuth flow            │
│  - Validates tokens              │
│  - Protects MCP tools            │
└──────────┬───────────────────────┘
           │
           │ 2. OAuth with Auth0
           ↓
┌──────────────────────────────────┐
│      Auth0 (IdP)                 │
│  - User authentication           │
│  - Token issuance                │
│  - OIDC discovery                │
└──────────────────────────────────┘

📋 先决条件

🐍 Python 3.10或更高版本
🔑 Auth0帐户（免费版有效）
⚙️ 配置了重定向URI的Auth0应用程序

📦 安装

1.️⃣ 克隆存储库

git clone <your-repo-url>
cd mcp-auth-oidcO

2.️⃣ 再进行

pip install -r requirements.txt

或者在虚拟环境中：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3.️⃣ 配置Auth0

🎯 创建Auth0应用程序

登录到您的 Auth0仪表板
引导到 应用程序 → 创建应用
选择 常规Web应用程序
注意你的领域, 客户端ID，以及 客户端密钥

🔗 配置重定向URI

在Auth0应用程序设置中，添加回调URL：

对于当地发展：

http://localhost:8000/auth/callback

生产：

https://your-domain.com/auth/callback

🎫 创建API（面向受众）

引导到 应用程序编程接口 → 创建API
设置标识符（例如。， https://dev-zilqiezmsk6ylig2.us.auth0.com/api/v2/)
添加以下范围：
- 📖 read:notes -阅读笔记
- ✍️ write:notes -创建、更新、删除笔记
- 🧮 use:calculator -使用计算器工具

4.️⃣ 配置环境变量

创建一个 .env 项目根目录中的文件：

# Auth0 Configuration
AUTH0_DOMAIN=your-domain.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=https://your-domain.us.auth0.com/api/v2/

# Server Configuration
RESOURCE_ID=http://localhost:8000
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

✨ 演示凭据 （预配置）：

AUTH0_DOMAIN=dev-zilqiezmsk6ylig2.us.auth0.com
AUTH0_CLIENT_ID=GsJfBMVGn5cDgWQwTiq91SIQBYxQccJA
AUTH0_CLIENT_SECRET=Qst5RVD9Vt79F5NgM_s6ymZSvMYemKrFMykWrDOtextPC2nBeK593yBvpJBafIDl
AUTH0_AUDIENCE=https://dev-zilqiezmsk6ylig2.us.auth0.com/api/v2/
RESOURCE_ID=http://localhost:8000
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

🚀 运行服务器

启动服务器：

python run.py

您应该看到：

============================================================
MCP Auth Demo Server (FastMCP + OIDC Proxy)
============================================================
Base URL: http://localhost:8000
Auth0 Domain: dev-zilqiezmsk6ylig2.us.auth0.com
Server: http://0.0.0.0:8000
Auth Callback: http://localhost:8000/auth/callback
============================================================

Starting server with FastMCP's built-in HTTP/SSE transport...

服务器将于启动 http://localhost:8000 具有以下端点：

📡 MCP/SSE: /mcp/sse 或 /sse （已认证）
🔄 身份验证回调: /auth/callback （OAuth重定向）
✅ 同意: /auth/consent （用户授权）

🛠️ 可用工具

🧮 计算器工具

所有计算器工具都需要 use:calculator 范围：

add_numbers（a，b） ➕ 加两个数字
减法_数字（a，b） ➖ 从a中减去b
复数（a，b） ✖️ 将两个数字相乘
除数（a，b） ➗ 将a除以b

📝 笔记工具

Notes工具需要 read:notes 或 write:notes 范围：

create_note（标题、内容） ✍️ 创建新笔记（需要 write:notes)
read_note（note_id） 📖 阅读特定注释（需要 read:notes)
list_notes（） 📋 列出所有注释（必填 read:notes)
update_note（note_id、标题、内容） 📝 更新注释（需要 write:notes)
delete_note（note_id） 🗑️ 删除注释（需要 write:notes)

🔌 连接到Claude.ai

🌐 方法1:Claude.ai Web界面

打开 Claude.ai
转到“设置”→ 集成→ 模型上下文协议
点击“添加远程MCP服务器”
请输入您的服务器URL： http://localhost:8000
第ai条将：
- 通过代理执行动态客户端注册（DCR）
- 将您重定向到Auth0进行身份验证
- 请求对所需范围的同意
- 使用有效的访问令牌连接到MCP服务器

🌍 方法2：使用ngrok进行远程访问

如果Claude.ai需要通过互联网访问您的本地服务器：

安装吸烟
启动ngrok：
```
ngrok http 8000
```
更新您的 .env 具有ngrok URL的文件：
```
RESOURCE_ID=https://your-ngrok-id.ngrok.io
```
将Auth0重定向URI更新为： https://your-ngrok-id.ngrok.io/auth/callback
重新启动服务器
在Claude.ai中使用ngrok URL： https://your-ngrok-id.ngrok.io

💻 方法3：克劳德桌面应用程序

对于Claude Desktop应用程序，请在MCP配置中添加：

位置:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

配置:

{
  "mcpServers": {
    "auth-demo": {
      "url": "http://localhost:8000",
      "transport": "sse"
    }
  }
}

🔍 MCP检验员测试

这 MCP 检查员是一个交互式开发工具，用于测试和调试启用OAuth的MCP服务器。

⚡ 快速开始

启动服务器:
```
python run.py
```
启动MCP检查器 （在新航站楼中）：
```
npx @modelcontextprotocol/inspector
```
这将打开检查器 http://localhost:6274
配置连接 在检查器UI中：
- 运输：选择“带SSE的HTTP”
- 服务器URL: http://localhost:8000/mcp
- OAuth范围: read:notes write:notes use:calculator
更新身份验证0重定向URI:
- 添加 http://localhost:6274/oauth/callback 到Auth0应用程序的允许回调URL
连接并测试:
- 点击“连接”以启动OAuth流程
- 使用Auth0进行身份验证
- 交互式测试计算器和笔记工具

🎯 你可以用检查员做什么

✅ 逐步测试OAuth身份验证流程
✅ 使用自定义参数调用MCP工具
✅ 查看详细的请求/响应数据
✅ 调试身份验证和授权问题
✅ 验证基于范围的访问控制
✅ 测试错误处理和边缘情况

📚 详细指南

有关全面的测试说明，包括：

逐步OAuth流程测试
具有预期结果的工具调用示例
常见问题和解决方案
高级测试场景

查看完整 MCP检验员测试指南.

🔄 运作原理

🔐 使用OIDC代理的OAuth流

客户注册 📝 Claude.ai向FastMCP发送DCR请求
代理DCR 🔄 FastMCP代理注册（Auth0本身不支持DCR）
授权 🔑 用户被重定向到Auth0进行身份验证
同意 ✅ 用户授权Claude.ai要求的范围
代币交换 🎫 FastMCP交换令牌的授权码
令牌验证 ✔️ FastMCP使用Auth0的OIDC配置验证令牌
工具访问 🛠️ 经过身份验证的请求可以访问受保护的MCP工具

🌟 OIDC代理的主要优势

🚀 无需手动注册：客户端动态注册
✅ 自动令牌验证：通过Auth0的JWKS进行JWT验证
🔒 基于范围的授权：受OAuth作用域保护的工具
👤 同意流程：用户查看并批准客户端可以访问的内容
🌐 与任何OIDC提供商合作：不只是Auth0

📁 项目结构

mcp-auth-oidcO/
├── src/
│   ├── __init__.py           # Package initialization
│   ├── auth_config.py        # Auth0Provider configuration
│   ├── server.py             # FastMCP server with demo tools
│   ├── app.py                # FastMCP app export
│   └── main.py               # Main entry point
├── .env                      # Environment variables (not in git)
├── .gitignore               # Git ignore rules
├── pyproject.toml           # Python project configuration
├── requirements.txt         # Python dependencies
├── run.py                   # Convenience script
├── README.md               # This file
├── QUICKSTART.md           # Quick start guide
└── TESTING.md              # Testing guide

👨‍💻 发展

📝 代码结构

服务器由三个简单的文件构建：

auth_config.py 🔧 配置Auth0Provider
server.py 🛠️ 定义MCP工具 @mcp.tool() 装饰器
main.py 🚀 启动FastMCP HTTP服务器

就是这样！FastMCP自动处理所有路由、身份验证和SSE。

➕ 添加新工具

要添加新工具，请执行以下操作：

打开 src/server.py
使用添加新功能 @mcp.tool() 装饰师：

@mcp.tool()
def my_new_tool(param: str) -> str:
    """
    Description of what the tool does.
    
    Args:
        param: Description
    
    Returns:
        Description of return value
    
    Requires:
        Scope: my:scope
    """
    return f"Result: {param}"

将范围添加到 src/auth_config.py:

SUPPORTED_SCOPES = [
    "read:notes",
    "write:notes",
    "use:calculator",
    "my:scope",  # Add your new scope
]

在Auth0中配置作用域

🧪 测试

看测试.md 获取全面的测试说明。

⚡ 快速测试

启动服务器并验证其是否正在运行：

# Start server
python run.py

# In another terminal, check health (if you add a health endpoint)
curl http://localhost:8000/

🔧 故障排除

❌ 服务器无法启动

✅ 检查Python版本： python --version （需要3.10+）
✅ 验证是否在中设置了所有环境变量 .env
✅ 确保安装了依赖项： pip install -r requirements.txt

🔐 身份验证失败

✅ 验证中的Auth0凭据 .env 是正确的
✅ 检查Auth0中的重定向URI是否匹配 {BASE_URL}/auth/callback
✅ 确保在Auth0 API中配置了作用域

🌐 Claude.ai无法连接

✅ 验证服务器是否正在运行且可访问
✅ 检查基本URL是否正确
✅ 对于本地测试，请确保Claude.ai可以访问本地主机（尝试ngrok）
✅ 检查服务器日志中的身份验证错误

🔒 安全考虑

🚨 用于生产部署

🔐 仅限HTTPS：在生产环境中始终使用HTTPS
🔑 环境变量：从不承诺 .env 到版本控制
🗝️ 安全的秘密：使用机密管理器（AWS机密管理器、Azure密钥库等）
💾 令牌存储：配置加密存储后端（带加密的Redis）
🎫 JWT签名密钥：设置显式 jwt_signing_key 生产中
⏱️ 速率限制：添加限速中间件
📝 日志记录：实施全面的审计日志
🌐 跨域资源共享：配置特定来源（不 *)

⚙️ 生产配置

from fastmcp.server.auth.providers.auth0 import Auth0Provider
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet
import os

auth = Auth0Provider(
    config_url=f"https://{os.environ['AUTH0_DOMAIN']}/.well-known/openid-configuration",
    client_id=os.environ['AUTH0_CLIENT_ID'],
    client_secret=os.environ['AUTH0_CLIENT_SECRET'],
    audience=os.environ['AUTH0_AUDIENCE'],
    base_url=os.environ['BASE_URL'],
    required_scopes=SUPPORTED_SCOPES,
    jwt_signing_key=os.environ['JWT_SIGNING_KEY'],
    client_storage=FernetEncryptionWrapper(
        key_value=RedisStore(host="redis.example.com", port=6379),
        fernet=Fernet(os.environ['STORAGE_ENCRYPTION_KEY'])
    )
)

📚 参考文献

📄 许可证

MIT许可证-您可以自由地将其用作您自己的MCP服务器的模板。

💬 支持

对于问题和疑问：

🚀 FastMCP： GitHub问题 | 不和谐
🌐 身份验证0: 社区论坛

🤝 贡献

欢迎投稿！请随时提交pull请求或打开bug和功能请求的问题。

⭐ 如果你觉得这个repo有用，请将其标记为星号！ ⭐

由...制作❤️ 使用 FastMCP 和身份验证0