Gmail MCP Server

Gmail MCP 服务

一个基于 Java 的 Model Context Protocol（MCP）服务，可与 Gmail 集成，让用户通过 Claude Desktop 使用自然语言查询电子邮件。该服务提供按主题（例如“项目截止日期”）搜索邮件和读取邮件内容的工具，并使用 Gmail API 和安全的 OAuth2 身份验证。

功能

• 搜索邮件：使用 Gmail 的查询语法按主题、发件人或日期查找邮件（例如，from:alice budget）。
• 读取邮件：按 ID 获取完整的邮件内容（主题、发件人、正文）。
• 安全身份验证：使用 gmail.readonly 范围，最大限度地减少访问权限。
• MCP 集成：通过 Stdio 使用 JSON-RPC 2.0 与 Claude Desktop 通信。
• 稳健设计：包含错误处理、日志记录和输入验证，可满足生产环境使用需求。

先决条件

• Java 17：确保已安装 JDK 17（java --version）。
• Maven：用于依赖项管理（mvn --version）。
• Google Cloud 项目：已启用 Gmail API 并配置 OAuth2 凭据。
• Claude Desktop：已安装并配置 MCP（可从 Anthropic 获取）。
• 操作系统：已在 Windows、macOS 和 Linux 上测试。

设置说明

1. 创建 Google Cloud 凭据

1. 前往 Google Cloud Console。
2. 创建新项目（例如，“Gmail MCP Server”）。
3. 启用 Gmail API：
   • 前往 APIs & Services > Library。
   • 搜索“Gmail API”，然后点击 Enable。
4. 创建 OAuth 2.0 凭据：
   • 前往 APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client IDs。
   • 将应用类型选为 Desktop app。
   • 为客户端命名（例如，“Gmail MCP Client”）。
   • 下载 credentials.json 文件。
5. 将 http://localhost 添加到授权重定向 URI：
   • 在 Credentials 中，编辑 OAuth 2.0 Client ID，并在 Authorized redirect URIs 下添加 http://localhost。

2. 克隆或设置项目

1. 克隆仓库（或创建新的 Maven 项目）：

   git clone <repository-url>
   cd gmail-mcp-server
   

   或者，创建新的 Maven 项目并复制提供的文件：
   • src/main/java/com/swiftbeard/gmailmcp/GmailMcpServer.java
   • pom.xml
   • src/main/resources/credentials.json（来自 Google Cloud）
   • src/main/resources/logback.xml
2. 将 credentials.json 放入 src/main/resources/。
3. 验证项目结构：

   gmail-mcp-server/
   ├── pom.xml
   ├── src/
   │   ├── main/
   │   │   ├── java/
   │   │   │   └── com/swiftbeard/gmailmcp/
   │   │   │       └── GmailMcpServer.java
   │   │   ├── resources/
   │   │   │   ├── credentials.json
   │   │   │   └── logback.xml
   

3. 构建项目

1. 安装依赖项并构建项目：

   mvn clean install
   

2. 构建过程会生成一个包含依赖项的 JAR：target/gmail-mcp-server-1.0-SNAPSHOT.jar。

4. 运行服务

1. 启动服务：

   java -jar target/gmail-mcp-server-1.0-SNAPSHOT.jar
   

2. 首次运行时，服务会打开浏览器以进行 OAuth2 身份验证：
   • 使用你的 Gmail 账号登录。
   • 授予应用读取邮件的权限（使用 gmail.readonly 范围）。
   • 令牌会保存到 ~/.gmail-mcp/tokens，供后续运行使用。
3. 服务以 Stdio 模式运行，等待来自 Claude Desktop 的 MCP 请求。

5. 配置 Claude Desktop

1. 从 Anthropic 网站安装 Claude Desktop。
2. 找到或创建 MCP 配置文件（例如，~/.cursor/mcp.json 或 Claude 的设置文件）。
3. 添加 Gmail MCP 服务配置：

   {
     "mcpServers": {
       "gmail": {
         "command": "java",
         "args": ["-jar", "/full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar"]
       }
     }
   }
   

   将 /full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar 替换为你的 JAR 文件的绝对路径（例如，/home/user/gmail-mcp-server/target/gmail-mcp-server-1.0-SNAPSHOT.jar）。
