Email MCP

🚀 📧 通用郵箱 MCP Server

一個讓AI輕鬆接管郵箱的通用MCP服務器，基於 Model Context Protocol (MCP) 構建，支持在 MCP-X、Claude Desktop 等 MCP 客戶端中使用。支持多種郵箱服務商自動配置，如QQ郵箱、163郵箱、Gmail、Outlook、騰訊企業郵箱、網易企業郵箱、阿里雲郵箱、新浪郵箱、搜狐郵箱等。

🚀 快速開始

方式一：直接使用npm包（推薦）

1. 安裝npm包

# 全局安裝
npm install -g mcp-email

# 或本地安裝
npm install mcp-email

2. 在MCP客戶端中配置

MCP-X 配置示例：

{
  "mcpServers": {
    "universal-email": {
      "command": "npx",
      "args": ["mcp-email"],
      "env": {
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASSWORD": "your-password-or-auth-code",
        "EMAIL_TYPE": "auto"
      }
    }
  }
}

方式二：從源碼安裝

1. 克隆項目

git clone https://github.com/TimeCyber/email-mcp.git
cd email-mcp

2. 安裝依賴

npm install

3. 配置 MCP 客戶端（源碼安裝）

MCP-X 配置：

{
  "mcpServers": {
    "universal-email": {
      "command": "node",
      "args": ["F:\\path\\to\\email-mcp\\index.js"],
      "env": {
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASSWORD": "your-password-or-auth-code",
        "EMAIL_TYPE": "auto"
      }
    }
  }
}

企業郵箱配置：

{
  "mcpServers": {
    "enterprise-email": {
      "command": "node",
      "args": ["F:\\path\\to\\email-mcp\\index.js"],
      "env": {
        "EMAIL_USER": "user@company.com",
        "EMAIL_PASSWORD": "your-enterprise-auth-code",
        "EMAIL_TYPE": "exmail"
      }
    }
  }
}

4. 測試配置

# 測試郵件配置是否成功
node test-auto-config.js

✨ 主要特性

• 📤 郵件發送：支持發送HTML和純文本郵件
• 👥 多收件人：支持多個收件人、抄送、密送
• 📎 附件支持：支持文件附件和Base64編碼內容
• 🔧 動態配置：支持運行時配置郵箱服務器
• 🔍 連接測試：內置SMTP服務器連接測試
• 🛡️ 安全認證：支持微信企業郵箱授權碼認證
• ⚡ 高性能：優化的連接超時和重試機制

📦 安裝指南

# npm 安裝
npm install -g mcp-email

# 使用 npx 運行（推薦）
npx mcp-email

💻 使用示例

基礎用法

發送郵件

{
  "to": ["recipient@example.com"],
  "subject": "測試郵件",
  "text": "這是一封測試郵件"
}

獲取最近郵件

{
  "limit": 10,
  "days": 7
}

獲取郵件內容

{
  "uid": "12345"
}

設置郵箱賬號

{
  "email": "user@qq.com",
  "password": "your-auth-code"
}

列出支持的郵箱

{}

手動配置服務器

{
  "user": "your-email@domain.com",
  "password": "your-password",
  "smtpHost": "smtp.domain.com",
  "smtpPort": 465,
  "smtpSecure": true
}

測試連接

{
  "testType": "smtp"
}

高級用法

帶抄送和HTML內容的郵件發送

{
  "to": ["recipient1@example.com", "recipient2@example.com"],
  "cc": ["manager@example.com"],
  "subject": "項目報告",
  "text": "請查看項目報告",
  "html": "<h1>項目報告</h1><p>項目進展順利。</p>"
}

帶附件的郵件發送

{
  "to": ["recipient@example.com"],
  "subject": "帶附件的郵件",
  "text": "請查看附件",
  "attachments": [
    {
      "filename": "report.pdf",
      "path": "C:\\path\\to\\report.pdf"
    },
    {
      "filename": "data.txt",
      "content": "SGVsbG8gV29ybGQ="
    }
  ]
}

企業郵箱設置

{
  "email": "user@company.com",
  "password": "your-enterprise-auth-code",
  "provider": "exmail"
}

📚 詳細文檔

項目提供了詳細的配置指南，包含各大郵箱服務商的配置說明： 📖 CONFIG_GUIDE.md - 完整配置指南，包含：

• 📧 163郵箱詳細配置教程
• 🏢 微信企業郵箱配置指南
• 🌐 QQ郵箱、Gmail等主流郵箱配置
• 🛠️ 故障排除和常見問題解決

