MCP Aruba Email

🚀 MCP阿魯巴郵件與日曆服務器

這是一個基於MCP（模型上下文協議）的服務器，用於通過IMAP/SMTP/CalDAV訪問阿魯巴（Aruba）的郵件和日曆。它能輕鬆地將阿魯巴的郵件和日曆與Claude等人工智能助手集成！

意大利語 | 英語

🚀 快速開始

你可以按照以下步驟快速啟動並使用本服務器：

# 克隆倉庫
git clone https://github.com/jackfioru92/mcp-aruba-email.git
cd mcp-aruba-email

# 創建虛擬環境
python -m venv .venv
source .venv/bin/activate  # 在Windows上使用：.venv\Scripts\activate

# 安裝依賴
pip install -e .

✨ 主要特性

郵件相關功能

• 📧 列出郵件：可通過發件人過濾器瀏覽收件箱。
• 🔍 搜索郵件：按主題或正文搜索，並支持日期過濾。
• 📖 閱讀郵件：獲取郵件完整內容。
• ✉️ 發送郵件：通過SMTP協議發送郵件，並支持自定義簽名。
• ✍️ 設置郵件簽名：創建包含照片和品牌顏色的專業簽名。

日曆相關功能

• 📅 創建事件：創建帶參與者的日曆事件。
• 📋 列出事件：查看未來的日曆事件。
• ✅ 接受邀請：接受日曆邀請。
• ❌ 拒絕邀請：拒絕日曆邀請。
• ❓ 可能參加：回覆“可能參加”日曆邀請。
• 🗑️ 刪除事件：從日曆中移除事件。

通用特性

• 🔒 安全可靠：使用SSL/TLS加密的IMAP/SMTP/CalDAV協議。
• ⚡ 高效快速：通過上下文管理器高效管理連接。
• 🤖 支持AI：與Claude Desktop和其他MCP客戶端完美配合。

📦 安裝指南

克隆項目

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

創建虛擬環境

python -m venv .venv
source .venv/bin/activate  # 在Windows上使用：.venv\Scripts\activate

安裝依賴

pip install -e .

配置環境變量

1. 複製環境變量示例文件：

cp .env.example .env

2. 編輯.env文件，填入你的阿魯巴賬戶憑證：

# 郵件配置
IMAP_HOST=imaps.aruba.it
IMAP_PORT=993
IMAP_USERNAME=你的郵箱@aruba.it
IMAP_PASSWORD=你的郵箱密碼

SMTP_HOST=smtps.aruba.it
SMTP_PORT=465

# 日曆配置
CALDAV_URL=https://syncdav.aruba.it/calendars/你的郵箱@aruba.it/
CALDAV_USERNAME=你的郵箱@aruba.it
CALDAV_PASSWORD=你的郵箱密碼

3. （可選）配置自定義郵件簽名：
   • 方法1：交互式腳本（推薦）

# 運行交互式腳本
python setup_signature.py

腳本將指導你創建專業簽名，包括： - 📝 個人信息（姓名、職位、公司、聯繫方式） - 🎨 風格選擇（專業、簡約、多彩） - 🌈 顏色自定義 - 📸 自動上傳照片到Imgur（可選）

- **方法2：通過Claude（更簡單！）**

在配置好Claude Desktop後，直接詢問：
"為我創建一個郵件簽名，姓名為張三，職位為軟件開發者，公司為科技公司，顏色為#0066cc"
"用這張照片配置我的簽名：/path/to/photo.jpg"
"設置一個僅包含姓名和郵箱的簡約簽名"

Claude將自動使用MCP工具為你創建簽名。簽名將自動包含在所有發出的郵件中。

⚠️ 重要提示

憑證信息將本地存儲，不會離開你的計算機。MCP服務器在本地運行，並直接連接到阿魯巴的服務器。

💻 使用示例

基礎用法

快速查看最新郵件

# 安裝依賴
pip install -e .

# 配置憑證（複製並修改.env.example）
cp .env.example .env
# 編輯.env文件，填入你的阿魯巴賬戶憑證

# 顯示最新的5封郵件
python cli.py emails 5

# 或者使用示例腳本
python demo_list_emails.py

如果你想使用Claude，配置完成後，只需詢問：

顯示最新的5封郵件
給我最新的郵件
我今天收到了哪些郵件？

📖 完整指南：查看GUIDA_UTILIZZO_EMAIL.md瞭解所有可用方法。

直接運行服務器

python -m mcp_aruba.server

與Claude Desktop集成

