快速邮件-MCP
项目介绍
Fastmail MCP 服务器
这是一个基于模型上下文协议（MCP）的服务器，提供对 Fastmail API 的访问，使AI助手能够与电子邮件、联系人和日历数据进行交互。
功能
核心邮件操作
- 列出邮箱并获取邮箱统计信息
- 使用高级标准列出、搜索和过滤电子邮件
- 通过ID获取特定电子邮件及其全部内容
- 发送电子邮件（文本和HTML），并正确处理草稿和已发送邮件
- 邮件管理：标记已读/未读、删除、在文件夹之间移动
高级邮件功能
- 附件处理：列出并下载电子邮件附件
- 线程支持：获取完整的对话线程
- 高级搜索：多条件过滤（发件人、日期范围、附件、已读状态）
- 批量操作：同时处理多个电子邮件
- 统计数据与分析：账户概要和邮箱统计
联系人操作
- 列出所有联系人及其完整联系信息
- 通过ID获取特定联系人
- 按姓名或电子邮件搜索联系人
日历操作
- 列出所有日历和日历事件
- 通过ID获取特定日历事件
- 创建新的日历事件，包括参与者和详细信息
身份与账户管理
- 列出可用的发送身份
- 包含全面统计信息的账户概要
安装
先决条件
- Node.js 18+
- 具有 API 访问权限的 Fastmail 账户
- Fastmail API 令牌
安装步骤
-
克隆或下载此仓库
-
安装依赖项：
npm install -
构建项目：
npm run build
配置
-
获取您的 Fastmail API 令牌：
- 登录到 Fastmail 网页界面
- 前往设置 → 隐私与安全
- 找到“连接的应用程序及 API 令牌”部分
- 点击“管理 API 令牌”
- 点击“新建 API 令牌”
- 复制生成的令牌
-
设置环境变量：
export FASTMAIL_API_TOKEN="your_api_token_here" # 可选：自定义基础 URL（默认为 https://api.fastmail.com） export FASTMAIL_BASE_URL="https://api.fastmail.com"
运行服务器
启动 MCP 服务器：
npm start
开发模式（自动重载）：
npm run dev
通过 npx 运行（GitHub）
默认使用 main 分支：
FASTMAIL_API_TOKEN="your_token" FASTMAIL_BASE_URL="https://api.fastmail.com" \
npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp
Windows PowerShell：
$env:FASTMAIL_API_TOKEN="your_token"
$env:FASTMAIL_BASE_URL="https://api.fastmail.com"
npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp
指定标签版本：
FASTMAIL_API_TOKEN="your_token" \
npx --yes github:MadLlama25/fastmail-mcp@v1.6.1 fastmail-mcp
作为 Claude Desktop 扩展安装 (DXT)
您可以使用打包的 .dxt 文件将此服务器安装为 Claude Desktop 的桌面扩展。
-
构建并打包：
npm run build npx dxt pack这将在项目根目录中生成
fastmail-mcp.dxt。 -
安装到 Claude Desktop：
- 打开
.dxt文件，或将它拖放到 Claude Desktop 中 - 当提示时：
- Fastmail API 令牌：粘贴您的令牌（由 Claude 加密存储）
- Fastmail 基础 URL：留空以使用
https://api.fastmail.com（默认）
- 打开
-
使用任何工具（例如
get_recent_emails）。
可用工具（总计 31 个）
🎯 最受欢迎的工具：
- check_function_availability：检查可用功能并获得设置指导
- test_bulk_operations：使用干运行模式安全测试批量操作
- send_email：具有完整功能的电子邮件发送，正确处理草稿和已发送邮件
- advanced_search：强大的多条件电子邮件过滤
- get_recent_emails：快速访问来自任何邮箱的最近电子邮件
邮件工具
- list_mailboxes：获取账户中的所有邮箱
- list_emails：从特定邮箱或所有邮箱中列出电子邮件
- 参数：
mailboxId（可选），limit（默认：20）
- 参数：
- get_email：通过ID获取特定电子邮件
- 参数：
emailId（必需）
- 参数：
- send_email：发送电子邮件
- 参数：
to（必需数组），cc（可选数组），bcc（可选数组），from（可选），mailboxId（可选），subject（必需），textBody（可选），htmlBody（可选）
- 参数：
- search_emails：按内容搜索电子邮件
- 参数：
query（必需），limit（默认：20）
- 参数：
- get_recent_emails：获取邮箱中的最新电子邮件（灵感来自 JMAP-Samples 的 top-ten 示例）
- 参数：
limit（默认：10，最大：50），mailboxName（默认：'inbox'）
- 参数：
- mark_email_read：将电子邮件标记为已读或未读
- 参数：
emailId（必需），read（默认：true）
- 参数：
- delete_email：删除电子邮件（移至垃圾箱）
- 参数：
emailId（必需）
- 参数：
- move_email：将电子邮件移动到不同的邮箱
- 参数：
emailId（必需），targetMailboxId（必需）
- 参数：
高级邮件功能
- get_email_attachments：获取电子邮件的附件列表
- 参数：
emailId（必需）
- 参数：
- download_attachment：获取电子邮件附件的下载链接
- 参数：
emailId（必需），attachmentId（必需）
- 参数：
- advanced_search：具有多个标准的高级电子邮件搜索
- 参数：
query（可选），from（可选），to（可选），subject（可选），hasAttachment（可选），isUnread（可选），mailboxId（可选），after（可选），before（可选），limit（默认：50）
- 参数：
- get_thread：获取对话线程中的所有电子邮件
- 参数：
threadId（必需）
- 参数：
邮件统计数据与分析
- get_mailbox_stats：获取邮箱的统计数据（未读数量、总邮件数等）
- 参数：
mailboxId（可选，默认为所有邮箱）
- 参数：
- get_account_summary：获取包含统计数据的整体账户概要
批量操作
- bulk_mark_read：将多封电子邮件标记为已读或未读
- 参数：
emailIds（必需数组），read（默认：true）
- 参数：
- bulk_move：将多封电子邮件移动到邮箱
- 参数：
emailIds（必需数组），targetMailboxId（必需）
- 参数：
- bulk_delete：删除多封电子邮件（移至垃圾箱）
- 参数：
emailIds（必需数组）
- 参数：
联系人工具
- list_contacts：列出所有联系人
- 参数：
limit（默认：50）
- 参数：
- get_contact：通过ID获取特定联系人
- 参数：
contactId（必需）
- 参数：
- search_contacts：按姓名或电子邮件搜索联系人
- 参数：
query（必需），limit（默认：20）
- 参数：
日历工具
- list_calendars：列出所有日历
- list_calendar_events：列出日历事件
- 参数：
calendarId（可选），limit（默认：50）
- 参数：
- get_calendar_event：通过ID获取特定日历事件
- 参数：
eventId（必需）
- 参数：
- create_calendar_event：创建新的日历事件
- 参数：
calendarId（必需），title（必需），description（可选），start（必需，ISO 8601），end（必需，ISO 8601），location（可选），participants（可选数组）
- 参数：
身份与测试工具
- list_identities：列出发送身份（可用于发送的电子邮件地址）
- check_function_availability：根据账户权限检查哪些功能可用（包括设置指导）
- test_bulk_operations：使用干运行模式安全测试批量操作
- 参数：
dryRun（默认：true），limit（默认：3）
- 参数：
API 信息
此服务器使用 Fastmail 提供的 JMAP（JSON 元应用协议）API。JMAP 是一种现代且高效的替代 IMAP 的电子邮件访问方式。
受 Fastmail JMAP-Samples 启发
许多功能在此 MCP 服务器中受到官方 Fastmail JMAP-Samples 存储库的启发，包括：
- 最近电子邮件检索（基于 top-ten 示例）
- 邮件管理操作
- 高效的链式 JMAP 方法调用
认证
服务器使用 Fastmail API 的承载令牌认证。API 令牌提供了无需暴露主账户密码的安全访问。
速率限制
Fastmail 对 API 请求应用了速率限制。服务器处理标准的速率限制，但过多的请求可能会被限流。
开发
项目结构
src/
├── index.ts # 主 MCP 服务器实现
├── auth.ts # 认证处理
├── jmap-client.ts # JMAP 客户端封装
└── contacts-calendar.ts # 联系人和日历扩展
构建
npm run build
开发模式
npm run dev
许可证
MIT
贡献
欢迎贡献！请确保：
- 代码遵循现有风格
- 所有函数都正确类型化
- 实现错误处理
- 更新新功能的文档
故障排除
常见问题
- 认证错误：确保您的 API 令牌有效且具有必要的权限
- 缺少依赖项：运行
npm install以确保所有依赖项均已安装 - 构建错误：使用
npm run build检查 TypeScript 编译是否完成且无错误 - 日历/联系人“禁止”错误：使用
check_function_availability查看设置指导
日历/联系人不起作用？
如果日历和联系人功能返回“禁止”错误，这可能是由于：
- 账户计划：日历/联系人 API 可能需要商业/专业 Fastmail 计划
- API 令牌范围：您的 API 令牌可能需要启用日历/联系人权限
- 功能启用：这些功能可能需要在您的账户中明确激活
解决方案：运行 check_function_availability 以获取逐步设置指导。
测试您的设置
使用内置的测试工具：
- check_function_availability：查看可用功能并获得设置帮助
- test_bulk_operations：安全地测试批量操作而不做更改
如需更详细的错误信息，请在运行服务器时检查控制台输出。
隐私与安全
- API 令牌在通过 DXT 安装时由 Claude Desktop 加密存储，并且永远不会被此服务器记录。
- 服务器避免在错误消息中记录原始错误和敏感数据（令牌、电子邮件地址、身份、附件名称/blobIds）。
- 工具响应可能设计上包含您的电子邮件元数据/内容（例如，列出电子邮件），但内部标识符和凭证不会超出 Fastmail 返回的请求数据范围。
- 如果您遇到错误，消息会被净化并总结，以防止泄露个人信息。