AI导哈

Gmail邮件查询服务

一个基于Java的MCP服务器，集成Gmail API，通过自然语言查询搜索和读取邮件内容，适用于需要高效邮件管理的场景。

  • by gemacjr
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 gemacjr/mcp-gmail-server

使用说明

Gmail MCP服务器

基于Java的模型上下文协议（MCP）服务器，与Gmail集成，通过Claude Desktop实现自然语言电子邮件查询。服务器使用带有安全OAuth2身份验证的Gmail API，公开按主题（例如“项目截止日期”）搜索电子邮件和阅读电子邮件内容的工具。

特性

  • 搜索电子邮件：使用Gmail的查询语法按主题、发件人或日期查找电子邮件（例如。， from:alice budget).
  • 阅读电子邮件：按ID检索完整的电子邮件内容（主题、发件人、正文）。
  • 安全认证：将OAuth2与 gmail.readonly 最小访问范围。
  • MCP集成：使用JSON-RPC 2.0通过Stdio与Claude Desktop通信。
  • 稳健设计：包括错误处理、日志记录和生产就绪的输入验证。

先决条件

  • Java 17：确保安装了JDK 17(java --version).
  • 梅文：用于依赖关系管理(mvn --version).
  • 谷歌云项目：启用Gmail API和OAuth2凭据。
  • 克劳德桌面：已安装并配置MCP（可从Anthropic获得）。
  • 操作系统：在Windows、macOS和Linux上进行了测试。

安装说明

1.创建Google Cloud凭据

  1. 转到 谷歌云控制台.
  2. 创建一个新项目（例如“Gmail MCP服务器”）。
  3. 启用Gmail API：
    • 引导到 API和服务>库.
    • 搜索“Gmail API”并点击 启用.
  4. 创建OAuth 2.0凭据：
    • 首选 API和服务>凭据>创建凭据>OAuth 2.0客户端ID.
    • 选择 桌面应用程序 作为应用程序类型。
    • 命名客户端（例如，“Gmail MCP客户端”）。
    • 下载 credentials.json 文件。
  5. 添加 http://localhost 到授权重定向URI：
    • 在……里面 凭证，编辑OAuth 2.0客户端ID并添加 http://localhost 在...之下 授权重定向URI.

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 （来自谷歌云）
    • 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.配置克劳德桌面

  1. 从以下位置安装Claude Desktop Anthropic网站.
  2. 定位或创建MCP配置文件（例如。， ~/.cursor/mcp.json 或克劳德的设置文件）。
  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. 打开克劳德桌面。
  2. 输入自然语言查询，例如：
    Find emails about project deadlines from the last 30 days.
  3. 克劳德将其翻译为 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": "jane.doe@example.com",
  "body": "Hi team, please review the June 1 deadline for Project X..."
}
  6. 克劳德用自然语言总结了结果。

使用示例

  • 按主题搜索:
    Show me emails about budget approvals from last month.
    地图指向： searchEmails("budget approvals after:2025-03-01 before:2025-04-01").
  • 按发件人搜索:
    Find emails from alice@example.com about conference planning.
    地图指向： searchEmails("from:alice@example.com 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 如果令牌无效，则重新进行身份验证。
  • 服务器未响应:
    • 验证中的JAR路径 mcp.json 是正确的。
    • 检查控制台中的日志是否有错误。
  • Claude桌面问题:
    • 确保Claude Desktop已更新到最新版本。
    • 确认MCP配置文件的格式正确。
  • Gmail API费率限制:
    • 如果达到速率限制，请降低查询频率或实现指数回退。

安全考虑

  • 凭证：添加 credentials.json 和 ~/.gmail-mcp/tokens 向 .gitignore 以防止意外犯罪。
  • OAuth2：用途 offline 持久令牌的访问类型；查看谷歌云控制台是否有异常活动。
  • 范围：仅限于 gmail.readonly 以防止未经授权的行为。

扩展服务器

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

贡献

欢迎投稿！拜托：

  1. 分叉存储库。
  2. 创建要素分支(git checkout -b feature/xyz).
  3. 提交更改(git commit -m "Add XYZ feature").
  4. 推到分支(git push origin feature/xyz).
  5. 打开一个pull请求。

许可证

MIT许可证。看 LICENSE 了解详情。

致谢

对于问题或疑问，打开GitHub问题或联系维护人员。

相关 MCP