jmap-mcp · 协议与工具集成

让 AI 代理直接「操控」邮件：JMAP MCP Server 深度解析

背景故事：为什么 AI 不能直接发邮件？

你用过 Claude 的邮件功能吗？它能读 Gmail——但想发一封带格式的邮件、给邮件加标签、或者自动把某个发件人的来信归到特定文件夹，对不起，做不到。这类操作需要 Gmail API 深度集成，Claude 帮不了你。

这背后是一个更普遍的问题：AI Agent 想操控用户的邮件，但邮件系统千差万别。 Gmail 用的是 Gmail API，Outlook 用的是 Microsoft Graph，Fastmail 用的是 JMAP。如果每次接入都要单独适配，工作量巨大，维护成本更高。

JMAP MCP Server 的作者 Wyatt Johnson 找到了一个优雅的解法——接入 JMAP（JSON Meta Application Protocol）。JMAP 是一种标准化的邮件协议（RFC 8620/8621），被 FastMail、Stalwart Mail Server、Cyrus 等主流邮件服务商采用。只要邮件服务器支持 JMAP，一个 MCP Server 就能通吃所有这些平台。

什么是 MCP？—— AI 工具的 USB 接口

在深入 JMAP 之前，先理解 MCP（Model Context Protocol）。这是 Anthropic 在 2024 年底开源的标准协议，可以理解为 AI Agent 的「USB 接口」——它定义了 AI 如何调用外部工具和数据源。

MCP 的架构非常清晰：

MCP Host：Claude Desktop、Claude Code 这类 AI 应用
MCP Client：Host 内部的客户端组件，负责维护与 MCP Server 的连接
MCP Server：提供具体能力的服务器程序，它暴露「工具」（Tools），AI 可以调用

MCP 架构图

图1：MCP 架构示意（来源：modelcontextprotocol.io）

你可以把 MCP Server 想象成一个个插件——接入了 Sentry MCP，Claude 就能查 bug；接入了 JMAP MCP，Claude 就能管邮件。MCP 本身只定义了通信协议，不限制具体功能。

技术栈解析：为什么选 Deno + TypeScript？

JMAP MCP Server 的技术选型非常有意思：用 Deno 写，用 TypeScript 实现，接入 MCP SDK。

Deno 是 Node.js 作者 Ryan Dahl 的第二个项目，相比 Node.js，Deno 默认安全（所有权限需要显式授予）、内置 TypeScript 支持、标准化依赖管理（通过 URL 直接导入）。对于这种需要网络访问和精确权限控制的服务器程序，Deno 的安全模型更契合。

核心依赖：

@modelcontextprotocol/sdk：Anthropic 官方的 MCP SDK，封装了 JSON-RPC 通信、工具注册、参数校验等核心逻辑
jmap-jam：JMAP 客户端库，封装了 RFC 8620 的会话发现、认证、API 调用等底层细节
zod：运行时类型校验库，确保 MCP 工具接收的参数符合预期格式

核心工具集：AI 能对邮件做什么？

JMAP MCP Server 注册了四大类工具，完整覆盖邮件管理生命周期：

1. 邮箱查询类

get_mailboxes：获取所有邮箱/文件夹，返回 ID 和层级关系，这是第一步，因为后续搜索和移动邮件需要邮箱 ID
get_emails：根据 ID 获取邮件详情，支持选择返回哪些字段（headers、bodyValues、textBody 等），避免无谓的数据传输

2. 搜索过滤类

search_emails：功能最强大的搜索工具，支持组合过滤：
- from/to：按发件人/收件人地址过滤
- subject/query：按主题/全文搜索
- hasKeyword/notKeyword：按邮件标签过滤（如 $seen、$flagged）
- before/after：按日期范围过滤
- body：仅搜索邮件正文（区别于 query 的全字段搜索）
get_email_changes：get_search_updates：基于 JMAP 状态变化的增量同步，AI 轮询时可以只拉取新增/变更的邮件，而不是每次全量拉取

3. 邮件操作类

mark_emails：标记邮件为已读/未读、加星/取消星
move_emails：将邮件移动到指定邮箱
delete_emails：永久删除邮件

