Gmail MCP Server

Gmail MCP 服务

此 MCP 服务通过模型上下文协议提供 Gmail 功能，让 Claude 等大模型能够与您的电子邮件交互。

功能

• 列出收件箱中的电子邮件
• 搜索特定电子邮件
• 阅读电子邮件内容
• 发送新电子邮件
• 回复现有电子邮件
• 删除单封电子邮件
• 一次批量删除多封电子邮件

设置

1. 安装依赖项：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. 设置 Google API 凭据：

   • 前往 Google Cloud Console
   • 创建新项目
   • 启用 Gmail API：
     • 在侧边栏中，前往“APIs & Services”>“Library”
     • 搜索“Gmail API”并选择它
     • 点击“Enable”
   • 创建 OAuth 2.0 凭据：
     • 在侧边栏中，前往“APIs & Services”>“Credentials”
     • 点击“Create Credentials”，然后选择“OAuth client ID”
     • 将应用类型选为“Desktop application”
     • 为 OAuth 客户端输入名称（例如，“Gmail MCP Server”）
     • 点击“Create”
     • 下载凭据 JSON 文件，并将其保存为项目根目录中的 credentials.json

3. 复制示例文件并创建 .env 文件：

   cp .env.example .env
   

4. 运行服务：

   • 首次运行服务时，会打开浏览器窗口进行身份验证
   • 按照提示授权应用访问您的 Gmail 账户

Gmail API 设置详解

了解凭据文件

1. credentials.json：

   • 此文件包含您在 Google Cloud 中的 OAuth 2.0 客户端凭据
   • 用于向 Google 的 OAuth 服务识别您的应用
   • 格式示例（您的应用所用的值会有所不同）：

     {
       "installed": {
         "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
         "project_id": "your-project-id",
         "auth_uri": "https://accounts.google.com/o/oauth2/auth",
         "token_uri": "https://oauth2.googleapis.com/token",
         "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
         "client_secret": "YOUR_CLIENT_SECRET",
         "redirect_uris": ["http://localhost"]
       }
     }
     

   • 您可以参考提供的 credentials.json.example

2. token.json：

   • 此文件会在首次身份验证时自动生成
   • 包含访问 Gmail 账户所需的 OAuth 令牌
   • 完成浏览器中的身份验证流程后，系统会创建此文件
   • 格式示例（您账户的令牌会有所不同）：

     {
       "token": "ya29.a0AfB_byC...",
       "refresh_token": "1//0eXxYz...",
       "token_uri": "https://oauth2.googleapis.com/token",
       "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
       "client_secret": "YOUR_CLIENT_SECRET",
       "scopes": [
         "https://www.googleapis.com/auth/gmail.readonly",
         "https://www.googleapis.com/auth/gmail.send",
         "https://www.googleapis.com/auth/gmail.compose",
         "https://www.googleapis.com/auth/gmail.modify"
       ],
       "expiry": "2025-03-05T14:30:00.000Z"
     }
     

身份验证流程

1. 首次运行服务时：

   • 服务会检查是否存在 token.json 文件
   • 如果未找到，服务将启动 OAuth 2.0 身份验证流程
   • 浏览器窗口会打开，提示您登录 Google 账户
   • 系统会要求您授予应用权限
   • 授予权限后，浏览器会显示成功消息
   • 服务会自动将令牌保存到 token.json

2. 后续运行时：

   • 服务会使用现有的 token.json 文件
   • 如果令牌已过期，系统会自动刷新
   • 刷新后的令牌会保存回 token.json

安全注意事项

• 妥善保管 credentials.json 和 token.json 文件
• 不要将这些文件提交到版本控制中
• .gitignore 文件已配置为排除这些文件
• 如果怀疑凭据已泄露，请在 Google Cloud Console 中撤销凭据并重新生成

用法

运行服务：

source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m src.server

如果默认端口（8000）已被占用，服务会自动查找可用端口。你可以在 .env 文件中配置首选主机、端口和路径：

SERVER_HOST=0.0.0.0   # The host address to bind to
SERVER_PORT=8000      # The preferred port (will use next available if busy)
SERVER_PATH=/mcp      # The URL path for the MCP server

在 claude_desktop_config.json 中添加此服务，以配置 Claude Desktop 使用它：

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/gmail-mcp-server"
    }
  }
}

可用工具函数

Gmail MCP Server 提供以下工具函数：

1. list_emails - 列出 Gmail 收件箱中的邮件

   • 参数：
     • max_results：要返回的邮件数量上限（默认值：10）
     • label：用于筛选的 Gmail 标签（默认值：INBOX）

2. get_email - 获取指定邮件的完整内容

   • 参数：
     • email_id：要检索的邮件 ID

3. search_emails - 搜索符合查询条件的邮件

   • 参数：
     • query：用于匹配邮件字段的搜索查询
     • max_results：要返回的结果数量上限（默认值：5）

4. send_email - 发送新邮件

   • 参数：
     • to：收件人邮箱地址
     • subject：邮件主题
     • body：邮件正文内容

5. reply_to_email - 回复现有邮件

   • 参数：
     • email_id：要回复的邮件 ID
     • body：回复内容

6. delete_email - 删除单封邮件

   • 参数：
     • email_id：要删除的邮件 ID

7. delete_emails - 通过批量操作删除多封邮件

   • 参数：
     • email_ids：要删除的邮件 ID 列表

设计理念

本项目遵循精简、高效的设计理念：

1. 代码精简，不添加冗余内容
2. 直接集成 Gmail API
3. 不使用模拟数据或不必要的抽象
4. 注重可靠性和性能

故障排除

服务端口问题

如果遇到服务端口问题：

1. 如果默认端口（8000）已被占用，服务会自动尝试查找可用端口
2. 查看控制台日志，确认实际使用的端口
3. 你可以在 .env 文件中手动指定其他端口
4. 确保 Claude Desktop 配置指向正确的端口

身份验证问题

如果遇到身份验证问题：

1. 检查 credentials.json 文件是否正确放置在项目根目录中
2. 如果 token.json 文件存在，请将其删除以强制重新进行身份验证
3. 确保 OAuth 客户端启用了正确的权限范围
4. 查看控制台日志，获取具体的错误消息

Gmail API 速率限制

Gmail API 的速率限制可能会影响使用：

• 每天 1,000,000,000 个配额单位
• 每种 API 方法消耗的配额单位各不相同
• 更多信息请参阅 Gmail API 配额