AI导哈

Gmail邮件管理服务

通过Model Context Protocol提供Gmail功能访问，允许LLMs如Claude与您的电子邮件进行交互。

  • by Imsharad
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Imsharad/gmail-mcp-server

使用说明

Gmail MCP服务器

此MCP服务器通过模型上下文协议提供对Gmail功能的访问，允许像Claude这样的LLM与您的电子邮件进行交互。

特性

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

设置

  1. 安装依赖项：

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

  2. 设置Google API凭据：

    • 转到 谷歌云控制台
    • 创建新项目
    • 启用Gmail API：
      • 在侧栏中，导航到“API和服务”>“库”
      • 搜索“Gmail API”并选择它
      • 点击“启用”
    • 创建OAuth 2.0凭据：
      • 在侧栏中，导航到“API和服务”>“凭据”
      • 点击“创建凭据”并选择“OAuth客户端ID”
      • 选择“桌面应用程序”作为应用程序类型
      • 输入OAuth客户端的名称（例如，“Gmail MCP服务器”）
      • 点击“创建”
      • 下载凭据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身份验证流程
    • 浏览器窗口将打开，要求您登录您的谷歌帐户
    • 系统将要求您授予应用程序权限
    • 授予权限后，浏览器将显示成功消息
    • 服务器将自动将令牌保存到 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添加到您的 claude_desktop_config.json:

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

可用工具功能

Gmail MCP服务器提供以下工具功能：

  1. list_邮件 -列出Gmail收件箱中的电子邮件

    • 参数：
      • max_results：要返回的最大电子邮件数（默认值：10）
      • label：要筛选的Gmail标签（默认：收件箱）

  2. get_email -获取特定电子邮件的完整内容

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

  3. 搜索邮件 -搜索与查询匹配的电子邮件

    • 参数：
      • query：搜索查询以匹配电子邮件字段
      • max_results：要返回的最大结果数（默认值：5）

  4. send_邮件 -发送新电子邮件

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

  5. 回复_发送_邮件 -对现有电子邮件的回复

    • 参数：
      • email_id：要回复的电子邮件的ID
      • body：回复消息内容

  6. 删除电子邮件 -删除一封电子邮件

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

  7. 删除电子邮件 -在批处理操作中删除多封电子邮件

    • 参数：
      • 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有可能影响使用的速率限制：

  • 每天1000000000个配额单位
  • 每个API方法使用不同的配额单位
  • 有关更多信息，请参阅 Gmail API配额

相关 MCP