MCPClient Server Oauth

MCP 客户端/服务器 OAuth 项目

一个使用FastMCP框架的Python项目，演示了通过Google OAuth认证实现的模型上下文协议（MCP）客户端-服务器通信。

项目结构

MCPClient_Server_Oauth/
├── MCPServer/          # MCP Server implementation with OAuth
│   ├── .venv/         # Server virtual environment
│   ├── .env           # OAuth credentials (not in git)
│   ├── pyproject.toml # Server dependencies
│   └── main.py        # Server entry point with GoogleProvider
│
├── MCPClient/          # MCP Client implementation
│   ├── .venv/         # Client virtual environment
│   ├── pyproject.toml # Client dependencies
│   └── main.py        # Client entry point with OAuth flow
│
└── Documentation/
    ├── CLAUDE.md              # Development guide
    ├── HOW_UV_WORKS.md        # UV detection algorithm explained
    ├── UV_GUIDE.md            # UV quick reference
    └── test_uv_detection.sh   # UV demonstration script

特点/功能

• Google OAuth 认证使用Google OAuth 2.0进行安全认证
• MCP协议通过模型上下文协议进行工具发现和远程调用
• FastMCP 框架基于FastMCP 2.12.5+构建，便于服务器/客户端开发
• 隔离环境为服务器组件和客户端组件分别设置虚拟环境

快速入门

先决条件

• Python 3.12及以上版本
• UV包管理器（pip install uv 或者参见 https://docs.astral.sh/uv/）
• Google Cloud Console OAuth 凭据

1. 设置Google OAuth

在成功使用 Google OAuth 提供商运行 MCP 服务器之前，请按照以下步骤操作：

创建OAuth凭据

1. 在 Google Cloud 中创建一个项目

- 首选 Google Cloud 控制台 - 创建一个新项目或选择一个现有项目

1. 配置OAuth授权屏幕

- 导航至 APIs（应用程序编程接口）与服务 - 点击 OAuth授权屏幕 在左侧面板中 - 选择 外部的 作为用户类型（允许任何Gmail账户进行验证） - 填写所有必填信息： - 应用名称 - 用户支持邮箱 - 开发人员联系方式 - 点击 保存并继续 - 如需，请添加范围（这些范围在MCP客户端中设置） - 选择这些范围 - OpenID（开放唯一标识符） - https://www.googleapis.com/auth/userinfo.email 的中文翻译可以是：“获取用户电子邮件地址的权限”。 - https://www.googleapis.com/auth/userinfo.profile 翻译为中文是：“https://www.googleapis.com/auth/用户信息.个人资料”（注：这里的“用户信息.个人资料”是根据语境对“userinfo.profile”的一种解释性翻译，实际在技术文档中可能直接保留为“userinfo.profile”或根据具体上下文调整）。不过，为了更贴合技术文档的表达习惯，我们也可以简化为“Google API 用户资料信息授权”。但直接翻译网址部分时，通常保留原样，因为网址是特定的标识符，不直接翻译。所以，更准确的表述是，该网址代表的是“Google 用户信息 API 中的个人资料授权” - 如需添加测试用户（可选） - 完成同意屏幕设置

1. 创建OAuth 2.0客户端ID

- 回到 应用程序编程接口（API）与服务 - 点击 凭证；资历；资格 在左侧面板中 - 点击 创建凭据 → OAuth 2.0 客户端ID - 选择 网络应用程序 作为应用类型 - 为您的OAuth客户端选择一个名称

1. 配置授权来源和重定向URI

- 在...之下 授权的JavaScript来源，补充：

     http://localhost:8000
     http://127.0.0.1:8000

- 在……之下 授权重定向URI，补充：

     http://localhost:8000/auth/callback
     http://127.0.0.1:8000/auth/callback

1. 保存凭据

- 点击 创建 - 保存你的 客户端ID 并且 客户端密钥 （你需要这些来 .env 文件)

配置服务器环境

创建一个 .env 文件在（文件夹/目录中） MCPServer/ 目录：

cd MCPServer
cat > .env << EOF
# Google OAuth client credentials (from Google Cloud Console)
GOOGLE_CLIENT_ID=your-client-id-here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret-here
EOF

重要的替换 your-client-id-here 并且 your-client-secret-here 使用您在 Google Cloud Console 中的实际凭据。

2. 安装依赖项

# Install server dependencies
cd MCPServer
uv sync

# Install client dependencies
cd ../MCPClient
uv sync

3. 运行服务器

cd MCPServer
uv run python main.py

你应该看到：

Starting MCP server on http://localhost:8000
MCP path: http://localhost:8000/mcp
Redirect path: http://localhost:8000/auth/callback

4. 运行客户端

在一个新终端中：

cd MCPClient
uv run python main.py

OAuth 流程将开始：

1. 一个浏览器窗口打开，显示Google登录界面
2. 使用您的谷歌账户进行身份验证
3. 授予应用程序权限
4. 浏览器重定向回服务器
5. 客户端成功连接并列出可用工具

预期输出：

🔐 OAuth authentication successful!

Available tools:
...

Tool result: Hello, world!

可用工具

服务器提供了以下MCP工具：

• 你好，世界返回一个简单的问候信息
• 获取天气返回指定城市的天气信息

客户端示例用法：

# Call hello_world tool
result = await client.call_tool("hello_world")

# Call get_weather tool with parameters
result = await client.call_tool("get_weather", {"city": "New York"})

配置

服务器配置（MCPServer/main.py）

