金大哥 - mcp-aruba-email MCP 详情

article

README

🚀 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 .

配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑.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=你的邮箱密码

（可选）配置自定义邮件签名：
- 方法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个字符，防止上下文溢出。
✅ 无外部服务：直接连接到阿鲁巴的服务器。

安全最佳实践

永远不要将.env文件提交到版本控制中。
使用强密码和唯一的邮箱账户密码。
考虑在你的阿鲁巴账户中启用双因素认证（2FA）。
定期更换凭证。
查看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同步：

访问https://webmail.aruba.it。
导航到日历部分。
点击**"同步日历"**。
选择**"日历"** → "继续"。
选择**"读写"**（CalDAV） → "继续"。
选择要同步的日历 → "继续"。启用后，你可以通过MCP服务器完全管理你的日历！

问题解决

日历不可用

如果你看到“没有可用的日历”，你需要启用CalDAV同步（见上文）。

连接错误

验证.env文件中的凭证信息是否正确。
检查端口993（IMAP）、465（SMTP）、443（CalDAV）是否被阻止。
验证防火墙设置。
尝试运行测试脚本。

邮件或事件未显示

验证你在账户上是否有正确的权限。
检查应用的过滤器（发件人过滤器、日期过滤器）。
增加结果限制。

常见问题解答

问：将我的凭证信息存储在.env文件中安全吗？
答：是的，只要.env文件不被提交到版本控制中。它已经包含在.gitignore中。凭证信息将保留在你的本地计算机上。

问：我可以将此服务器与其他邮件提供商一起使用吗？
答：该服务器针对阿鲁巴进行了优化，但你可以通过修改配置将其适配到支持IMAP/SMTP/CalDAV的其他提供商。

问：MCP服务器的费用是多少？
答：MCP服务器是免费的！这是开源软件。你只需要订阅Claude或GitHub Copilot即可与这些AI一起使用。

问：我的数据会发送给第三方吗？
答：不会！服务器在本地运行，并直接连接到阿鲁巴的服务器。没有数据会通过第三方服务。

问：我可以为项目做贡献吗？
答：当然可以！查看CONTRIBUTING.md获取指南。

贡献指南

欢迎贡献代码！请按照以下步骤进行：

Fork仓库。
创建功能分支 (git checkout -b feature/出色的功能)。
提交更改 (git commit -m '添加出色的功能')。
推送到分支 (git push origin feature/出色的功能)。
打开拉取请求。查看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许可证

支持与反馈

如果你遇到问题：

查看问题解决部分。
运行测试脚本来验证连接。
检查日志中的错误消息。
在GitHub上创建一个issue。

📄 许可证

本项目采用MIT许可证。详情请参阅LICENSE文件。

作者

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

致谢

Model Context Protocol 提供MCP框架。
Anthropic 提供Claude Desktop。
GitHub 提供Copilot。
阿鲁巴提供可靠的邮件和日历服务。

⭐ 如果这个项目对你有帮助，请在GitHub上给它点个星！