Imap Mini MCP

🚀 IMAP Mini MCP

IMAP Mini MCP 是一個輕量級的 MCP（模型上下文協議）服務器，用於讀取 IMAP 電子郵件並創建草稿回覆。它可以與任何標準的 IMAP 服務器（如 Gmail、Outlook、Fastmail 等）以及本地橋接工具（如 ProtonMail Bridge）配合使用。

代理可以讀取、搜索、移動、標記星標和整理電子郵件，還能撰寫草稿，但不能發送或刪除電子郵件。

有關最近添加的功能，請參閱 CHANGELOG.md。

🚀 快速開始

強烈建議使用語音轉文字工具（例如 Mac 上的 SuperWhisper 或 Windows 上的 Whisperflow），並將您的 AI 桌面應用程序（如 Claude、Codex 等）連接到這個 MCP 服務器。這樣，您就可以通過語音與您的電子郵件收件箱進行對話，從而顯著加快工作流程。

📦 安裝指南

代理配置

將以下內容添加到您的 MCP 客戶端配置文件（例如 claude_desktop_config.json）中：

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "you@example.com",
        "IMAP_PASS": "your-password"
      }
    }
  }
}

args 路徑必須指向已構建的 dist/index.js。根據需要，可在 env 塊中添加任何可選變量。

環境變量

對於大多數提供商（如 Gmail、Outlook、Fastmail），使用默認設置即可 — 只需設置主機、用戶和密碼。

對於 ProtonMail Bridge，以下五個設置都是必需的（該橋接工具在本地主機上監聽，不使用 TLS，使用自簽名證書，並且不支持 STARTTLS）：

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=false

或者作為 MCP 客戶端配置：

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_STARTTLS": "false",
        "IMAP_TLS_REJECT_UNAUTHORIZED": "false",
        "IMAP_USER": "you@proton.me",
        "IMAP_PASS": "your-bridge-password"
      }
    }
  }
}

💻 使用示例

基礎用法

每個電子郵件都由一個複合 id (YYYY-MM-DDTHH:mm:ss.<Message-ID>) 標識，該 id 全局唯一，並且在文件夾移動時保持穩定。使用 find_emails 返回的 id 來獲取內容、下載附件、移動電子郵件或創建回覆草稿。操作工具接受一個可選的 mailbox 提示，以加快查找速度；如果省略該提示，則會搜索所有文件夾。

find_emails

搜索和過濾電子郵件。所有參數都是可選的 — 不傳遞任何參數調用該工具將返回收件箱中所有電子郵件，按最新郵件優先排序。

示例：

高級用法

📚 詳細文檔

故障排除

"IMAP 連接意外關閉" 或 "服務器斷開連接"

這幾乎總是意味著服務器由於 TLS/STARTTLS 不匹配而拒絕連接。請驗證您的 MCP 客戶端配置中以下環境變量是否設置正確：

本地 IMAP 橋接工具（如 ProtonMail Bridge）通常需要 IMAP_SECURE=false、IMAP_STARTTLS=false 和 IMAP_TLS_REJECT_UNAUTHORIZED=false。請參閱上面 環境變量 部分中的 ProtonMail Bridge 配置示例。

"IMAP 身份驗證失敗"

檢查 IMAP_USER 和 IMAP_PASS 是否正確。某些提供商（如 Gmail）需要應用專用密碼而不是您的賬戶密碼。

"無法連接到 IMAP 服務器 — 連接被拒絕"

IMAP 服務器未運行或未在配置的主機和端口上監聽。對於本地橋接工具，請確保橋接應用程序正在運行。

開發

構建和運行

npm install
npm run build

使用 .env 進行本地開發

要直接運行服務器（不在 MCP 客戶端中），請將 .env.example 複製到 .env 並填寫您的憑據，然後執行以下命令：

npm start

通過 MCP 客戶端使用時，憑據將通過客戶端配置的 env 塊提供。

測試

測試使用 vitest 並模擬 IMAP 層 — 不需要實際的服務器連接：

npm test             # 運行一次
npm run test:watch   # 監聽模式
npm run lint         # 僅進行類型檢查

📄 許可證

MIT