查看CLAUDE_SETUP.md獲取詳細說明。以下是~/Library/Application Support/Claude/claude_desktop_config.json的快速配置示例：

{
  "mcpServers": {
    "aruba-email-calendar": {
      "command": "python",
      "args": ["-m", "mcp_aruba.server"],
      "env": {
        "IMAP_HOST": "imaps.aruba.it",
        "IMAP_PORT": "993",
        "IMAP_USERNAME": "你的郵箱@aruba.it",
        "IMAP_PASSWORD": "你的郵箱密碼",
        "SMTP_HOST": "smtps.aruba.it",
        "SMTP_PORT": "465",
        "CALDAV_URL": "https://syncdav.aruba.it/calendars/你的郵箱@aruba.it/",
        "CALDAV_USERNAME": "你的郵箱@aruba.it",
        "CALDAV_PASSWORD": "你的郵箱密碼"
      }
    }
  }
}

與VS Code Copilot集成

查看VSCODE_SETUP.md瞭解如何使用本服務器與VS Code的Copilot MCP擴展。

使用快速CLI

# 激活虛擬環境
source .venv/bin/activate

# 顯示最新的5封郵件
python cli.py emails

# 顯示最新的10封郵件
python cli.py emails 10

# 顯示未來7天的日曆事件
python cli.py calendar

# 顯示未來14天的日曆事件
python cli.py calendar 14

高級用法

郵件工具

• list_emails：列出最近的郵件，支持可選過濾。
  • 參數：
    • folder（字符串，默認值："INBOX"）：要讀取的郵件文件夾。
    • sender_filter（字符串，可選）：按發件人郵件地址過濾。
    • limit（整數，默認值：10，最大值：50）：返回的郵件數量。
  • 示例：

顯示來自john@example.com的最新5封郵件
列出我的收件箱中的最近郵件
給我老闆發來的最新10封郵件

• read_email：讀取特定郵件的完整內容。
  • 參數：
    • email_id（字符串）：list_emails返回的郵件ID。
    • folder（字符串，默認值："INBOX"）：郵件文件夾。
  • 示例：

讀取郵件ID為123的郵件
顯示郵件ID為456的郵件完整內容

• search_emails：按主題或正文內容搜索郵件。
  • 參數：
    • query（字符串）：搜索查詢。
    • folder（字符串，默認值："INBOX"）：搜索的文件夾。
    • from_date（字符串，可選）：僅搜索此日期之後的郵件（格式：DD - MMM - YYYY）。
    • limit（整數，默認值：10，最大值：50）：最大返回結果數。
  • 示例：

搜索上週提到“API”的郵件
查找12月以來所有關於“發票”的郵件

• send_email：通過SMTP發送郵件。
  • 參數：
    • to（字符串）：收件人郵箱地址。
    • subject（字符串）：郵件主題。
    • body（字符串）：郵件正文（純文本）。
    • from_name（字符串，默認值："Giacomo Fiorucci"）：發件人顯示名稱。
    • use_signature（布爾值，默認值：True）：如果已配置，包含郵件簽名。
    • verify_recipient（布爾值，默認值：True）：驗證收件人郵箱地址是否存在。
  • 示例：

向colleague@example.com發送郵件，感謝其更新信息
回覆john@example.com，告知項目狀態

💡 使用建議

如果你使用setup_signature.py配置了簽名，它將自動包含在郵件中。你可以使用use_signature=False臨時禁用簽名。

• set_email_signature：配置自定義郵件簽名。
  • 參數：
    • name（字符串）：全名。
    • email（字符串）：郵箱地址。
    • role（字符串，可選）：職位。
    • company（字符串，可選）：公司名稱。
    • phone（字符串，可選）：電話號碼。
    • website（字符串，可選）：網站地址。
    • photo_input（字符串，可選）：照片文件路徑或URL（自動上傳到Imgur）。
    • style（字符串，默認值："professional"）：風格：專業、簡約、多彩。
    • color（字符串，默認值："#0066cc"）：主要顏色（十六進制格式）。
    • signature_name（字符串，默認值："default"）：簽名的標識名稱。
  • 示例：

用我的姓名、職位和個人照片創建一個簽名
配置一個帶有公司標誌的專業簽名

• get_email_signature：獲取當前郵件簽名。

  • 參數：
    • signature_name（字符串，默認值："default"）：要獲取的簽名名稱。

• list_email_signatures：列出所有保存的郵件簽名。

日曆工具

