mcpgoogle (Applehawk)

MCP谷歌中心

适用于谷歌服务（Gmail、日历、云端硬盘）的FastMCP服务器 OMA 后端 用于集中OAuth 2.0管理的集成。

特性

• = 双重身份验证模式:

- OMA 后端 （推荐）：通过集中式后端实现服务器到服务器的OAuth - 本地文件 （遗留）：传统的基于文件的OAuth流

• =� Gmail工具：发送、阅读、搜索、修改消息
• =� 日历工具：查看即将发生的事件，创建事件
• =� 驱动工具：搜索、创建、更新、删除、共享文件
• = 自动令牌刷新：自动OAuth令牌刷新处理

建筑

�����������������         ������������������         �������������
  MCP Google Hub  ������>    OMA Backend     ������>    Google    
  (This Project)   OAuth    (Auth Server)     OAuth     APIs      
�����������������         ������������������         �������������
     FastMCP Server          Centralized OAuth           Gmail, Calendar
                             Token Management            Drive, etc.

OMA后端集成

OMA （OAuth管理和身份验证）后端提供：

• 集中式用户身份验证（JWT）
• Google OAuth流管理
• 安全加密令牌存储
• 多用户支持
• 自动令牌刷新

📊 详细文件：

• 建筑图（美人鱼） -可视化流程图
• 多用户架构 -多用户OAuth 2.0详细信息
• - 生产多用户部署
• 集成指南 -完整的集成文档
• 迁移摘要 -变更和迁移指南

安装

先决条件

• Python 3.12+
• OMA后端服务器正在运行（用于 oma_backend 模式）
• 具有OAuth凭据的谷歌云项目

设置

1. 克隆和安装依赖关系：

git clone 
cd mcpgoogle
pip install -e .

1. 配置环境：

cp .env.example .env
# Edit .env with your configuration

1. 选择身份验证模式：

选项A:OMA后端模式（推荐）

# .env
AUTH_MODE=oma_backend
OMA_BACKEND_URL=https://rndaibot.ru/api/v1
OMA_ACCESS_TOKEN=your_oma_access_token
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

如何获取OMA_ACCESS_TOKEN：

1. 导航到OMA后端web界面： https://rndaibot.ru
2. 使用您的帐户注册/登录
3. 通过web UI连接您的Google帐户
4. 从API响应或浏览器cookie复制您的访问令牌

选项B：本地文件模式（传统）

# .env
AUTH_MODE=local_file
GOOGLE_CREDENTIALS_PATH=secrets/credentials.google.json
GOOGLE_TOKEN_PATH=data/token.google.json

下载 credentials.json 从 谷歌云控制台.

用法

运行服务器

# Start the MCP server
python src/server.py

# Or with FastMCP CLI
fastmcp run src/server.py

服务器将在以下位置可用：

• MCP端点: http://localhost:8000/mcp/
• 健康检查: http://localhost:8000/health

卷曲快速测试

# List available tools
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

# Call a tool (list unread emails)
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "gmail_list_unread",
      "arguments": {"max_results": 5}
    }
  }'

OpenAI代理集成

from openai import OpenAI

client = OpenAI(api_key="your-api-key")

response = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "mcpgoogle",
        "server_url": "http://localhost:8000/mcp/",
        "require_approval": "never"
    }],
    input="Check my unread emails and summarize them"
)

print(response.output)

看 MCP_GUIDE.md 获取完整的集成示例和curl命令。

身份验证流程（OMA后端模式）

1. User logs in to OMA Backend web interface
   �> Receives JWT access_token

2. User connects Google account via web UI
   �> OMA Backend handles OAuth flow
   �> Stores encrypted Google credentials

3. MCP Google Hub requests credentials
   �> GET /api/v1/google/credentials
   �> Header: Authorization: Bearer {OMA_ACCESS_TOKEN}

4. OMA Backend returns Google OAuth tokens
   �> MCP Hub uses tokens to call Google APIs
   �> OMA Backend auto-refreshes expired tokens

配置参考

环境变量

谷歌身份验证

\*需要 AUTH_MODE=oma_backend \*\*需要 AUTH_MODE=local_file

MCP服务器配置

默认谷歌范围

[
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/drive",
]

项目结构

