MCP Twake Mail

麦克电报

](https://www.npmjs.com/package/mcp-twake-mail)  ](https://nodejs.org/)

MCP服务器 醒来 --将您的主权JMAP电子邮件服务器与任何兼容MCP的AI助手集成

Twake Mail

概述

mcp-twake-mail是一个模型上下文协议（mcp）服务器，它将任何兼容mcp的AI助手（Claude Desktop、Claude Code等）连接到您的JMAP电子邮件服务器。与JMAP兼容的服务器兼容，包括Apache James、Cyrus IMAP和其他RFC 8620/8621实现。

主要优势：

• 您的数据保留在您自己的服务器上——主权基础设施
• 可与任何兼容MCP的AI助手配合使用
• 完全控制电子邮件数据——读取、写入、发送和组织
• 多种身份验证方法：基本、承载令牌或OIDC
• 自动发现 --仅使用您的电子邮件地址进行配置
• 电子邮件签名 --自动Markdown签名注入
• 仅安全HTTPS连接

特性

29 MCP工具

电子邮件阅读工具：

• list_emails -列出具有过滤、搜索和分页功能的电子邮件
• get_email -获取完整的电子邮件内容，包括正文和标题
• search_emails -按关键字搜索电子邮件
• get_thread -获取对话线程中的所有电子邮件

电子邮件撰写工具：

• send_email -撰写并发送一封新电子邮件（纯文本和/或HTML）
• reply_email -以正确的线程回复电子邮件（在回复中，参考文献）
• forward_email -转发带有附件和个人笔记的电子邮件
• create_draft -创建电子邮件草稿以供以后编辑或发送
• update_draft -更新现有草稿（主题、正文、收件人）
• send_draft -发送以前保存的草稿

电子邮件管理工具：

• mark_as_read / mark_as_unread -标记电子邮件阅读状态
• delete_email -移至垃圾箱或永久删除
• move_email -将电子邮件移动到其他邮箱
• add_label / remove_label -添加或删除标签/邮箱

批量操作（一次最多50封电子邮件）：

• batch_mark_read / batch_mark_unread -标记多封电子邮件
• batch_delete -删除多封电子邮件
• batch_move -将多封电子邮件移动到邮箱
• batch_add_label / batch_remove_label -在多封电子邮件中添加/删除标签

邮箱工具：

• list_mailboxes -列出所有邮箱（收件箱、已发送、草稿等）
• get_mailbox -按ID获取邮箱详细信息
• create_mailbox -创建一个具有可选嵌套的新文件夹
• rename_mailbox -重命名现有文件夹（系统文件夹受保护）
• delete_mailbox -删除带有安全检查的空文件夹

附件工具：

• get_attachments -列出电子邮件的附件元数据
• download_attachment -下载附件内容（自动保存大文件）

高级功能

• 自动发现 --仅使用您的电子邮件地址进行配置（DNS SRV+.wearned/jmap）
• 电子邮件签名 --Markdown签名文件自动附加到电子邮件中
• 默认发件人身份 --配置默认“发件人”地址
• 批量操作 --一次请求最多可处理50封电子邮件
• 工作流程草案 --创建、更新和发送带有原子转换的草稿
• 文件夹管理 --创建、重命名和删除自定义文件夹
• 系统文件夹保护 --无法修改收件箱、已发送、草稿、废纸篓
• 企业单点登录的OIDC认证与PKCE（S256）
• OIDC会话的自动令牌刷新
• 基于线程的电子邮件分组
• 内联与常规附件检测
• 大附件处理（对于大于750KB的文件，自动保存到~/下载）
• MCP工具注释（只读提示、解构提示、幂等提示）

先决条件

• Node.js >= 20.0.0
• JMAP服务器 -符合JMAP标准的电子邮件服务器，例如：

- 阿帕奇·詹姆斯 - Cyrus IMAP - 备用邮件服务器 - 快速邮件

• MCP兼容AI助手 -Claude Desktop、Claude Code或任何MCP客户端

安装

来自npm（推荐）：

npx mcp-twake-mail setup

来源：

git clone https://github.com/linagora/mcp-twake-mail.git
cd mcp-twake-mail
npm install
npm run build

快速设置（推荐）

配置mcp-twake邮件的最简单方法是使用交互式设置向导：

npx mcp-twake-mail setup

向导将：

1. 自动发现 从您的电子邮件地址（或手动输入）访问您的JMAP服务器
2. 询问您的身份验证方法（基本、承载或OIDC）
3. 收集所需的凭据
4. 配置默认发件人 以及可选的电子邮件签名
5. 测试与JMAP服务器的连接
6. 生成配置并将其写入Claude Desktop配置文件（可选）

自动发现模式

安装向导支持 自动发现 --只需提供您的电子邮件地址，系统就会自动找到您的JMAP服务器：

=== MCP Twake Mail Setup Wizard ===

Setup mode:
  1. Auto-discover from email address (Recommended)
  2. Manual configuration
Choose [1-2]: 1

Email address: user@example.com

Discovering JMAP server...
✓ Found JMAP server: https://jmap.example.com/jmap/session
✓ Found OIDC issuer: https://sso.example.com

Use discovered settings? [Y/n]: y

自动发现使用：

• DNS服务器 查找： _jmap._tcp.{domain}
• 众所周知/jmap 端点
• OAuth元数据 发现OIDC配置

看 docs/auto-discovery.md 了解详情。

电子邮件签名支持

配置一个可选的Markdown签名文件，该文件将自动附加到所有电子邮件中：

Configure email signature file? [y/N]: y
Path to signature file (Markdown format): ~/.mcp-twake-mail/signature.md

签名文件示例(~/.mcp-twake-mail/signature.md):

**John Doe**
Software Engineer
[john.doe@example.com](mailto:john.doe@example.com)

签名会自动转换为HTML（用于富格式电子邮件）和纯文本（用于简单电子邮件）。

看 docs/签名.md 了解详情。

CLI命令

配置

环境变量

基本认证

持有者令牌

OIDC身份验证

对于具有OpenID Connect（PKCE S256）的企业SSO：

看 docs/oidc-configuration.md 了解详细的OIDC设置说明。

身份和签名（可选）

其他选项

Claude桌面配置

将以下内容添加到您的Claude Desktop配置文件中：

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

配置（基本身份验证）：

{
  "mcpServers": {
    "mcp-twake-mail": {
      "command": "npx",
      "args": ["-y", "mcp-twake-mail"],
      "env": {
        "JMAP_SESSION_URL": "https://jmap.example.com/jmap/session",
        "JMAP_AUTH_METHOD": "basic",
        "JMAP_USERNAME": "user@example.com",
        "JMAP_PASSWORD": "your-password",
        "JMAP_DEFAULT_FROM": "user@example.com",
        "JMAP_SIGNATURE_PATH": "~/.mcp-twake-mail/signature.md"
      }
    }
  }
}

配置（OIDC）：

{
  "mcpServers": {
    "mcp-twake-mail": {
      "command": "npx",
      "args": ["-y", "mcp-twake-mail"],
      "env": {
        "JMAP_SESSION_URL": "https://jmap.example.com/jmap/session",
        "JMAP_AUTH_METHOD": "oidc",
        "JMAP_OIDC_ISSUER": "https://sso.example.com",
        "JMAP_OIDC_CLIENT_ID": "my-client-id",
        "JMAP_OIDC_SCOPE": "openid profile email offline_access",
        "JMAP_DEFAULT_FROM": "user@example.com",
        "JMAP_SIGNATURE_PATH": "~/.mcp-twake-mail/signature.md"
      }
    }
  }
}

更新配置后，重新启动Claude Desktop以使更改生效。

用法示例

配置后，您可以就电子邮件向Claude自然语言提问：

电子邮件查询：

• “我的未读邮件是什么？”
• “显示Pierre的电子邮件”
• “我收件箱中的最新电子邮件是什么？”
• “查找有关预算会议的电子邮件”
• “显示此电子邮件的对话线索”

电子邮件组成：

• “发送电子邮件至pierre@example.com关于明天的会议”
• “回复此电子邮件，感谢他们提供的信息”
• “将此电子邮件转发给团队，并附上备注”
• “为团队创建一封关于项目更新的电子邮件草稿”

草案管理：

• “更新草稿以更改主题行”
• “将玛丽添加到该草案的CC列表中”
• “发送我正在编写的草稿”

电子邮件管理：

• “将此电子邮件标记为已读”
• “将此电子邮件移动到存档文件夹”
• “删除所有垃圾邮件”
• “将“重要”标签添加到此电子邮件中”

批量操作：

• “将上周的所有电子邮件标记为已读”
• “将所有新闻稿移动到存档文件夹”
• “删除垃圾箱中所有超过30天的电子邮件”

文件夹管理：

• “创建一个名为“项目”的新文件夹”
• “将“Old Stuff”文件夹重命名为“Archive 2025””
• “删除空的'Temp'文件夹”

附件：

• “此电子邮件中有哪些附件？”
• “下载PDF附件”

文档

• 自动发现 --JMAP和OIDC自动发现的工作原理
• 电子邮件签名 --配置Markdown电子邮件签名
• OIDC配置 --详细的OIDC/OAuth设置指南

可用工具

发展

git clone https://github.com/linagora/mcp-twake-mail.git
cd mcp-twake-mail
npm install
npm run build    # compile TypeScript
npm test         # run tests (704 tests)
npm run dev      # watch mode (auto-rebuild on file changes)

服务器使用MCP stdio传输，并通过stdin/stdout上的JSON-RPC进行通信。

建筑

mcp-twake-mail采用分层架构构建：

1. 配置层 -基于Zod的环境变量验证，具有快速失败行为
2. 测井层 -配置用于stderr输出的引脚记录器（防止stdout污染）
3. 认证层 -多方法身份验证支持（基本、承载、带PKCE的OIDC）
4. 许可证管理 -具有安全令牌存储的OIDC自动令牌刷新
5. 发现层 -通过DNS SRV、.wearned/jmap和OAuth元数据自动发现
6. JMAP客户端层 -会话管理、请求批处理、blob下载支持
7. 签名层 -电子邮件签名的Markdown到HTML转换
8. 转换层 -电子邮件/邮箱数据转换，实现AI友好输出
9. MCP工具层 -29个MCP工具，通过工具注释展示电子邮件功能
10. 入口点 -使用stdio传输初始化MCP服务器

关键设计决策：

• ESM模块 .js 导入扩展（MCP SDK要求）
• JMAP RFC 8620/8621合规性，实现广泛的服务器兼容性
• AI友好的错误格式化，用于故障排除
• 大附件处理（大于750KB的文件自动保存到磁盘）
• 用于AI客户端的MCP工具注释（readOnlyHint、destructiveHint、幂等Hint）
• 按项目报告成功/失败的批处理操作
• 安全邮箱管理的系统文件夹保护

版本历史

许可证

该项目根据 GNU Affero通用公共许可证v3.0（AGPL-3.0）.

请参阅 许可证 文件以获取详细信息。

版权所有（c）2026利纳戈拉

贡献

欢迎投稿！请阅读我们的 贡献指南 有关开发工作流、代码风格和pull请求过程的详细信息。

支持

对于问题、疑问或功能请求，请在GitHub存储库上打开问题。

如需商业支持或咨询，请联系LINAGORA： .