JMAP MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供用于与 JMAP (JSON Meta Application Protocol) 电子邮件服务器交互的工具。使用 Deno 构建，并使用 @htunnicliff/jmap-jam 客户端库。

功能

电子邮件管理工具

• 搜索邮件：通过文本查询、发件人/收件人过滤器、日期范围和关键字搜索邮件。所有过滤器均为“与”(AND) 关系。

• 获取邮件：通过 ID 获取特定邮件，并可配置属性选择

• 获取会话：获取电子邮件会话（对话链）

• 标记邮件：将邮件标记为已读/未读、加星标/取消星标

• 移动邮件：在邮箱之间移动邮件

• 删除邮件：永久删除邮件

邮箱管理

• 获取邮箱：列出所有支持层级结构的邮箱/文件夹。使用此工具查找其他工具所需的邮箱 ID。

增量同步

• 获取邮件变更：获取自上次状态以来创建、更新或销毁的邮件 ID（基于状态的增量跟踪）

• 获取搜索更新：获取自上次查询状态 (queryState) 以来搜索查询结果中的添加或移除项

邮件撰写

• 发送邮件：撰写并发送支持纯文本和 HTML 的新邮件

• 回复邮件：回复现有邮件，支持自动处理邮件头和“全部回复”

关键能力

• 通过 jmap-jam 完全符合 JMAP RFC 8620/8621 标准

• 使用 Zod 模式进行全面的输入验证

• 支持所有列表操作的分页

• 基于状态的增量同步，实现高效轮询

• 丰富的错误处理和连接管理

• 基于能力的工具注册（只读、提交）

• 强类型的 TypeScript 支持

Related MCP server: bare-mcp

安装

Claude Code 插件（推荐）

通过插件市场安装：

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

然后在 MCP 服务器设置中配置所需的环境变量。

前置要求

• Deno v1.40 或更高版本

• 符合 JMAP 标准的电子邮件服务器（例如 Cyrus IMAP、Stalwart Mail Server、FastMail）

• 有效的 JMAP 身份验证凭据

设置

将以下内容添加到您选择的代理中：

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

如果不使用 FastMail，请将 --allow-net 中的 api.fastmail.com 替换为您 JMAP 服务器的主机名。

使用方法

环境变量

可用工具

get_mailboxes

列出邮箱/文件夹及其 ID、名称和元数据。请先调用此工具以获取 search_emails (inMailbox) 和 move_emails (mailboxId) 所需的邮箱 ID。常见名称：收件箱 (Inbox)、草稿 (Drafts)、已发送 (Sent)、废纸篓 (Trash)、归档 (Archive)、垃圾邮件 (Spam/Junk)。

参数：

• parentId（可选）：按父邮箱 ID 过滤

• limit（可选）：最大结果数（1-200，默认：100）

• position（可选）：分页的起始位置

search_emails

使用过滤器搜索邮件。所有过滤器均为“与”(AND) 关系。 仅返回邮件 ID — 使用 get_emails 获取内容。结果包含用于通过 get_search_updates 进行增量同步的 queryState。

参数：

• query（可选）：跨所有字段的文本搜索

• body（可选）：仅在邮件正文中搜索

• from（可选）：按发件人电子邮件地址过滤

• to（可选）：按收件人电子邮件地址过滤

• subject（可选）：按主题文本过滤

• inMailbox（可选）：要在其中搜索的邮箱 ID（从 get_mailboxes 获取）

• hasKeyword（可选）：按关键字过滤（例如 $seen, $flagged）

• notKeyword（可选）：按关键字排除（例如 $seen, $draft）

• allInThreadHaveKeyword（可选）：会话中的所有邮件必须包含该关键字

• someInThreadHaveKeyword（可选）：会话中至少有一封邮件包含该关键字

• before（可选）：仅限该日期之前的邮件（ISO 8601 日期时间）

• after（可选）：仅限该日期之后的邮件（ISO 8601 日期时间）

• limit（可选）：最大结果数（1-100，默认：50）

• position（可选）：分页的起始位置（默认：0）

get_emails

通过 ID 获取特定邮件。使用 properties 仅请求您需要的字段 — 获取所有属性会返回大量数据。

参数：

• ids：邮件 ID 数组（1-50 个 ID）