• create_calendar_event：創建新的日曆事件。
  • 參數：
    • summary（字符串）：事件標題。
    • start（字符串）：開始日期/時間，ISO格式（YYYY - MM - DDTHH:MM:SS）。
    • end（字符串）：結束日期/時間，ISO格式。
    • description（字符串，可選）：事件描述。
    • location（字符串，可選）：事件地點。
    • attendees（字符串，可選）：參與者郵箱地址列表，用逗號分隔。
  • 示例：

創建一個名為“團隊會議”的會議，明天15:00開始，持續1小時
安排一個“項目評審”會議，12月10日14:00，邀請john@example.com參加

• list_calendar_events：列出指定日期範圍內的日曆事件。
  • 參數：
    • start_date（字符串，可選）：開始日期，ISO格式（默認值：今天）。
    • end_date（字符串，可選）：結束日期，ISO格式（默認值：從現在起30天）。
    • limit（整數，默認值：50）：最大返回事件數。
  • 示例：

顯示我本週的日曆
我12月有哪些事件？
列出我未來7天的所有會議

• accept_calendar_event：接受日曆邀請。
  • 參數：
    • event_uid（字符串）：事件的唯一標識符。
    • comment（字符串，可選）：可選評論。
  • 示例：

接受“團隊站立會議”的邀請
接受abc123@aruba.it的事件邀請，並留言“迫不及待！”

• decline_calendar_event：拒絕日曆邀請。
  • 參數：
    • event_uid（字符串）：事件的唯一標識符。
    • comment（字符串，可選）：可選評論。
  • 示例：

拒絕abc123@aruba.it的事件邀請
拒絕會議邀請，並留言“抱歉，我有衝突”

• tentative_calendar_event：回覆“可能參加”日曆邀請。
  • 參數：
    • event_uid（字符串）：事件的唯一標識符。
    • comment（字符串，可選）：可選評論。
  • 示例：

對abc123@aruba.it的事件邀請回復“可能參加”
將明天的會議標記為“可能參加”
我可能參加明天的會議

• delete_calendar_event：刪除日曆事件。
  • 參數：
    • event_uid（字符串）：要刪除的事件的唯一標識符。
  • 示例：

刪除abc123@aruba.it的事件
取消我14:00的會議

📚 詳細文檔

常見使用場景

團隊溝通

顯示團隊成員發來的最新郵件
列出project@company.com未讀的郵件

項目跟蹤

搜索上週提到“API修改”的郵件
查找12月1日以來所有關於“發票”的郵件

每日郵件總結

總結我今天收到的所有郵件
顯示我今天上午的重要郵件

快速回復

向colleague@example.com發送郵件，感謝其更新信息
回覆john@example.com，告知項目狀態

日曆管理

我本週有哪些會議？
明天15:00創建一個團隊會議
接受週五評審會議的日曆邀請
拒絕週一的會議邀請，我正在休假
顯示我下週的日程安排

AI郵件和日曆管理

使用Claude Desktop或VS Code Copilot，你可以：

• 讓Claude總結多封郵件。
• 根據郵件內容生成回覆。
• 從郵件線程中提取任務。
• 自動組織和分類郵件。
• 根據郵件對話安排會議。
• 管理日曆衝突並查找可用時間段。

技術棧

• Python 3.10+：現代Python版本。
• MCP SDK 1.2.0+：用於AI集成的模型上下文協議。
• imaplib：標準IMAP客戶端庫（支持SSL/TLS）。
• smtplib：標準SMTP客戶端庫（支持SSL/TLS）。
• email：郵件解析和MIME處理。
• caldav：CalDAV協議，用於訪問日曆。
• icalendar：解析和生成iCalendar格式。
• python - dotenv：環境變量管理。

安全與隱私

• 🔒 本地運行：服務器在你的計算機上運行，憑證信息不會離開你的機器。
• 🛡️ SSL/TLS加密：所有連接使用安全協議（IMAPS端口993，SMTPS端口465，CalDAV使用HTTPS）。
• 🔐 環境變量：憑證信息存儲在.env文件中（默認被git忽略）。
• 📝 正文截斷：郵件正文限制為5000個字符，防止上下文溢出。
• ✅ 無外部服務：直接連接到阿魯巴的服務器。

安全最佳實踐

1. 永遠不要將.env文件提交到版本控制中。
2. 使用強密碼和唯一的郵箱賬戶密碼。
3. 考慮在你的阿魯巴賬戶中啟用雙因素認證（2FA）。
4. 定期更換憑證。
5. 查看MCP服務器日誌，排查可疑活動。

