Gmail MCP 服务器

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

功能

• 列出收件箱中的电子邮件
• 搜索特定电子邮件
• 阅读电子邮件内容
• 发送新电子邮件
• 回复现有电子邮件

设置

1. 安装依赖项：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   pip install -r requirements.txt
   

2. 设置 Google API 凭据：

   • 转到 Google Cloud Console
   • 创建一个新项目
   • 启用 Gmail API：
     • 在侧边栏中，导航到“API 和服务”>“库”
     • 搜索“Gmail API”并选择它
     • 点击“启用”
   • 创建 OAuth 2.0 凭据：
     • 在侧边栏中，导航到“API 和服务”>“凭据”
     • 点击“创建凭据”并选择“OAuth 客户端 ID”
     • 选择“桌面应用程序”作为应用程序类型
     • 输入 OAuth 客户端的名称（例如，“Gmail MCP Server”）
     • 点击“创建”
     • 下载凭据 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  # 在 Windows 上：venv\Scripts\activate
python -m src.server

通过将其添加到您的 claude_desktop_config.json 来配置 Claude Desktop 以使用此服务器：

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

设计理念

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

1. 代码最少，没有膨胀
2. 与 Gmail API 直接集成
3. 没有模拟数据或不必要的抽象
4. 专注于可靠性和性能

故障排除

身份验证问题

如果您遇到身份验证问题：

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

Gmail API 速率限制

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

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