4. 邮件发送类

send_email：发送新邮件，支持纯文本和 HTML 格式，可指定发件身份（identityId）
reply_to_email：回复邮件，支持 reply-all，自动处理 In-Reply-To 等邮件头

所有工具参数都通过 Zod Schema 定义了严格的类型和校验规则，并附带了详细的描述文本——这些描述直接成为 AI 理解工具用途的 Prompt，是 MCP 工具设计的关键细节。

部署体验：3 分钟跑起来

对于 Claude Code 用户，项目提供了插件市场一键安装：

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

然后配置三个环境变量：

JMAP_SESSION_URL：JMAP 服务器的会话端点（如 FastMail 的 https://api.fastmail.com/jmap/session）
JMAP_BEARER_TOKEN：API 认证令牌
JMAP_ACCOUNT_ID：（可选）账户 ID，不填则自动探测

对于非 Claude Code 用户，也支持直接在 Claude Desktop 中配置：

{
  "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.4"],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Docker 部署同样简洁。项目提供了多阶段 Dockerfile：第一阶段缓存依赖，第二阶段构建最终镜像，运行时以 deno 非 root 用户运行，并预先执行 TypeScript 类型检查，确保启动零等待。

架构亮点：能力感知与权限隔离

JMAP MCP Server 有一个设计细节值得注意：能力感知（Capability-aware）工具注册。

JMAP 协议支持扩展能力，不同邮件服务器支持的特性可能不同。MCP Server 在初始化时会检查 JMAP Session 的 capabilities：

如果服务器支持 urn:ietf:params:jmap:mail，注册邮箱读写工具
如果服务器还支持 urn:ietf:params:jmap:submission 且账户不是只读，才注册发送工具

这种设计让同一个 MCP Server 可以安全地接入不同能力的 JMAP 服务器，避免在不支持的服务器上调用不存在的 API 导致失败。

此外，Deno 运行时的权限控制被充分利用：Dockerfile 中 --allow-net 只放行目标邮件服务器域名，--allow-env 只允许读取 JMAP 相关的环境变量，实现了最小权限原则。

局限与注意事项

依赖 JMAP 兼容服务器：不支持 Gmail、Outlook 等非 JMAP 邮件服务。如果你用 FastMail、Stalwart 等，自在；如果用的是国内邮箱服务，大概率不兼容
纯 CLI，无 Web UI：这是一个 MCP Server，不是独立的 Web 应用，不适合不懂技术配置环境的用户
只读账户的处理：如果 JMAP 账户是只读模式，urn:ietf:params:jmap:submission 能力不会被注册，发送工具不会注册，但搜索、标记、移动工具仍然可用

行业意义：AI Agent 标准化数据接入的范式

JMAP MCP Server 的出现，折射出 AI Agent 时代的一个大趋势：数据接入标准化。

过去，每个 AI 应用想接邮件，都要自己写 Gmail/Outlook/QQ 邮箱的适配器，维护成本极高。MCP 出现后，一次实现，处处运行——只要 AI 应用支持 MCP（现在 Claude、Cursor、Windsurf 等都支持了），就能无缝接入 JMAP MCP。

更重要的是，JMAP 作为邮件协议标准，让 AI Agent 不绑定特定邮件服务商。用户可以自由切换邮件提供商（从 FastMail 换到 ProtonMail），而不需要重新配置 AI 工具。这种解耦对重视数据主权和技术自主性的用户尤为重要。

项目信息

项目	值
Stars	175
语言	TypeScript / Deno
许可证	MIT
官方文档	GitHub
包管理	JSR (@wyattjoh/jmap-mcp)

让 AI 代理直接「操控」邮件：JMAP MCP Server 深度解析

背景故事：为什么 AI 不能直接发邮件？

什么是 MCP？—— AI 工具的 USB 接口

MCP 的架构非常清晰：

MCP Host：Claude Desktop、Claude Code 这类 AI 应用
MCP Client：Host 内部的客户端组件，负责维护与 MCP Server 的连接
MCP Server：提供具体能力的服务器程序，它暴露「工具」（Tools），AI 可以调用

MCP 架构图

