mcp-gmail-server

🚀 Gmail MCP 服务器

这个 Gmail MCP 服务器允许用户通过自然语言指令与 Gmail 帐户进行交互，支持搜索和阅读电子邮件，为用户提供了便捷的邮件操作体验。

🚀 快速开始

将 Gmail API 密钥和 OAuth 凭证配置到 src/main/resources/credentials.json 文件中，并确保 JVM 系统属性 -Dgmail.credentials.path=src/main/resources 设置正确。运行服务器前，请完成以下身份验证步骤：

1. 创建项目并启用 Gmail API。
2. 启用 Cloud Platform API 服务。
3. 创建 OAuth 凭证。

✨ 主要特性

搜索电子邮件

通过自然语言或查询字符串搜索电子邮件，支持以下操作：

searchEmails(query: String) -> List<Email>

阅读电子邮件

根据邮件 ID 读取完整内容：

readEmail(emailId: String) -> Email

📦 安装指南

• credentials.json: 包含 Gmail API 的凭据信息。
• src/main/resources/: 确保配置文件位于此目录中。
• -Dgmail.credentials.path=src/main/resources: 设置 JVM 系统属性。

💻 使用示例

基础用法

• 按主题搜索：

  显示过去一个月关于预算批准的邮件。
  

  转换为：searchEmails("budget approvals after:2025-03-01 before:2025-04-01")

• 按发件人搜索：

  查找 alice@example.com 发送的有关会议计划邮件。
  

  转换为：searchEmails("from:alice@example.com conference planning")

📚 详细文档

最佳实践

• 安全性：

  • 使用最小权限 gmail.readonly 范围以限制访问。
  • 将凭据文件和令牌存储在安全位置，如 .gitignore 中排除它们。

• 错误处理：

  • 返回 JSON-RPC 错误响应处理无效请求或 API 失败。
  • 使用 SLF4J/Logback 进行详细日志记录以辅助调试。

故障排除

• 身份验证错误：
  • 确保 credentials.json 文件位于 src/main/resources/ 目录中。
  • 删除 ~/.gmail-mcp/tokens 并重新进行身份验证。

安全考虑

• 凭据：确保 credentials.json 和 ~/.gmail-mcp/tokens 不被意外提交到版本控制系统。
• OAuth2：使用 offline 访问类型以实现持续令牌访问；定期检查 Google Cloud 控制台中的活动日志。

扩展服务器

• 添加功能：扩展 GmailMcpServer.java 以包含更多功能，如 labelEmail 或 sendEmail（需额外范围）。
• 远程部署：使用 SSE 或 WebSocket 进行云端部署（例如，使用 Spring WebFlux）。
• 缓存：实现常见查询的缓存机制，使用 Caffeine 等内存存储。

贡献指南

欢迎贡献！请：

1. 叉取仓库。
2. 创建功能分支 (git checkout -b feature/xyz)。
3. 提交更改 (git commit -m "添加 XYZ 功能")。
4. 推送到分支 (git push origin feature/xyz)。
5. 提交拉取请求。

📄 许可证

[许可证信息]

👏 致谢

感谢以下贡献者：

• [贡献者姓名]
• [其他贡献者姓名]