Gmail MCP Server

Gmail MCP 服务

使用 FastMCP（模型控制协议）集成 Gmail，让 AI 助手能够通过一组工具和提示词与 Gmail 交互。

概述

此项目提供了一种服务端-客户端架构，允许 AI 助手执行 Gmail 操作，例如：

• 发送邮件
• 查看未读邮件
• 查看邮件内容
• 将邮件移至垃圾箱
• 在浏览器中打开邮件
• 将邮件标记为已读

系统使用 Google 的 OAuth 2.0 进行身份验证，并通过 Gmail API 执行邮件操作。现在还包含一个由大模型驱动的客户端，可理解自然语言请求。

组件

1. Gmail 服务端（gmail_server.py）

提供 Gmail 操作 MCP 工具的核心服务端：

• FastMCP 集成：使用 FastMCP 框架将 Gmail 操作作为工具公开
• OAuth 身份验证：处理 Gmail API 身份验证、令牌管理和刷新
• 邮件操作：实现邮件发送、读取和管理功能
• 提示词：包含用于邮件起草和管理的专用提示词

2. 智能 Gmail 客户端（test_gmail_server.py）

Gmail 服务端的自然语言界面：

• 大模型集成：使用 Google 的生成式 AI（Gemini）理解用户请求
• 自然语言理解：将普通英语请求转换为工具调用
• 参数提取：自动从用户查询中提取所需参数
• 交互式界面：提供用于管理邮件的对话体验
• 全面日志记录：包含详细日志，便于调试通信过程

设置和要求

前置条件

• Python 3.6+
• Gmail API 凭据（用于 Gmail 身份验证）
• Google 生成式 AI API 密钥（用于大模型驱动的客户端）
• requirements.txt 中的包：

  google-auth>=2.22.0
  google-auth-oauthlib>=1.0.0
  google-api-python-client>=2.95.0
  fastmcp>=0.1.0
  typing-extensions>=4.5.0
  google-generativeai>=0.1.0
  python-dotenv>=0.19.0
  

克隆后的初始设置

1. 安装依赖项：

   pip install -r requirements.txt
   

2. 设置 Gmail API 凭据：

   • 前往 Google Cloud Console
   • 创建新项目或选择现有项目
   • 为项目启用 Gmail API
   • 创建 OAuth 2.0 凭据（桌面客户端类型）
   • 下载凭据 JSON 文件
   • 将其重命名为 credentials.json，并放在项目根目录中

3. 设置 Gemini API 密钥：

   • 前往 Google AI Studio
   • 创建新的 API 密钥
   • 根据 example.env 模板创建 .env 文件：

     cp example.env .env
     

   • 将 Gemini API 密钥添加到 .env 文件中：

     GOOGLE_API_KEY=your_api_key_here
     

4. 首次运行时将生成令牌：

   • 首次运行 Gmail 服务端时，会打开一个浏览器窗口
   • 登录 Google 账号并授予所请求的权限
   • 这会生成 token.json 文件，供后续身份验证使用

身份验证文件

系统需要多个身份验证文件：

• credentials.json：Google Cloud Console 中用于 Gmail API 的 OAuth 客户端 ID 凭据
• token.json：用于已通过身份验证的 Gmail 访问的生成令牌文件
• .env：包含 Google 生成式 AI API 密钥的环境变量文件

使用方法

启动 Gmail 服务端

启动 Gmail 服务端：

python gmail_server.py --creds credentials.json --token token.json

服务端提供以下工具：

• send_email：发送邮件，包含收件人、主题和正文
• get_unread_emails：获取未读邮件
• read_email：获取指定邮件的内容
• trash_email：将邮件移至垃圾箱
• open_email：在浏览器中打开邮件
• mark_email_as_read：将邮件标记为已读

使用智能 Gmail 客户端

智能客户端允许你使用自然语言与 Gmail 交互：

python test_gmail_server.py

示例命令：

• “给 [recipient] 发送一封关于 [topic] 的邮件”
• “检查我的未读邮件”
• “阅读我最近收到的邮件”
• “在浏览器中打开最新邮件”
• “将来自 [sender] 的邮件移至垃圾箱”
• “将我的未读邮件标记为已读”

客户端将：

1. 使用大模型处理你的请求
2. 判断你想执行哪项 Gmail 操作
3. 从你的请求中提取必要参数
4. 请求补充任何缺失的信息
5. 在执行敏感操作前进行确认
6. 执行操作并显示结果

实现细节

邮件内容处理

• 支持解析和解码 MIME 消息
• 处理多部分消息和附件
• 正确解码邮件标头

大模型集成

• 使用 Gemini 1.5 Flash 进行自然语言理解
• 将大模型响应转换为结构化工具调用
• 包含处理格式错误的大模型响应的回退机制
• 从自由文本中提取参数

错误处理

• 在整个应用程序中进行全面日志记录
• 妥善处理 Gmail API 的 HTTP 错误
• 在大模型响应格式不符合预期时使用回退机制
• 为客户端应用提供清晰的错误响应

开发

扩展智能客户端

若要支持新的 Gmail 操作：

1. 在 gmail_server.py 中添加相应的工具实现
2. 智能客户端会自动发现并开放新工具
3. 大模型会根据工具描述学会理解针对新操作的请求

自定义大模型集成

你可以修改 test_gmail_server.py 中的大模型提示词，以便：

• 改进特定用例的参数提取
• 针对特定类型的请求添加专门的处理方式
• 根据你的 Gmail 使用模式调整系统

安全说明

此代码库不包含凭据文件。切勿提交以下文件：

• credentials.json 文件
• token.json 文件
• 包含 API 密钥的 .env 文件

这些文件已列入 .gitignore 文件，以防止意外提交敏感信息。

参考

https://medium.com/@jason.summer/create-a-gmail-agent-with-model-context-protocol-mcp-061059c07777