Gmail MCP 服务器

一个与 FastMCP (模型控制协议) 集成的 Gmail，使 AI 助手能够通过一系列工具和提示与 Gmail 交互。

概述

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

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

该系统使用 Google 的 OAuth 2.0 进行身份验证，并使用 Gmail API 进行电子邮件操作。现在它包含一个由 LLM 驱动的客户端，可以理解自然语言请求。

组件

1. Gmail 服务器 (gmail_server.py)

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

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

2. 智能 Gmail 客户端 (test_gmail_server.py)

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

• LLM 集成: 使用 Google 的生成式 AI (Gemini) 来解释用户请求
• 自然语言理解: 将纯英语请求转换为工具调用
• 参数提取: 自动从用户查询中提取所需参数
• 交互式界面: 提供用于管理电子邮件的对话式体验
• 全面日志记录: 包括用于调试通信的详细日志记录

设置和要求

前提条件

• Python 3.6+
• Gmail API 凭据（用于 Gmail 身份验证）
• Google Generative AI API 密钥（用于 LLM 驱动的客户端）
• 来自 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 的 OAuth 客户端 ID 凭据，用于 Gmail API
• token.json: 生成的令牌文件，用于经过身份验证的 Gmail 访问
• .env: 包含您的 Google Generative 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

示例命令：

• "Send an email to [recipient] about [topic]" (向 [收件人] 发送关于 [主题] 的电子邮件)
• "Check my unread emails" (检查我的未读邮件)
• "Read my most recent message" (阅读我最近的消息)
• "Open the latest email in browser" (在浏览器中打开最新的电子邮件)
• "Move an email from [sender] to trash" (将来自 [发件人] 的电子邮件移至垃圾箱)
• "Mark my unread emails as read" (将我的未读邮件标记为已读)

客户端将：

1. 使用 LLM 处理您的请求
2. 确定您要执行的 Gmail 操作
3. 从您的请求中提取必要的参数
4. 请求任何缺失的信息
5. 在执行敏感操作之前确认
6. 执行操作并向您显示结果

实现细节

电子邮件内容处理

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

LLM 集成

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

错误处理

• 整个应用程序中的全面日志记录
• 优雅地处理来自 Gmail API 的 HTTP 错误
• 当 LLM 响应未按预期格式化时的后备机制
• 客户端应用程序的清晰错误响应

开发

扩展智能客户端

要添加对新 Gmail 操作的支持：

1. 在 gmail_server.py 中添加适当的工具实现
2. 智能客户端将自动发现并公开新工具
3. LLM 将学习从工具描述中理解对新操作的请求

自定义 LLM 集成

您可以修改 test_gmail_server.py 中的 LLM 提示以：

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

安全提示

此存储库不包含凭据文件。 永远不要提交您的：

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

这些文件包含在 .gitignore 文件中，以防止意外提交敏感信息。

参考

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