4. 保存文件并重启 Claude Desktop。

6. 测试集成

1. 打开 Claude Desktop。
2. 输入自然语言查询，例如：

   Find emails about project deadlines from the last 30 days.
   

3. Claude 会将其转换为 searchEmails 工具调用（例如，query: "project deadlines after:2025-03-26"）。服务会返回邮件列表：

   [
     {"id": "abc123", "subject": "Project Deadlines Update", "snippet": "Please review the June 1 deadline..."},
     {"id": "def456", "subject": "Q2 Deadlines", "snippet": "Deadlines for Project X..."}
   ]
   

4. 接着询问：

   Read the email with ID abc123.
   

5. 服务会执行 readEmail("abc123") 并返回：

   {
     "id": "abc123",
     "subject": "Project Deadlines Update",
     "from": "[email protected]",
     "body": "Hi team, please review the June 1 deadline for Project X..."
   }
   

6. Claude 会用自然语言总结结果。

使用示例

• 按主题搜索：

  Show me emails about budget approvals from last month.
  

  对应：searchEmails("budget approvals after:2025-03-01 before:2025-04-01")。
• 按发件人搜索：

  Find emails from [email protected] about conference planning.
  

  对应：searchEmails("from:[email protected] conference planning")。
• 阅读特定邮件：

  Read the email with ID xyz123.
  

  对应：readEmail("xyz123")。

最佳实践

• 安全性：
  • 使用最小权限范围 gmail.readonly 来限制访问。
  • 将 OAuth2 令牌安全地存储在 ~/.gmail-mcp/tokens 中（不纳入版本控制）。
  • 验证输入以防止注入攻击。
• 错误处理：
  • 对无效请求或 API 调用失败返回 JSON-RPC 错误响应。
  • 使用 SLF4J/Logback 记录错误，以便调试。
• 性能：
  • 将搜索结果限制为 10 封邮件，以遵守 Gmail API 的速率限制（每分钟 250 次查询）。
  • 使用 Jackson 高效解析 JSON。
• 可维护性：
  • 采用模块化代码，将 Gmail 逻辑与 MCP 逻辑分开。
  • 提供全面的日志记录，以便监控。

故障排除

• 身份验证错误：
  • 确保 credentials.json 位于 src/main/resources/ 中。
  • 如果令牌无效，请删除 ~/.gmail-mcp/tokens 并重新进行身份验证。
• 服务未响应：
  • 确认 mcp.json 中的 JAR 路径正确。
  • 检查控制台日志中的错误。
• Claude Desktop 问题：
  • 确保 Claude Desktop 已更新至最新版本。
  • 确认 MCP 配置文件的格式正确。
• Gmail API 速率限制：
  • 如果达到速率限制，请降低查询频率或实现指数退避。

安全注意事项

• 凭据：将 credentials.json 和 ~/.gmail-mcp/tokens 添加到 .gitignore，以防意外提交。
• OAuth2：使用 offline 访问类型来持久保存令牌；请在 Google Cloud Console 中检查是否存在异常活动。
• 权限范围：仅限于 gmail.readonly，以防止未经授权的操作。

扩展服务

• 添加工具：扩展 GmailMcpServer.java，加入 labelEmail 或 sendEmail 等工具（需要额外的权限范围）。
• 远程托管：修改为使用 SSE 或 WebSockets 进行云部署（例如，使用 Spring WebFlux）。
• 缓存：使用 Caffeine 等内存存储，为经常搜索的查询实现缓存。

贡献

欢迎贡献！请：

1. Fork 此代码库。
2. 创建功能分支（git checkout -b feature/xyz）。
3. 提交更改（git commit -m "Add XYZ feature"）。
4. 推送到该分支（git push origin feature/xyz）。
5. 发起拉取请求。

许可证

MIT 许可证。详情请参阅 LICENSE。

致谢

• 基于 Google Gmail API 和 Anthropic MCP 构建。
• 灵感来自 GongRzhe 的 Gmail MCP Server 等社区 MCP 服务。

如有问题或疑问，请提交 GitHub issue 或联系维护者。