mcpgoogle/
�� src/
   �� __init__.py
   �� config.py              # Configuration management
   �� core.py                # FastMCP instance
   �� server.py              # Main server entry point
   �� auth/
      �� __init__.py
      �� google_auth.py     # Multi-mode Google auth
      �� oma_client.py      # OMA Backend client
   �� tools/
       �� __init__.py
       �� gmail_tool.py      # Gmail MCP tools
       �� calendar_tool.py   # Calendar MCP tools
       �� drive_tool.py      # Drive MCP tools
�� tests/
�� .env.example               # Environment configuration template
�� pyproject.toml             # Project dependencies
�� README.md                  # This file

API 参考

Gmail工具

• gmail_send_message(to, subject, body, cc=None, bcc=None) -发送电子邮件
• gmail_list_unread(max_results=10) -列出未读邮件
• gmail_search_messages(query, max_results=10) -搜索邮件
• gmail_get_message(message_id) -获取消息详细信息
• gmail_mark_as_read(message_id) -将邮件标记为已读
• gmail_modify_message(message_id, add_labels=[], remove_labels=[]) -修改标签

日历工具

• calendar_upcoming(max_results=10, time_min=None) -获取即将举行的活动

驱动工具

• drive_search(query, max_results=10) -搜索文件
• drive_create_file(name, content, mime_type, folder_id=None) -创建文件
• drive_update_file(file_id, content) -更新文件内容
• drive_delete_file(file_id) -删除文件
• drive_share_file(file_id, email, role='reader') -共享文件
• drive_download_file(file_id) -下载文件内容

安全最佳实践

OMA 后端模式

 推荐用于生产

• 集中式凭证管理
• 后端加密令牌存储
• 没有本地凭据文件
• 多用户支持
• 自动令牌刷新
• 审计日志记录（在OMA后端）

本地文件模式

� 仅用于开发

• 存储在本地文件中的凭据
• 需要手动OAuth流
• 仅限单个用户
• 生产安全性较低

MCP端点

服务器公开以下MCP端点：

• POST/mcp/ -主MCP端点（JSON-RPC 2.0）

- tools/list -列出具有模式的可用工具 - tools/call -带参数的执行工具

• GET/健康 -健康检查端点

可用工具

• gmail_list_unread -列出未读电子邮件
• gmail_search_messages -按查询搜索电子邮件
• gmail_get_message -按ID获取电子邮件内容
• gmail_send_message -使用可选的CC/BCC发送电子邮件
• gmail_mark_as_read -将电子邮件标记为已读
• gmail_modify_message -修改电子邮件标签
• calendar_upcoming -获取即将到来的日历活动

故障排除

MCP服务器问题

服务器无法启动：

# Install dependencies
pip install -e .

# Check configuration
python -c "from src import config; config.validate_config()"

401未经授权（MCP端点）：

• 禁用身份验证：设置 MCP_AUTH_TOKEN= 在 .env
• 或包括： Authorization: Bearer your-token 头球

CORS错误：

# Allow all origins (dev)
MCP_CORS_ORIGINS=*

# Specific domains (prod)
MCP_CORS_ORIGINS=https://api.openai.com,https://yourapp.com

Google OAuth问题

错误：“OMA_ACCESS_TOKEN环境变量是必需的”

在中设置OMA访问令牌 .env:

# Login to OMA Backend first
curl -X POST https://rndaibot.ru/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

# Copy access_token from response to .env
OMA_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

错误：“Google帐户未连接”

通过OMA后端web界面连接Google帐户：

1. 引导到 https://rndaibot.ru
2. 使用您的帐户登录
3. 前往设置→ 谷歌集成
4. 点击“连接谷歌账户”
5. 授权Google OAuth流

错误：“身份验证方案无效”

确保 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 与OMA后端中配置的凭据匹配。

发展

运行测试

pytest tests/

代码格式化

ruff check src/
ruff format src/

文档

• MCP_GUIDE.md -完整的OpenAI代理集成指南，附带curl示例
• 建筑\_ IAGRAMS.md -可视化流程图
• **** -生产部署指南
• 集成.md -完整的集成文档

相关项目

• OMA 后端：OAuth管理和身份验证服务器

- 存储库： oma-backend/ - API文件： https://rndaibot.ru/api/docs

• 前端：Next.js web界面

- 存储库： openai-realtime-agents/ - 网址： https://rndaibot.ru

外部资源

• MCP规范
• FastMCP文档
• OpenAI代理SDK

许可证

\[您的许可证\]

贡献

\[贡献指南\]