内容
# 🔐 MCP 服务器使用 OAuth 认证（通过 Auth0）
[](https://www.python.org/downloads/)
[](https://gofastmcp.com/)
[](https://auth0.com/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
> 🚀 一个生产就绪的模型上下文协议（MCP）服务器，使用 FastMCP 内置的 OIDC 代理和 Auth0 作为身份提供者，支持 OAuth 2.1 认证。
## ✨ 功能
- 🔒 **FastMCP OIDC 代理**：通过 FastMCP 的 OIDCProxy 进行内置 OAuth 认证
- 🌐 **Auth0 集成**：预配置的 Auth0 提供者，实现无缝认证
- 🔄 **动态客户端注册**：代理 DCR 以便 Auth0 与 Claude.ai 配合使用
- 🛠️ **演示工具**：计算器和笔记管理工具，用于测试
- 📡 **HTTP/SSE 传输**：内置服务器，自动路由和认证
## 🏗️ 架构
FastMCP 的 OIDC 代理作为 Claude.ai 和 Auth0 之间的桥梁：
```
┌─────────────┐
│ Claude.ai │
│ Client │
└──────┬──────┘
│
│ 1. DCR 请求
↓
┌──────────────────────────────────┐
│ FastMCP 服务器（OIDC 代理） │
│ - 代理 DCR │
│ - 处理 OAuth 流 │
│ - 验证令牌 │
│ - 保护 MCP 工具 │
└──────────┬───────────────────────┘
│
│ 2. 与 Auth0 进行 OAuth
↓
┌──────────────────────────────────┐
│ Auth0（IdP） │
│ - 用户认证 │
│ - 令牌颁发 │
│ - OIDC 发现 │
└──────────────────────────────────┘
```
## 📋 先决条件
- 🐍 Python 3.10 或更高版本
- 🔑 Auth0 账户（免费层级有效）
- ⚙️ 已配置 Auth0 应用程序，包含重定向 URI
## 📦 安装
### 1️⃣ 克隆仓库
```bash
git clone <your-repo-url>
cd mcp-auth-oidcO
```
### 2️⃣ 安装依赖项
```bash
pip install -r requirements.txt
```
或使用虚拟环境：
```bash
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
pip install -r requirements.txt
```
### 3️⃣ 配置 Auth0
#### 🎯 创建 Auth0 应用程序
1. 登录到您的 [Auth0 仪表盘](https://manage.auth0.com/)
2. 导航到 **应用程序** → **创建应用程序**
3. 选择 **常规 Web 应用程序**
4. 记录您的 **域名**、**客户端 ID** 和 **客户端密钥**
#### 🔗 配置重定向 URI
在您的 Auth0 应用程序设置中，添加回调 URL：
**适用于本地开发：**
```
http://localhost:8000/auth/callback
```
**适用于生产环境：**
```
https://your-domain.com/auth/callback
```
#### 🎫 创建 API（用于受众）
1. 导航到 **API** → **创建 API**
2. 设置标识符（例如，`https://dev-zilqiezmsk6ylig2.us.auth0.com/api/v2/`）
3. 添加以下作用域：
- 📖 `read:notes` - 读取笔记
- ✍️ `write:notes` - 创建、更新、删除笔记
- 🧮 `use:calculator` - 使用计算器工具
### 4️⃣ 配置环境变量
在项目根目录创建 `.env` 文件：
```env
# Auth0 配置
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/
# 服务器配置
RESOURCE_ID=http://localhost:8000
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```
**✨ 演示凭证** （预配置）：
```env
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
```
## 🚀 运行服务器
启动服务器：
```bash
python run.py
```
您应该看到：
```
============================================================
MCP Auth 演示服务器（FastMCP + OIDC 代理）
============================================================
基准 URL：http://localhost:8000
Auth0 域名：dev-zilqiezmsk6ylig2.us.auth0.com
服务器：http://0.0.0.0:8000
认证回调：http://localhost:8000/auth/callback
============================================================
使用 FastMCP 内置的 HTTP/SSE 传输启动服务器...
```
服务器将在 `http://localhost:8000` 启动，以下是以下端点：
- 📡 **MCP/SSE**：`/mcp/sse` 或 `/sse`（已认证）
- 🔄 **认证回调**：`/auth/callback`（OAuth 重定向）
- ✅ **同意**：`/auth/consent`（用户授权）
## 🛠️ 可用工具
### 🧮 计算器工具
所有计算器工具都需要 `use:calculator` 作用域：
1. **add_numbers(a, b)** ➕ 添加两个数字
2. **subtract_numbers(a, b)** ➖ 从 a 中减去 b
3. **multiply_numbers(a, b)** ✖️ 乘以两个数字
4. **divide_numbers(a, b)** ➗ 将 a 除以 b
### 📝 笔记工具
笔记工具需要 `read:notes` 或 `write:notes` 作用域：
1. **create_note(title, content)** ✍️ 创建新笔记（需要 `write:notes`）
2. **read_note(note_id)** 📖 读取特定笔记（需要 `read:notes`）
3. **list_notes()** 📋 列出所有笔记（需要 `read:notes`）
4. **update_note(note_id, title, content)** 📝 更新笔记（需要 `write:notes`）
5. **delete_note(note_id)** 🗑️ 删除笔记（需要 `write:notes`）
## 🔌 连接到 Claude.ai
### 🌐 方法 1：Claude.ai Web 界面
1. 打开 [Claude.ai](https://claude.ai)
2. 进入 设置 → 集成 → 模型上下文协议
3. 点击 "添加远程 MCP 服务器"
4. 输入您的服务器 URL：`http://localhost:8000`
5. Claude.ai 将：
- 通过代理执行动态客户端注册（DCR）
- 重定向您到 Auth0 进行认证
- 请求所需作用域的同意
- 使用有效的访问令牌连接到您的 MCP 服务器
### 🌍 方法 2：使用 ngrok 进行远程访问
如果 Claude.ai 需要通过互联网访问您的本地服务器：
1. 安装 [ngrok](https://ngrok.com/)
2. 启动 ngrok：
```bash
ngrok http 8000
```
3. 更新您的 `.env` 文件，使用 ngrok URL：
```env
RESOURCE_ID=https://your-ngrok-id.ngrok.io
```
4. 更新 Auth0 重定向 URI 至：`https://your-ngrok-id.ngrok.io/auth/callback`
5. 重启服务器
6. 在 Claude.ai 中使用 ngrok URL：`https://your-ngrok-id.ngrok.io`
### 💻 方法 3：Claude 桌面应用程序
对于 Claude 桌面应用程序，请添加至您的 MCP 配置：
**位置**：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
**配置**:
```json
{
"mcpServers": {
"auth-demo": {
"url": "http://localhost:8000",
"transport": "sse"
}
}
}
```
## 🔍 使用 MCP 检测器进行测试
[MCP 检测器](https://github.com/modelcontextprotocol/inspector) 是一个交互式开发者工具，用于测试和调试您的 OAuth 启用 MCP 服务器。
### ⚡ 快速开始
1. **启动服务器**：
```bash
python run.py
```
2. **启动 MCP 检测器** （在新终端中）：
```bash
npx @modelcontextprotocol/inspector
```
这将打开检测器，网址为 `http://localhost:6274`
3. **在检测器 UI 中配置连接**：
- **传输**：选择 "HTTP with SSE"
- **服务器 URL**：`http://localhost:8000/mcp`
- **OAuth 作用域**：`read:notes write:notes use:calculator`
4. **更新 Auth0 重定向 URI**：
- 将 `http://localhost:6274/oauth/callback` 添加到您的 Auth0 应用程序的允许回调 URL 列表中
5. **连接并测试**：
- 点击 "连接" 以启动 OAuth 流
- 使用 Auth0 进行认证
- 交互式测试计算器和笔记工具
### 🎯 您可以使用检测器执行的操作
- ✅ 分步测试 OAuth 认证流程
- ✅ 调用 MCP 工具并带有自定义参数
- ✅ 查看详细的请求/响应数据
- ✅ 调试认证和授权问题
- ✅ 验证基于作用域的访问控制
- ✅ 测试错误处理和边缘情况
### 📚 详细指南
有关综合测试说明，包括：
- 分步 OAuth 流测试
- 示例工具调用及预期结果
- 常见问题及解决方案
- 高级测试场景
请参阅完整的 [MCP 检测器测试指南](MCP_INSPECTOR_GUIDE.md)。
## 🔄 工作原理
### 🔐 使用 OIDC 代理的 OAuth 流
1. **客户端注册** 📝 Claude.ai 向 FastMCP 发送 DCR 请求
2. **代理 DCR** 🔄 FastMCP 代理注册（Auth0 不原生支持 DCR）
3. **授权** 🔑 用户被重定向到 Auth0 进行认证
4. **同意** ✅ 用户授权 Claude.ai 请求的作用域
5. **令牌交换** 🎫 FastMCP 交换授权码为令牌
6. **令牌验证** ✔️ FastMCP 使用 Auth0 的 OIDC 配置验证令牌
7. **工具访问** 🛠️ 已认证的请求可以访问受保护的 MCP 工具
### 🌟 OIDC 代理的主要优势
- 🚀 **无需手动注册**：客户端动态注册
- ✅ **自动令牌验证**：通过 Auth0 的 JWKS 进行 JWT 验证
- 🔒 **基于作用域的授权**：工具受 OAuth 作用域保护
- 👤 **同意流程**：用户查看并批准客户端可以访问的内容
- 🌐 **与任何 OIDC 提供者配合使用**：不仅限于 Auth0
## 📁 项目结构
```
mcp-auth-oidcO/
├── src/
│ ├── __init__.py # 包初始化
│ ├── auth_config.py # Auth0Provider 配置
│ ├── server.py # FastMCP 服务器，带有演示工具
│ ├── app.py # FastMCP 应用程序导出
│ └── main.py # 主入口点
├── .env # 环境变量（不在 git 中）
├── .gitignore # Git 忽略规则
├── pyproject.toml # Python 项目配置
├── requirements.txt # Python 依赖项
├── run.py # 便捷脚本
├── README.md # 此文件
├── QUICKSTART.md # 快速入门指南
└── TESTING.md # 测试指南
```
## 👨💻 开发
### 📝 代码结构
服务器由三个简单的文件构建：
1. **`auth_config.py`** 🔧 配置 Auth0Provider
2. **`server.py`** 🛠️ 定义 MCP 工具，带有 `@mcp.tool()` 装饰器
3. **`main.py`** 🚀 启动 FastMCP HTTP 服务器
就是这样！FastMCP 自动处理所有路由、认证和 SSE。
### ➕ 添加新工具
要添加新工具：
1. 打开 `src/server.py`
2. 添加一个带有 `@mcp.tool()` 装饰器的新函数：
```python
@mcp.tool()
def my_new_tool(param: str) -> str:
"""
描述工具的作用。
参数：
param: 描述
返回：
返回值的描述
需要：
作用域：my:scope
"""
return f"结果：{param}"
```
3. 将作用域添加到 `src/auth_config.py`：
```python
SUPPORTED_SCOPES = [
"read:notes",
"write:notes",
"use:calculator",
"my:scope", # 添加您的新作用域
]
```
4. 在 Auth0 中配置作用域
## 🧪 测试
请参阅 [TESTING.md](TESTING.md) 以获取综合测试说明。
### ⚡ 快速测试
启动服务器并验证它正在运行：
```bash
# 启动服务器
python run.py
# 在另一个终端，检查健康状况（如果您添加健康端点）
curl http://localhost:8000/
```
## 🔧 故障排除
### ❌ 服务器无法启动
- ✅ 检查 Python 版本：`python --version`（需要 3.10+）
- ✅ 验证 `.env` 中是否设置了所有环境变量
- ✅ 确保已安装依赖项：`pip install -r requirements.txt`
### 🔐 认证失败
- ✅ 验证 `.env` 中的 Auth0 凭证是否正确
- ✅ 检查 Auth0 中的重定向 URI 是否与 `{BASE_URL}/auth/callback` 匹配
- ✅ 确保 Auth0 API 中已配置作用域
### 🌐 Claude.ai 无法连接
- ✅ 验证服务器是否正在运行且可访问
- ✅ 检查基准 URL 是否正确
- ✅ 对于本地测试，确保 Claude.ai 可以访问 localhost（尝试 ngrok）
- ✅ 查看服务器日志中的认证错误
## 🔒 安全考虑
### 🚨 生产部署
1. 🔐 **仅使用 HTTPS**：生产环境中始终使用 HTTPS
2. 🔑 **环境变量**：永远不要将 `.env` 提交到版本控制
3. 🗝️ **安全密钥**：使用密钥管理器（AWS Secrets Manager、Azure Key Vault 等）
4. 💾 **令牌存储**：配置加密存储后端（带有加密的 Redis）
5. 🎫 **JWT 签名密钥**：在生产环境中设置显式 `jwt_signing_key`
6. ⏱️ **速率限制**：添加速率限制中间件
7. 📝 **日志记录**：实施综合审计日志
8. 🌐 **CORS**：配置特定来源（不允许 `*`）
### ⚙️ 生产配置```python
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'])
)
```
## 📚 参考
- 🚀 [FastMCP 文档](https://gofastmcp.com/)
- 🔐 [FastMCP OIDC 代理指南](https://gofastmcp.com/servers/auth/oidc-proxy)
- 📖 [模型上下文协议规范](https://spec.modelcontextprotocol.io/)
- 🔒 [OAuth 2.1 草案](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1)
- 🌐 [Auth0 文档](https://auth0.com/docs)
## 📄 许可证
MIT 许可证 - 随意使用此模板作为您自己的 MCP 服务器。
## 💬 支持
对于问题和疑问：
- 🚀 FastMCP：[GitHub Issues](https://github.com/jlowin/fastmcp/issues) | [Discord](https://discord.gg/prefect)
- 🌐 Auth0：[社区论坛](https://community.auth0.com/)
## 🤝 贡献
欢迎贡献！请随意提交拉取请求或打开问题以报告错误和功能请求。
---
<div align="center"
⭐ 如果您发现本仓库有帮助，请 ⭐ 本仓库！
使用 [FastMCP](https://gofastmcp.com/) 和 [Auth0](https://auth0.com/) 创建
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器