🔧 技術細節

MCP 工具說明

1. send_email - 發送郵件

發送郵件，支持多種格式和收件人。

• 參數：
  • to (必需)：收件人郵箱地址數組
  • subject (必需)：郵件主題
  • text (必需)：純文本郵件內容
  • cc (可選)：抄送郵箱地址數組
  • bcc (可選)：密送郵箱地址數組
  • html (可選)：HTML格式郵件內容
  • attachments (可選)：附件數組

2. get_recent_emails - 獲取最近郵件

獲取最近幾天的郵件列表，自動選擇最佳協議（IMAP/POP3）。

• 參數：
  • limit (可選)：返回郵件數量限制，默認20
  • days (可選)：獲取最近幾天的郵件，默認3天

3. get_email_content - 獲取郵件內容

獲取指定郵件的詳細內容。

• 參數：
  • uid (必需)：郵件唯一標識符（從郵件列表中獲取）

4. setup_email_account - 設置郵箱賬號

自動識別郵箱類型並配置服務器，支持8大郵箱服務商。

• 參數：
  • email (必需)：郵箱地址
  • password (必需)：郵箱密碼或授權碼
  • provider (可選)：郵箱提供商（手動指定，用於企業郵箱）
• 支持的郵箱類型：
  • qq - QQ郵箱
  • 163 - 網易郵箱
  • gmail - Gmail
  • outlook - Outlook/Hotmail
  • exmail - 騰訊企業郵箱
  • netease-enterprise - 網易企業郵箱
  • aliyun - 阿里雲郵箱
  • sina - 新浪郵箱
  • sohu - 搜狐郵箱

5. list_supported_providers - 列出支持的郵箱

查看所有支持的郵箱服務商及其配置信息。

• 參數：無需參數

6. configure_email_server - 手動配置服務器

手動配置郵箱服務器設置（高級用戶使用）。

• 參數：
  • user (必需)：郵箱賬號
  • password (必需)：郵箱密碼或授權碼
  • smtpHost (可選)：SMTP服務器地址
  • smtpPort (可選)：SMTP端口
  • smtpSecure (可選)：是否使用SSL
  • imapHost (可選)：IMAP服務器地址
  • imapPort (可選)：IMAP端口
  • imapSecure (可選)：是否使用SSL

7. test_email_connection - 測試連接

測試郵箱服務器連接狀態。

• 參數：
  • testType (可選)：測試類型
    • smtp - 僅測試發送服務器
    • imap - 僅測試接收服務器
    • both - 測試全部（默認）

支持的郵箱服務商

主流郵箱服務器配置

*網易郵箱（163/126/yeah）自動使用POP3協議以避免"Unsafe Login"錯誤

Gmail特殊說明：從2025年5月1日起，Google Workspace賬號不再支持"less secure apps"，必須使用OAuth認證。個人Gmail需要使用應用專用密碼。詳見配置指南。*

自動配置特性

• ✅ 智能識別：根據郵箱域名自動選擇服務器配置
• ✅ 協議優化：163郵箱自動使用POP3，其他使用IMAP
• ✅ 企業郵箱：支持通過 EMAIL_TYPE 字段手動指定
• ✅ 錯誤處理：IMAP失敗時自動嘗試POP3協議

故障排除

常見錯誤和解決方案

1. 535 Error: authentication failed

原因：認證失敗 解決方案：

• 確認已在郵箱設置中開啟SMTP/IMAP/POP3服務
• 重新生成授權碼或應用專用密碼
• 檢查郵箱地址和授權碼是否正確
• 對於企業郵箱，確認管理員已允許第三方訪問

2. [IMAP] EXAMINE Unsafe Login (網易郵箱常見)

原因：網易郵箱安全限制 解決方案：

• 系統會自動切換到POP3協議
• 確認已在網易郵箱中開啟POP3/SMTP服務
• 使用最新生成的16位授權碼

3. ECONNREFUSED 或連接超時

原因：網絡連接問題 解決方案：

• 檢查網絡連接狀態
• 確認防火牆沒有阻擋郵件端口 (25, 465, 587, 993, 995)
• 嘗試不同的網絡環境或VPN

4. EMAIL_TYPE 相關錯誤

原因：企業郵箱域名和服務器不匹配 解決方案：