服务器可以通过环境变量或（通过）配置文件进行配置 .env 文件：

BASE_URL = "http://localhost:8000"              # Server base URL
REDIRECT_PATH = "/auth/callback"                # OAuth callback path
MCP_PATH = "/mcp"                               # MCP endpoint path
REQUIRED_SCOPES = [                             # Required OAuth scopes
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/userinfo.profile"
]
ALLOWED_CLIENT_REDIRECT_URIS = [                # Client callback patterns
    "http://localhost:*",
    "http://127.0.0.1:*"
]

客户端配置（MCPClient/main.py）

客户端使用OAuth连接到服务器：

# Simple OAuth (recommended)
client = Client("http://localhost:8000/mcp", auth="oauth")

# Custom OAuth with specific scopes
oauth = OAuth(
    mcp_url="http://localhost:8000/mcp",
    scopes=["openid", "email", "profile"]
)
client = Client("http://localhost:8000/mcp", auth=oauth)

关键概念

OAuth 流程

1. 客户端初始化客户端使用MCP服务器URL创建OAuth实例
2. 授权请求客户端将用户重定向到谷歌登录页面
3. 用户身份验证用户登录并授予权限
4. 回调处理Google 重定向到服务器的 /auth/callback
5. 代币兑换服务器用授权码交换访问令牌
6. 认证连接客户端使用令牌进行MCP通信

虚拟环境管理

每个组件都有其独立的虚拟环境：

• MCPServer/.venv（可翻译为：“MCPServer项目的虚拟环境目录”或根据上下文简化为“MCPServer虚拟环境”，其中“.venv”通常表示Python的虚拟环境目录）服务器依赖项（FastMCP、python-dotenv、Google认证）
• MCPClient/.venv（可翻译为）：MCP客户端/虚拟环境目录客户端依赖项（FastMCP 客户端库）

UV自动检测哪个 .venv 根据您当前的目录来使用。参见 HOW_UV_WORKS.md 翻译为中文是：“UV是如何工作的.md” 或者更自然地表达为：“UV的工作原理.md” 详情请参阅。

MCP协议

模型上下文协议支持：

• 工具发现列出可用的工具及其架构
• 远程调用使用类型化参数调用工具
• 结构化响应接收格式化结果
• 认证通过OAuth 2.0实现安全访问

文档

• CLAUDE.md（文件名或标题，直接翻译为“克劳德.md”，其中“.md”通常表示这是一个Markdown格式的文件）完整开发指南：如何与该代码库协同工作
• HOW_UV_WORKS.md 的中文翻译是：“UV的工作原理.md” 或者更流畅地表达为：“UV如何工作.md”（注：这里的“md”通常表示Markdown格式的文件，但在中文语境下，我们通常不会直接翻译“md”，因为它是一个特定的文件格式标识，保持原样即可）对UV的venv检测的详细解释
• UV_GUIDE.md 翻译为中文是：“UV指南.md”（其中，“md”通常表示Markdown文件格式）UV命令快速参考

常用命令

# Server
cd MCPServer
uv sync                    # Install/update dependencies
uv run python main.py      # Run server with OAuth

# Client
cd MCPClient
uv sync                    # Install/update dependencies
uv run python main.py      # Run client (triggers OAuth flow)

# Health check
curl http://localhost:8000/healthz

# Test UV detection
./test_uv_detection.sh

故障排除

浏览器中的“ERR_UNSAFE_REDIRECT”

原因在 Google Cloud Console 中未授权 OAuth 重定向 URI

解决方案：

1. 前往 Google Cloud Console → 凭据
2. 编辑您的OAuth 2.0客户端ID
3. 添加 http://localhost:8000/auth/callback 到授权重定向URI
4. 等待5-10分钟，以便更改生效

“GOOGLE_CLIENT_ID 或 GOOGLE_CLIENT_SECRET 未设置”

原因缺失或错误 .env 文件位于MCPServer/目录下

解决方案:

1. 创建 .env 文件存入 MCPServer/ 目录
2. 添加您的Google OAuth凭据（参见 设置Google OAuth）
3. 验证客户端密钥中没有重复的前缀（应该是 GOCSPX-...，不是 GOCSPX-GOCSPX-...)

客户端连接失败

原因服务器未运行或URL错误

解决方案：

1. 确保服务器正在运行于 http://localhost:8000
2. 检查服务器日志中的错误
3. 验证客户端是否连接到正确的MCP端点http://localhost:8000/mcp）

安全注意事项

• 永远不要承诺 .env 文件OAuth凭据应保持私密
• 在生产环境中使用HTTPSOAuth 应该使用安全连接
• 轮换凭据定期更新OAuth客户端密钥
• 限制范围仅请求必要的OAuth范围

依赖项

服务器（MCPServer/pyproject.toml）

• FastMCP (≥2.12.5): 支持OAuth的MCP服务器框架
• python-dotenv环境变量管理
• 谷歌身份验证OAuth 提供者集成

客户端（MCPClient/pyproject.toml）

• FastMCP (≥2.12.5)：带有OAuth流程的MCP客户端库

依赖项通过 pyproject.toml 并且 uv.lock 文件。

发展

见 CLAUDE.md（文件名，可译为“克劳德.md”或保持原样，具体根据上下文决定是否翻译文件名） for：对于；为了；因为；给；给……的

• 建筑细节
• 开发工作流程
• 测试程序
• 最佳实践

许可证

\[在此添加您的许可证\]