性能特點

• ⚡ 通過上下文管理器實現連接池。
• 📊 可配置結果限制，防止內存問題。
• 🚀 按需連接（無後臺進程）。
• 💾 最小內存佔用。

開發相關

運行測試

# 激活虛擬環境
source .venv/bin/activate

# 運行郵件連接測試
python test_connection.py

# 運行日曆連接測試
python test_calendar.py

# 測試事件創建
python test_create_event.py

# 測試發送日曆邀請
python send_invite.py

代碼質量檢查

# 格式化代碼
black src/

# 類型檢查
mypy src/

# 代碼檢查
pylint src/

啟用CalDAV同步

要使用日曆功能，你需要在阿魯巴Webmail中啟用CalDAV同步：

1. 訪問https://webmail.aruba.it。
2. 導航到日曆部分。
3. 點擊**"同步日曆"**。
4. 選擇**"日曆"** → "繼續"。
5. 選擇**"讀寫"**（CalDAV） → "繼續"。
6. 選擇要同步的日曆 → "繼續"。 啟用後，你可以通過MCP服務器完全管理你的日曆！

問題解決

日曆不可用

如果你看到“沒有可用的日曆”，你需要啟用CalDAV同步（見上文）。

連接錯誤

1. 驗證.env文件中的憑證信息是否正確。
2. 檢查端口993（IMAP）、465（SMTP）、443（CalDAV）是否被阻止。
3. 驗證防火牆設置。
4. 嘗試運行測試腳本。

郵件或事件未顯示

1. 驗證你在賬戶上是否有正確的權限。
2. 檢查應用的過濾器（發件人過濾器、日期過濾器）。
3. 增加結果限制。

常見問題解答

問：將我的憑證信息存儲在.env文件中安全嗎？
答：是的，只要.env文件不被提交到版本控制中。它已經包含在.gitignore中。憑證信息將保留在你的本地計算機上。

問：我可以將此服務器與其他郵件提供商一起使用嗎？
答：該服務器針對阿魯巴進行了優化，但你可以通過修改配置將其適配到支持IMAP/SMTP/CalDAV的其他提供商。

問：MCP服務器的費用是多少？
答：MCP服務器是免費的！這是開源軟件。你只需要訂閱Claude或GitHub Copilot即可與這些AI一起使用。

問：我的數據會發送給第三方嗎？
答：不會！服務器在本地運行，並直接連接到阿魯巴的服務器。沒有數據會通過第三方服務。

問：我可以為項目做貢獻嗎？
答：當然可以！查看CONTRIBUTING.md獲取指南。

貢獻指南

歡迎貢獻代碼！請按照以下步驟進行：

1. Fork倉庫。
2. 創建功能分支 (git checkout -b feature/出色的功能)。
3. 提交更改 (git commit -m '添加出色的功能')。
4. 推送到分支 (git push origin feature/出色的功能)。
5. 打開拉取請求。 查看CONTRIBUTING.md獲取完整細節。

路線圖

• [ ] 支持IMAP IDLE以實現即時通知。
• [ ] 支持郵件附件管理。
• [ ] 支持HTML郵件撰寫。
• [ ] 集成pytest測試套件。
• [ ] 支持多個賬戶。
• [ ] 支持重複日曆事件。
• [ ] 支持日曆通知。
• [ ] 與其他日曆（Google Calendar、Outlook）集成。

文檔資源

• README.md - 主文檔（英語）
• README_IT.md - 意大利語文檔
• GUIDA_UTILIZZO_EMAIL.md - 完整指南：如何查看最新郵件 📧
• EXAMPLES.md - 使用示例
• CLAUDE_SETUP.md - Claude Desktop設置
• VSCODE_SETUP.md - VS Code Copilot設置
• CONTRIBUTING.md - 貢獻指南
• LICENSE - MIT許可證

支持與反饋

如果你遇到問題：

1. 查看問題解決部分。
2. 運行測試腳本來驗證連接。
3. 檢查日誌中的錯誤消息。
4. 在GitHub上創建一個issue。

📄 許可證

本項目採用MIT許可證。詳情請參閱LICENSE文件。

作者

Giacomo Fiorucci - giacomo.fiorucci@emotion-team.com

致謝

• Model Context Protocol 提供MCP框架。
• Anthropic 提供Claude Desktop。
• GitHub 提供Copilot。
• 阿魯巴提供可靠的郵件和日曆服務。

---

⭐ 如果這個項目對你有幫助，請在GitHub上給它點個星！