• 為企業郵箱設置正確的 EMAIL_TYPE 字段
• 騰訊企業郵箱設置為 "exmail"
• 網易企業郵箱設置為 "netease-enterprise"

診斷工具

使用內置診斷命令：

# 測試郵箱配置
node test-auto-config.js

# 測試EMAIL_TYPE功能
node test-email-type.js

# 使用MCP工具測試連接
# 在MCP客戶端中調用 test_email_connection

調試技巧

1. 查看詳細日誌：系統會自動輸出配置和連接信息
2. 使用測試工具：通過 test_email_connection 診斷問題
3. 檢查郵箱類型：使用 list_supported_providers 確認支持
4. 逐步配置：先使用 setup_email_account 自動配置

項目結構

├── index.js                     # MCP Server主程序
├── package.json                # 項目依賴配置
├── README.md                   # 項目主文檔
├── CONFIG_GUIDE.md            # 詳細配置指南
├── .gitignore                 # Git忽略文件
├── 📁 配置模板/
│   ├── mcp-x_config_v2.json      # 通用配置模板
│   └── mcp-x_config_multi.json   # 多賬戶配置
├── 📁 測試工具/
│   ├── test-auto-config.js       # 自動配置測試
│   └── test-email-type.js        # EMAIL_TYPE功能測試
└── LICENSE                     # 開源許可證

核心文件說明

• index.js - 主要的MCP服務器程序，包含所有郵件功能
• CONFIG_GUIDE.md - 詳細的配置指南，包含各種郵箱配置說明
• mcp-x_config_v2.json - 通用配置模板，支持EMAIL_TYPE字段
• test-auto-config.js - 測試自動配置功能的腳本
• test-email-type.js - 驗證EMAIL_TYPE字段功能的測試腳本

📦 郵箱配置指南

獲取授權碼

騰訊企業郵箱

1. 訪問 企業郵箱管理後臺
2. 進入 "設置" → "賬戶" → "客戶端專用密碼"
3. 生成 客戶端專用密碼 (授權碼)
4. 進入 "設置" → "收發信設置" → "設置方法"
5. 開啟 "POP/IMAP/SMTP服務"

QQ郵箱

1. 登錄QQ郵箱，進入**"設置"** → "賬戶"
2. 開啟**"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服務"**
3. 生成授權碼

163郵箱

1. 登錄163郵箱，進入**"設置"** → "POP3/SMTP/IMAP"
2. 開啟**"POP3/SMTP/IMAP服務"**
3. 設置客戶端授權密碼

💡 使用建議

• 企業郵箱必須設置 EMAIL_TYPE 字段！
• 個人郵箱可以使用 EMAIL_TYPE: "auto" 自動識別

📖 CONFIG_GUIDE.md - 完整配置指南，包含所有郵箱類型詳細說明

🔐 安全注意事項

1. 保護授權碼：不要將授權碼提交到版本控制系統
2. 使用環境變量：推薦使用環境變量存儲敏感信息
3. 定期更新：定期更新授權碼和檢查安全設置
4. 權限控制：確保只有授權用戶可以訪問MCP服務器

📞 技術支持

文檔資源

• 📋 CONFIG_GUIDE.md - 完整配置指南
• 🔧 測試工具 - 使用 test-auto-config.js 和 test-email-type.js
• 🛠️ 內置診斷 - 使用 test_email_connection 工具

官方文檔

• 網易郵箱客戶端設置
• 騰訊企業郵箱配置
• QQ郵箱幫助中心
• Gmail設置指南

貢獻指南

歡迎提交 Issue 和 Pull Request 來改進這個項目！

• 🐛 報告Bug：請詳細描述問題和復現步驟
• 💡 功能建議：歡迎提出新的郵箱支持需求
• 📝 文檔改進：幫助完善使用文檔

項目狀態

• ✅ 生產就緒：支持8大主流郵箱服務商
• 🔄 持續更新：根據用戶反饋不斷改進
• 🛡️ 安全保障：支持SSL/TLS加密和授權碼認證

📄 許可證

MIT License - 詳見 LICENSE 文件

🎉 快速測試

配置完成後，可以在MCP客戶端中測試功能： 發送測試郵件：

請發送一封測試郵件到 test@example.com，主題為"MCP測試郵件"，內容為"Hello from Universal Email MCP!"

獲取郵件列表：

請獲取最近3天的郵件列表，限制10封郵件

測試連接：

請測試郵箱連接狀態

如果一切配置正確，所有功能都應該正常工作！🚀