Gmail MCP Server Btq

🚀 Gmail MCP 服務器

該項目實現了一個模型上下文協議 (MCP) 服務器，可藉助 IMAP 和 SMTP 與 Gmail 賬戶進行交互。它提供了一系列工具，可用於搜索郵件、檢索郵件內容、管理標籤（創建、刪除、重命名、應用、移除）以及發送或轉發郵件。

🚀 快速開始

1. 克隆倉庫

   git clone https://github.com/yourusername/gmail-mcp-server.git
   cd gmail-mcp-server
   

2. 創建虛擬環境並安裝依賴項

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

3. 配置環境變量 創建一個 .env 文件，添加以下內容：

   Gmail_IMAP_HOST=imap.gmail.com
   Gmail_SMTP_HOST=smtp.gmail.com
   Gmail_PORT=143  # IMAP 端口
   Gmail_SSL_PORT=465  # SMTP SSL 端口
   Gmail_EMAIL=your_email@gmail.com
   Gmail_PASSWORD=your_app_specific_password
   

4. 運行服務器

   source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
   python src/email_client/server.py
   

✨ 主要特性

• 郵件搜索：可按日期範圍、關鍵字或原始 Gmail 查詢字符串搜索郵件。支持在特定文件夾（收件箱、已發送）中進行搜索，並能限制結果數量。藉助 Gmail 的 X-GM-RAW 擴展，可實現高效的收件箱搜索（例如，按 category:primary 過濾）。
• 郵件內容檢索：使用序列 ID 可獲取特定郵件的完整內容（頭信息、正文、附件）。
• 標籤管理 (CRUD)
  • 列出所有可用的 Gmail 標籤（文件夾）。
  • 創建新的自定義標籤。
  • 重命名現有標籤。
  • 刪除現有自定義標籤（無法刪除系統標籤）。
  • 將標籤應用到單個郵件上。
  • 移除單個郵件上的標籤。
• 批處理操作
  • 使用序列 ID 批量為多個郵件應用標籤。
  • 從多個郵件上批量移除標籤。
  • 將多個郵件移動到特定標籤/文件夾中。
• 發送郵件：發送新郵件（需要 SMTP 配置）。
• 轉發郵件：轉發現有郵件，包括附件（需要 SMTP 配置）。
• 每日郵件計數：在指定日期範圍內統計每天收到的郵件數量。

📚 詳細文檔

可用工具（摘要）

• search-emails：搜索郵件。
• get-email-content：獲取完整的郵件詳情。
• count-daily-emails：統計每天收到的郵件數量。
• list-labels：列出所有標籤/文件夾。
• create-label：創建新的標籤。
• rename-label：重命名現有標籤。
• delete-label：刪除標籤。
• apply-label：將標籤應用到單個郵件上。
• remove-label：移除單個郵件上的標籤。
• apply-label-batch：批量為多個郵件應用標籤。
• remove-label-batch：從多個郵件上批量移除標籤。
• move-email：將單個郵件移動到一個標籤中。
• move-email-batch：將多個郵件移動到一個標籤中。
• send-email：發送新郵件。
• forward-email：轉發現有郵件。

有關每個工具的詳細輸入模式，請參閱 src/email_client/tool_definitions.py。

🔧 技術細節

項目結構

.
├── .gitignore         # 指定 Git 應忽略的文件
├── .python-version    # 指定 Python 版本（用於 pyenv）
├── LICENSE            # 項目許可證文件
├── pyproject.toml     # Python 項目配置（依賴項、構建系統）
├── README.md          # 此文件
├── task_list.md       # 跟蹤開發進度
├── uv.lock            # uv 包管理器的鎖定文件
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # 處理從環境變量（.env）加載配置
│       ├── handlers.py      # 實現處理 MCP 工具調用邏輯
│       ├── imap_client.py   # 包含與 IMAP 服務器交互的函數
│       ├── server.py        # 使用 @modelcontextprotocol/sdk 的主 MCP 服務器腳本
│       ├── smtp_client.py   # 包含與 SMTP 服務器交互的函數
│       └── tool_definitions.py # 定義所有可用工具及其詳細輸入模式

📄 許可證

項目許可證文件為 LICENSE，具體許可信息可查看該文件。