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. 提交拉取請求。

📄 許可證

[許可證信息]

致謝

感謝以下貢獻者：

• [貢獻者姓名]
• [其他貢獻者姓名]