图1：MCP 架构示意（来源：modelcontextprotocol.io）

技术栈解析：为什么选 Deno + TypeScript？

JMAP MCP Server 的技术选型非常有意思：用 Deno 写，用 TypeScript 实现，接入 MCP SDK。

核心依赖：

@modelcontextprotocol/sdk：Anthropic 官方的 MCP SDK，封装了 JSON-RPC 通信、工具注册、参数校验等核心逻辑
jmap-jam：JMAP 客户端库，封装了 RFC 8620 的会话发现、认证、API 调用等底层细节
zod：运行时类型校验库，确保 MCP 工具接收的参数符合预期格式

核心工具集：AI 能对邮件做什么？

JMAP MCP Server 注册了四大类工具，完整覆盖邮件管理生命周期：

1. 邮箱查询类

get_mailboxes：获取所有邮箱/文件夹，返回 ID 和层级关系，这是第一步，因为后续搜索和移动邮件需要邮箱 ID
get_emails：根据 ID 获取邮件详情，支持选择返回哪些字段（headers、bodyValues、textBody 等），避免无谓的数据传输

2. 搜索过滤类

search_emails：功能最强大的搜索工具，支持组合过滤：
- from/to：按发件人/收件人地址过滤
- subject/query：按主题/全文搜索
- hasKeyword/notKeyword：按邮件标签过滤（如 $seen、$flagged）
- before/after：按日期范围过滤
- body：仅搜索邮件正文（区别于 query 的全字段搜索）
get_email_changes：get_search_updates：基于 JMAP 状态变化的增量同步，AI 轮询时可以只拉取新增/变更的邮件，而不是每次全量拉取

3. 邮件操作类

mark_emails：标记邮件为已读/未读、加星/取消星
move_emails：将邮件移动到指定邮箱
delete_emails：永久删除邮件

4. 邮件发送类

send_email：发送新邮件，支持纯文本和 HTML 格式，可指定发件身份（identityId）
reply_to_email：回复邮件，支持 reply-all，自动处理 In-Reply-To 等邮件头

部署体验：3 分钟跑起来

对于 Claude Code 用户，项目提供了插件市场一键安装：

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

然后配置三个环境变量：

JMAP_SESSION_URL：JMAP 服务器的会话端点（如 FastMail 的 https://api.fastmail.com/jmap/session）
JMAP_BEARER_TOKEN：API 认证令牌
JMAP_ACCOUNT_ID：（可选）账户 ID，不填则自动探测

对于非 Claude Code 用户，也支持直接在 Claude Desktop 中配置：

{
  "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.4"],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

架构亮点：能力感知与权限隔离

JMAP MCP Server 有一个设计细节值得注意：能力感知（Capability-aware）工具注册。

JMAP 协议支持扩展能力，不同邮件服务器支持的特性可能不同。MCP Server 在初始化时会检查 JMAP Session 的 capabilities：

如果服务器支持 urn:ietf:params:jmap:mail，注册邮箱读写工具
如果服务器还支持 urn:ietf:params:jmap:submission 且账户不是只读，才注册发送工具

这种设计让同一个 MCP Server 可以安全地接入不同能力的 JMAP 服务器，避免在不支持的服务器上调用不存在的 API 导致失败。

局限与注意事项

依赖 JMAP 兼容服务器：不支持 Gmail、Outlook 等非 JMAP 邮件服务。如果你用 FastMail、Stalwart 等，自在；如果用的是国内邮箱服务，大概率不兼容
纯 CLI，无 Web UI：这是一个 MCP Server，不是独立的 Web 应用，不适合不懂技术配置环境的用户
只读账户的处理：如果 JMAP 账户是只读模式，urn:ietf:params:jmap:submission 能力不会被注册，发送工具不会注册，但搜索、标记、移动工具仍然可用

行业意义：AI Agent 标准化数据接入的范式

JMAP MCP Server 的出现，折射出 AI Agent 时代的一个大趋势：数据接入标准化。

项目信息

项目	值
Stars	175
语言	TypeScript / Deno
许可证	MIT
官方文档	GitHub
包管理	JSR (@wyattjoh/jmap-mcp)