• properties（可选）：要返回的特定属性。推荐组合：

  • 摘要：["id", "subject", "from", "to", "receivedAt", "preview"]

  • 完整读取：["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

  • 注意：要获取正文内容，请同时包含 bodyValues 和 textBody/htmlBody

get_threads

通过 ID 获取邮件会话。会话 ID 来自 get_emails 的响应（threadId 属性）。返回每个会话中的邮件 ID — 使用这些 ID 调用 get_emails 以获取内容。

参数：

• ids：会话 ID 数组（1-20 个 ID）

get_email_changes

获取自上次状态以来创建、更新或销毁的邮件 ID。使用 get_emails 响应中的 state 字符串。

参数：

• sinceState：来自先前 get_emails 响应的状态字符串

• maxChanges（可选）：返回的最大变更数（1-500）

• fetchEmails（可选）：自动获取已变更 ID 的完整邮件详情（默认：false）

• properties（可选）：当 fetchEmails 为 true 时要获取的属性

get_search_updates

获取自上次 queryState 以来搜索查询中的变更。必须使用与原始 search_emails 调用相同的过滤器参数。

参数：

• sinceQueryState：来自先前 search_emails 响应的 queryState

• 来自 search_emails 的所有过滤器参数（必须与原始查询匹配）

• maxChanges（可选）：返回的最大变更数（1-500）

mark_emails

将邮件标记为已读/未读或加星标/取消星标。

参数：

• ids：邮件 ID 数组（1-100 个 ID）

• seen（可选）：标记为已读 (true) 或未读 (false)

• flagged（可选）：标记为加星标 (true) 或取消星标 (false)

move_emails

将邮件移动到不同的邮箱。使用 get_mailboxes 查找目标邮箱 ID。

参数：

• ids：邮件 ID 数组（1-100 个 ID）

• mailboxId：目标邮箱 ID（从 get_mailboxes 获取）

delete_emails

永久删除邮件（无法撤销）。建议通过 move_emails 移动到废纸篓以实现可恢复的删除。

参数：

• ids：邮件 ID 数组（1-100 个 ID）

send_email

发送新邮件。需要 textBody 或 htmlBody（或两者）。

参数：

• to：收件人数组（name 可选，email 必需）

• cc（可选）：抄送收件人数组

• bcc（可选）：密送收件人数组

• subject：邮件主题

• textBody（可选）：纯文本正文

• htmlBody（可选）：HTML 正文

• identityId（可选）：发送邮件所用的 JMAP 身份 ID（如果省略，则使用服务器默认值）

reply_to_email

回复现有邮件。自动设置收件人/抄送、Re: 主题前缀以及会话邮件头（In-Reply-To, References）。

参数：

• emailId：要回复的邮件 ID

• replyAll（可选）：包含所有原始收件人（默认：false）

• subject（可选）：自定义回复主题（默认为 Re: <original>）

• textBody（可选）：纯文本正文

• htmlBody（可选）：HTML 正文

• identityId（可选）：发送邮件所用的 JMAP 身份 ID（如果省略，则使用服务器默认值）

JMAP 服务器兼容性

此服务器应适用于任何符合 JMAP 标准的电子邮件服务器，包括：

• Cyrus IMAP 3.0+

• Stalwart Mail Server

• FastMail (商业)

• Apache James (支持 JMAP)

开发

在开发模式下运行

just watch          # Run with file watching
just start          # Run without watching

测试

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

架构

该服务器基于以下技术构建：

• Deno：现代 JavaScript/TypeScript 运行时

• @modelcontextprotocol/sdk：MCP 服务器框架

• jmap-jam：轻量级、类型化的 JMAP 客户端

• Zod：运行时类型验证

安全性

• 所有输入均使用 Zod 模式进行验证

• 环境变量用于敏感配置

• 响应中不会记录或暴露任何机密信息

• 遵循 JMAP 安全最佳实践

贡献

1. Fork 本仓库

2. 创建功能分支

3. 遵循函数式编程风格进行更改

4. 彻底测试您的更改

5. 提交 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

相关项目

• jmap-jam - JMAP 客户端库

• Model Context Protocol - MCP 规范

• JMAP RFC 8620 - JMAP 核心协议

• JMAP RFC 8621 - 用于邮件的 JMAP