Commonpost MCP for Thunderbird

Thunderbird 的 Commonpost MCP

让 AI 助手全面访问 Thunderbird——搜索邮件、撰写消息、管理过滤器并整理收件箱。所有操作均通过 Model Context Protocol 完成。

这是 Tomasz Kasperczyk 的 thunderbird-mcp（MIT）的延续项目，从其 0.7.5 版本开始开发，并保留了完整的历史记录。这是 Commonpost 社区的独立项目，并非原项目，也未获其认可；它可以与原项目并行安装（参见迁移）。如果原作者希望取回这部分成果，我们愿意交还：我们的更改采用 MIT 许可，也会提供给上游项目。Thunderbird 是 Mozilla Foundation 的商标；本项目与 Mozilla 或 MZLA 无关。

原项目的灵感来自 bb1/thunderbird-mcp。本版本包含的内容列于变更日志。

---

快速安装（约 3 分钟）

1. 安装扩展。 从最新版本下载 commonpost-mcp-v<version>.xpi。在 Thunderbird 中：工具 > 附加组件和主题 > 齿轮菜单 > 从文件安装附加组件。重启 Thunderbird。

2. 从同一版本下载 mcp-bridge.cjs，并将其放入你会长期保留的文件夹，例如 ~/commonpost-mcp/。桥接程序是一个独立文件，不需要其他文件：该版本不包含 package.json。（桥接程序自带版本信息；不会读取任何 package.json。）

3. 检查 Node.js：node --version 必须显示 22 或更高版本。

4. 在 MCP 客户端中注册桥接程序。

   • Claude Code，使用插件（无需手动下载或更新文件；参见 Claude Code 插件）：

     claude plugin marketplace add commonpost/thunderbird-mcp
     claude plugin install commonpost-mcp@commonpost
     

   • Claude Code，使用文件（请使用文件的绝对路径）：

     claude mcp add commonpost-mail -- node /absolute/path/to/mcp-bridge.cjs
     

   • Claude Code on Windows，例如：

     claude mcp add commonpost-mail -- node C:\Users\<you>\commonpost-mcp\mcp-bridge.cjs
     

   • 其他客户端：将以下内容添加到客户端的 MCP 配置中（Claude Desktop、VS Code、Cursor、Codex CLI 和 Gemini CLI 各有自己的文件和格式：参见其他 MCP 客户端）。在 JSON 中，Windows 路径请使用 / 或将反斜杠加倍（"C:/Users/<you>/commonpost-mcp/mcp-bridge.cjs"）。

     {
       "mcpServers": {
         "commonpost-mail": {
           "command": "node",
           "args": ["/absolute/path/to/mcp-bridge.cjs"]
         }
       }
     }
     

5. 测试。保持 Thunderbird 打开，并向助手询问：“列出我的 Thunderbird 账户”。

桥接程序不会自动更新，而且每个 MCP 客户端都有自己的桥接程序。 当需要替换桥接程序时，扩展会在工具结果中提示（助手会将提示转达给你），也会在其选项页面的 Bridge 部分显示提示。该部分会列出已连接的桥接程序，并标注“已是最新版本”“有较新版本可用”（当前仍可使用；更新为可选操作）或“建议更新”。对于需要更新的桥接程序或被扩展拒绝的桥接程序，Thunderbird 也会显示系统通知，每个桥接程序在每个 Thunderbird 会话中显示一次；将隐藏首选项 extensions.commonpost-mcp.bridgeUpdateAlert 设为 false 可关闭通知。每个版本发布页面开头都会说明该版本带来的变化、是否更改桥接程序，以及操作步骤：下载 mcp-bridge.cjs 并替换你现有的副本（其路径位于客户端的 MCP 配置中；在 Claude Code 中运行 claude mcp get <server name>），然后重新连接 MCP 客户端（在 Claude Code 中运行 /mcp）；在 Claude Desktop 中，重新安装 .mcpb bundle；使用 Claude Code 插件时，更新插件。未更改桥接程序的版本会再次附带相同的桥接程序。扩展版本显示在工具 > 附加组件和主题中。

安装完成后，请立即打开扩展的选项页面（工具 > 附加组件和主题 > Commonpost MCP for Thunderbird > 选项），并选择助手可以使用哪些账户和工具。在此之前，MCP 客户端可以看到所有账户和工具。

在大多数情况下，Snap、Flatpak 和 macOS 无需额外操作；参见沙盒感知连接发现。如果遇到问题，请参见故障排除。

---

为什么？

Thunderbird 没有面向 AI 工具的官方 API。你的 AI 助手无法读取邮件、帮你起草回复或整理收件箱。此扩展解决了这个问题——它通过 MCP 暴露 40 个工具，让任何兼容的 AI（Claude、GPT、本地模型）都能按你预期的方式处理邮件。它符合 Cursor 对每个服务 40 个工具的限制。

默认情况下，发送邮件以及创建事件／任务都需要经过审核，因为 Block skipReview 默认处于启用状态。只有在你明确关闭此安全设置后，skipReview: true 才会生效。默认情况下，未经你审核，不会发送任何内容或创建任何项目。

---

工作原理

                    stdio              HTTP (localhost:8780-8789)
  MCP Client  <----------->  Bridge  <--------------------->  Thunderbird
  (Claude, etc.)           mcp-bridge.cjs                    Extension + HTTP Server

Thunderbird 扩展内置了一个本地 HTTP 服务，使用会话范围的身份验证令牌。Node.js 桥接程序负责在 MCP 的 stdio 协议与 HTTP 之间转换，并通过连接文件自动发现端口和令牌。桥接程序会在本地处理 MCP 生命周期方法（initialize、ping），因此即使 Thunderbird 尚未完全加载，客户端也能连接。

---

你可以做什么

邮件

工具	描述
listAccounts	列出所有电子邮件账户及其身份
listFolders	浏览文件夹树及邮件数量——可按账户或子树筛选；savedSearches 则列出已保存的搜索；使用 folderPath 执行 refresh 时，会先从该文件夹的邮件服务器（IMAP、Exchange、Graph；不包括新闻或订阅源）获取新邮件，等待时间最长为 20 s
searchMessages	跨账户搜索邮件头。所有词都必须匹配（主题、发件人、收件人、抄送、预览）；可组合使用运算符 from:、to:、cc:、subject:、participant:（发件人/收件人/抄送/密送；@domain 仅匹配该域中的地址，逗号用于列出多个选项：participant:@acme.com,@acme-group.com）和带引号的短语，例如 participant:@acme.com subject:"invoice 42"。groupBy: "sender" | "thread" 会按发件人或会话返回一行（latestId 是最新的非草稿邮件）；threadOf: {messageId, folderPath} 会跨文件夹返回整个会话（包括已发送邮件），按时间从旧到新排列（最多读取 10,000 个邮件头，之后设置 incomplete: true）。如果发出的 Re: 邮件没有线程头信息，则会按主题加入其发件人参与过的较早邮件（linkedBy: "subject"）；同一封邮件分别发送给多个人，以及重复的通知，仍会单独显示。筛选条件会选出会话中的邮件，但不会切断会话关联。除非设置 includeTrash 或明确指定 folderPath，否则会跳过废纸篓和垃圾邮件。始终返回 { messages, totalMatches, offset, limit, hasMore }（默认 20 行，最多 200 行）；format: "table" 返回 { columns, rows }，format: "legacy" 返回 0.10 及更早版本的输出（已弃用），详见 CHANGELOG。还支持 countOnly、includeSubfolders、日期范围、未读/已标记/标签筛选、searchBody（Gloda 全文搜索：少于 3 个字符的词会被忽略并列在 warning 中；英文词会匹配其他词形，俄语和其他语言则只匹配完全相同的词形）以及 dedupByMessageId（多个文件夹中的副本会合并为一行，并包含 dupLocations）。attachmentName（文件名中的任意部分，不区分大小写）和 attachmentType（application/pdf 或 image/ 这样的前缀）可与其他筛选条件组合，仅保留带有匹配附件的邮件；每行会列出匹配的附件（name、contentType、size）。仅会读取 Thunderbird 标记为带附件的邮件，并从其本地副本读取（不会下载或解密）；每次调用最多读取 500 封邮件，每封最大 16 MiB；attachmentSearch 会说明已检查的数量，以及其他邮件被跳过的原因（encrypted、tooLarge、notOffline、unreadable、limitReached）。Thunderbird 根据邮件顶层结构判断邮件是否带附件，因此通常无法找到已签名邮件（multipart/signed）、multipart/related 邮件或单部分附件。虽然不允许读取加密邮件，但与未设置附件选项时相同，包含词语的查询会排除带有加密封套的邮件。attachmentName 和 attachmentType 不能与 searchBody、threadOf 或 format: "legacy" 组合使用。
getMessage	读取完整邮件内容——bodyFormat：markdown（默认）、text 或 html。正文有长度上限（maxBodyChars，默认为 20000）；正文较长时会设置 bodyTruncated 和 nextBodyOffset，使用 bodyOffset 读取剩余内容。设置 rawSource: true 可获取完整的 RFC 2822 源码（同样受长度上限限制）；如果内容是有效的 UTF-8，则按 UTF-8 解码，否则使用其顶层、部分或检测到的字符集（rawCharset）。如果各部分声明了不同的字符集，会给出 warning 并列出 rawMixedCharsets；如果无效的 UTF-8 字符被替换，也会给出警告。rawEncoding: "base64" 会返回精确字节。可选保存附件。设置 includeInlineImages: true 可将受支持的内联 CID 图片作为 MCP 图片块附加到末尾（PNG、JPEG、GIF 或 WebP；每张图片的 base64 最大为 1 MiB，总计最大为 4 MiB）。被跳过的图片会列在附件元数据中。
getMessages	一次调用即可读取配置批次上限内多封邮件的完整内容（默认为 10，最多 20）。使用与 getMessage 相同的 bodyFormat、rawSource 和附件选项；每项提供 messageId 和 folderPath。每封邮件的正文都有长度上限（maxBodyChars，默认为 4000）。headersOnly 仅返回收到时的邮件头和标记，最多可读取 200 封邮件，不受批次上限影响，也不会解析任何正文；如果存在 List-Unsubscribe 邮件头，还会将其解析为仅供查看的 unsubscribe（mailto、https、oneClick）。
getRecentMessages	从所有文件夹（跳过废纸篓/垃圾邮件）或单个文件夹中按时间从新到旧获取最近邮件——支持 daysBack（默认为 7）、未读/已标记筛选、includeTrash 和分页。信封、行和 format 与 searchMessages 相同。
displayMessage	在 Thunderbird 图形界面中打开邮件——支持 3pane（默认）、tab 或 window 模式
updateMessage	标记为已读/未读、标记/取消标记、添加/移除标签、在文件夹之间移动，或移至废纸篓——支持通过 messageIds 批量操作
deleteMessages	删除邮件——草稿会安全地移至废纸篓
createFolder	创建新的子文件夹以整理邮件，或使用 savedSearch 创建已保存的搜索（虚拟文件夹：实时视图，不会移动邮件）
renameFolder	重命名现有邮件文件夹；返回其新的 URI，作为 path
deleteFolder	删除文件夹（移至废纸篓；如果已在废纸篓中，则永久删除）；已保存的搜索会作为视图移除，不会删除邮件
moveFolder	在同一账户内将文件夹移动到新的父文件夹中
emptyTrash	永久删除废纸篓中的所有邮件（包括子文件夹）
emptyJunk	永久删除垃圾邮件/Spam 中的所有邮件（包括子文件夹）

撰写

工具	说明
sendMail	撰写新邮件——打开审核窗口；直接发送需要明确关闭 skipReview 安全拦截，并会像撰写窗口一样添加身份签名和自动抄送／密送；dryRun 会报告调用将执行的操作（发件人、收件人、附件、估算大小）或将返回的错误，不会执行任何操作
replyToMessage	回复邮件，引用原文并正确加入会话线程，使用 Thunderbird 会选择的身份。mode：window（默认）打开审核窗口；draft 保存草稿，使用 Thunderbird“回复／全部回复”计算出的收件人，以及其回复窗口生成的正文（引用提示行、引文、签名、回复位置）；send（或 skipReview: true）直接发送——需要明确指定 to 和 from，并受相同的安全拦截限制。latestInThread: true（仅适用于 window 或 draft）会回复会话中最新的邮件，包括“已发送”文件夹中的邮件，并将其作为 repliedTo 返回；结果中的 threadIncomplete 表示大型邮箱仅读取了部分内容，可能存在更新的邮件
forwardMessage	转发邮件，保留所有原始附件，并使用 Thunderbird 会选择的身份。mode 与 replyToMessage 相同（draft 和 send 会采用 Thunderbird 转发窗口生成的主题和正文：标题表格、原始正文、签名）；除 send 外，to 为可选项；send 需要明确指定 to 和 from
saveDraft	将新邮件保存为草稿，方式与 Thunderbird 撰写窗口相同（包含身份签名）；也可通过 draftId 编辑现有草稿——返回其 messageId 和 folderPath

默认情况下，所有撰写工具都会打开窗口，供你在发送前审核和编辑。默认启用 Block skipReview 首选项，因此在你明确关闭该首选项前，skipReview: true（以及 mode: "send"）都会被拒绝。mode: "draft" 只会保存草稿，因此该首选项不会拦截此操作（即使同时使用 skipReview: true）；此操作需要在设置中启用 saveDraft 工具，因为你禁用的工具无法通过其他工具调用。附件可以是文件路径，也可以是内联 base64 对象。

直接发送或保存草稿（saveDraft、mode: "draft"）可能需要一段时间：桥接程序最多等待 Thunderbird 180 秒（其他调用为 30 秒）。你的 MCP 客户端也可能为工具调用设置自己的时限；如果时限短于 180 秒，客户端可能会放弃等待，但 Thunderbird 仍会继续发送或保存。因此，重试前请检查“已发送”和“发件箱”文件夹（或“草稿”文件夹），以免重复发送邮件或重复保存草稿。

撰写工具会严格验证 from 身份——如果指定的发件人不匹配任何已配置的 Thunderbird 身份，工具会返回错误，而不会静默替换为其他账户。

筛选规则

工具	描述
listFilters	列出所有筛选规则及其易读的条件和操作；使用 confirmation: true 时，改为读取待处理或最近一次确认的状态，也可通过 confirmationId 指定某次确认（见下文）
createFilter	使用结构化条件（发件人、主题、日期等）和操作（移动、添加标签、标记等）创建筛选规则
updateFilter	修改筛选规则的名称、启用状态、条件或操作
deleteFilter	按索引删除筛选规则
reorderFilters	更改筛选规则的执行优先级
applyFilters	按需对文件夹运行筛选规则——让 AI 整理收件箱

全面控制 Thunderbird 的邮件筛选规则。更改会立即保存。AI 可以创建分类规则、调整优先级，并对现有邮件运行筛选规则。applyFilters 只会运行已启用且标记为“手动运行”的规则（在规则编辑器中勾选允许助手启动的规则），并列出跳过的规则。

会转发或回复邮件的筛选规则会直接发送邮件，不会经过撰写工具提供的审核窗口。默认启用 阻止筛选规则转发/回复 设置（选项 > 发送安全）：启用时，无法通过 MCP 创建或更改此类规则，包含此类规则的筛选规则列表也无法通过 applyFilters 运行。仍可删除该规则。如果改为选择 每次都询问我，此类请求会返回 pending_user_confirmation，Thunderbird 也会显示一个对话框，其中包含规则、条件和完整目标地址；除非你在对话框中确认，否则不会写入任何内容。关闭对话框或在十分钟内未作答，也不会写入任何内容。

加密邮件

默认情况下，不会为助手解密 OpenPGP 和 S/MIME 邮件：getMessage 会返回邮件头和简短提示，而不是邮件内容。searchMessages 会省略查询匹配到的此类邮件，getRecentMessages 会列出此类邮件并显示线缆级主题，不提供预览，并标记 encrypted: true；threadOf 会省略此类邮件，且绝不会通过其主题关联对话。启用 允许助手读取加密邮件 设置（选项 > 加密邮件）后，加密邮件会被解密并交给助手，也会交给运行该助手的服务。

联系人

工具	描述
searchContacts	在所有通讯录中按电子邮件地址、姓名或组织搜索联系人（例如 acme 或 @acme.com）；空字段会被省略。支持 maxResults 和 format: "table"。
getContact	按 UID 读取完整联系人详情，包括所有电子邮件地址（emails：地址、工作/家庭类型、主要地址；如果存储的值不是单个纯地址，则标记 invalid: true）
createContact	创建联系人，可选提供一个或多个 emails（工作/家庭类型，其中一个为主要地址）、姓名、电话、邮寄地址、组织、职务、备注和生日。也支持仅包含电话号码的联系人。
updateContact	更新联系人字段；未提供的字段保持不变；emails、电话和地址会替换各自列表（空数组会清空列表），单独提供 email 只会更改主要地址
deleteContact	按 UID 删除联系人

日历

工具	描述
listCalendars	列出所有日历，并显示只读、已禁用、事件和任务支持标志
createEvent	创建日历事件——会打开审核对话框；通过 skipReview 直接创建需要显式禁用默认安全拦截。接受 status: tentative | confirmed | cancelled（iCal RFC 5545 中的 VEVENT STATUS）和 showAs: busy | free（该时段是否被占用；不会更改 status）。reminders 用于添加显示提醒，单位为开始前的分钟数（最多 5 个，范围为 0 到 40320）。
listEvents	按日期范围查询事件，并展开重复事件；未指定时间的日期表示当地时间的一整天。每个事件均返回 status 和 reminders（显示提醒，即开始前的分钟数）。支持 maxResults 和 format: "table"。
updateEvent	修改事件的标题、日期、地点、描述、status、showAs 或 reminders（替换显示提醒；[] 会移除提醒；保留电子邮件、音频、绝对时间和与结束时间相关的提醒，也保留分钟数未变的提醒；重复事件的例外事件保留各自的提醒）
deleteEvent	按 ID 删除日历事件
createTask	打开已预填任务内容的对话框以供审核；通过 skipReview 直接创建需要显式禁用默认安全拦截
listTasks	列出日历中的任务/待办事项——可按完成状态、截止日期或日历筛选。支持 maxResults 和 format: "table"。
updateTask	更新任务的标题、截止日期、描述、优先级、完成状态或完成百分比
listCategories	列出 Thunderbird 中定义的日历类别名称，供事件和任务按原样使用

访问控制

工具	描述
getAccountAccess	查看 MCP 服务可访问的账户

账户和工具访问权限通过扩展设置页面（Tools > Add-ons > Commonpost MCP for Thunderbird > Options）配置。访问控制不通过 MCP 暴露——只有用户可以更改。

同一设置页面中有一个“Send Safety”部分。默认启用 Block skipReview，会拒绝 sendMail、replyToMessage、forwardMessage、createEvent 和 createTask 的 skipReview: true（以及 replyToMessage 和 forwardMessage 的 mode: "send"）；其审核窗口或对话框仍会照常打开。只有显式禁用此首选项后，skipReview 才会生效。

---

设置

1. 安装扩展

从最新版本下载 commonpost-mcp-v<version>.xpi，然后在 Thunderbird 中依次选择：工具 > 附加组件和主题 > 齿轮菜单 > 从文件安装附加组件，然后重启。每个版本还附带来源证明（*.sigstore.json），将 XPI 与构建它的提交和工作流关联起来；你可以使用 gh attestation verify <file>.xpi --repo commonpost/thunderbird-mcp 进行验证。使用带标签的源代码运行 node scripts/build-xpi-reproducible.cjs，即可逐字节重建 XPI。

MCP 桥接程序 mcp-bridge.cjs 与 XPI 一同附在每个版本中（并有自己的来源证明）。你也可以运行 git clone --branch v<version> https://github.com/commonpost/thunderbird-mcp.git，然后使用克隆中的文件；请使用与扩展版本相同的桥接程序。

要求使用 Thunderbird 140 或更高版本，桥接程序（mcp-bridge.cjs）要求使用 Node.js 22 或更高版本。已在 Thunderbird 140.16.0esr、153.3.1esr 和 156.0.1 上测试。

自动更新： 附加组件会通过 Thunderbird 的附加组件更新检查，检查 https://commonpost.github.io/thunderbird-mcp/updates.json；该文件列出了每个版本的哈希值。Thunderbird 会在后台下载更新，并在下次重启时应用；由于此附加组件使用 Experiment API，更新不会热切换。如果没有收到更新，请检查附加组件齿轮菜单，并确保已启用自动更新附加组件。Thunderbird 默认的 xpinstall.signatures.required=false 允许安装未签名的附加组件；若配置文件经过强化，要求必须签名，则会阻止手动和自动安装。由于自动更新通道用于分发代码，你可以将其关闭（在该附加组件的详情页中设置），并手动更新。桥接程序不会自动更新： 当需要将你的 mcp-bridge.cjs 或 .mcpb 替换为较新版本中的文件时，附加组件会通过工具结果和其选项页的 Bridge 部分通知你；然后重新连接 MCP 客户端。部分防护机制位于桥接程序中。

2. 配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中（例如，Claude Code 使用 ~/.claude.json）：

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "node",
      "args": ["/absolute/path/to/commonpost-mcp/mcp-bridge.cjs"]
    }
  }
}

Claude Code 插件

此仓库也是一个 Claude Code 插件市场：插件 commonpost-mcp 声明了 commonpost-mail MCP 服务，并包含该版本的桥接程序，因此无需下载或手动替换 mcp-bridge.cjs。

claude plugin marketplace add commonpost/thunderbird-mcp
claude plugin install commonpost-mcp@commonpost

• 插件（plugins/claude-code/）仅包含桥接程序，即此仓库中由版本检查确保保持一致的 mcp-bridge.cjs 副本；请单独安装 Thunderbird 扩展（见上文第 1 步）。Node.js 22 或更高版本必须位于 PATH 中。
• 更新：除非启用自动更新（/plugin > Marketplaces > Enable auto-update），否则 Claude Code 不会自行更新第三方市场。若未启用，请运行 /plugin marketplace update commonpost（或 claude plugin update commonpost-mcp@commonpost），然后运行 /reload-plugins。每次发布都会提高插件版本，因此每个版本发布后都会触发更新，无论桥接程序是否更改；插件中的桥接程序始终是该版本中的文件。
• 工具名称包含插件和服务名称，例如：mcp__plugin_commonpost-mcp_commonpost-mail__searchMessages。为通过文件添加的服务编写的权限规则（mcp__commonpost-mail__*）不适用于这些工具。附加组件选项页的 Bridge 部分会将此桥接程序列为 mcp-bridge.cjs 文件。
• 插件通过 git 从此仓库获取（使用 main，或使用 claude plugin marketplace add commonpost/thunderbird-mcp#vX.Y.Z 固定到某个发布标签，自 v0.17.0 起）；它未经签名。插件中的桥接程序是该提交中的 mcp-bridge.cjs，也是每个版本都会提供来源证明的同一文件。

Claude Desktop（一键安装包）

在 macOS 和 Windows 上，Claude Desktop 可以通过 .mcpb 安装桥接程序，无需手动编辑配置文件。从最新版本下载 commonpost-mcp-v<version>.mcpb，然后用 Claude Desktop 打开并确认安装。如果文件无法在 Claude Desktop 中打开（Windows 上可能未将其关联到 Claude Desktop），请使用“Settings” > “Extensions” > “Advanced settings” > “Install Extension”，然后选择该文件。

• 安装包仅包含桥接程序（mcp-bridge.cjs）。请单独安装 Thunderbird 扩展（上面的步骤 1）。安装包中的版本号是其中桥接程序的版本号，只有桥接程序发生变化时才会更新：发布版本可能会附带一个版本号低于附加组件的安装包，但它仍然是当前版本的桥接程序。Claude Desktop 不会更新从文件安装的安装包：当附加组件（在工具结果或其选项页面的 Bridge 部分中）提示时，请安装新的 .mcpb。
• 与桥接程序一样，该安装包要求 Node.js 22 或更高版本。安装包没有设置项：如果桥接程序找不到连接文件，请在其他 MCP 客户端中使用 COMMONPOST_MCP_CONNECTION_FILE 进行手动配置。
• 安装包未经签名。每个版本都会附带该安装包的来源证明（*.mcpb.sigstore.json）：使用 gh attestation verify <file>.mcpb --repo commonpost/thunderbird-mcp 验证。也可以从已标记的源代码通过 node scripts/build-mcpb-reproducible.cjs 逐字节重建。

其他 MCP 客户端

该桥接程序是标准的 MCP stdio 服务，不与任何特定客户端绑定：任何能够启动本地服务的客户端都可以使用它。上面的 mcpServers 布局很常见，但并非通用，因此下面为每个客户端分别列出其配置文件和格式。所有情况下，都请使用 mcp-bridge.cjs 的绝对路径和服务名称 commonpost-mail，然后重启客户端。

Claude Desktop。 编辑 claude_desktop_config.json（通过 Settings > Developer > Edit Config 打开）：macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的路径为 %APPDATA%\Claude\claude_desktop_config.json。在 JSON 中，Windows 路径的反斜杠需要加倍。

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\commonpost-mcp\\mcp-bridge.cjs"]
    }
  }
}

Visual Studio Code。 编辑工作区中的 .vscode/mcp.json，或为你的用户配置文件运行 "MCP: Open User Configuration"。顶层键为 servers（不是 mcpServers），stdio 服务需要 "type": "stdio"。

{
  "servers": {
    "commonpost-mail": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bridge.cjs"]
    }
  }
}

Cursor。 编辑 ~/.cursor/mcp.json（适用于所有项目）或 .cursor/mcp.json（适用于单个项目）。顶层键为 mcpServers。

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bridge.cjs"]
    }
  }
}

OpenAI Codex CLI。 编辑 ~/.codex/config.toml（或受信任项目中的 .codex/config.toml）。这是 TOML，而不是 JSON：每个服务使用一个表。

[mcp_servers.commonpost-mail]
command = "node"
args = ["/absolute/path/to/mcp-bridge.cjs"]

Gemini CLI。 编辑 ~/.gemini/settings.json（或项目中的 .gemini/settings.json）。顶层键为 mcpServers。其中的 env 块会展开 $VAR、${VAR} 以及 Windows 上的 %VAR% 引用，因此包含 $ 或 % 的值会被修改。

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bridge.cjs"]
    }
  }
}

桥接程序通常会自动找到 Thunderbird 的连接文件，因此无需设置环境变量。只有在找不到连接文件时，才在服务的环境中将 COMMONPOST_MCP_CONNECTION_FILE 设为该文件的实际路径：JSON 格式中，在 args 旁边添加 "env": { ... } 对象；Codex 中使用 [mcp_servers.commonpost-mail.env] 表（参见适配沙盒的连接发现；在 Windows 上，该文件必须位于桥接程序自己的 %TEMP% 下）。此处设置的路径会替代自动发现，因此绝不能在其中保留占位符。客户端格式可能会变化；如果其中某个格式不再适用，请遵循客户端自己的 MCP 文档，并保持相同的命令和参数。

从另一台电脑使用（SSH）

要在另一台电脑上的 MCP 客户端中使用 Thunderbird，请在运行 Thunderbird 的电脑上运行桥接程序，并 通过 SSH 传输其标准输入和输出。此扩展程序仅在 localhost 上持续监听，邮件则通过加密的 SSH 连接在 网络上传输：

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "ssh",
      "args": ["-o", "BatchMode=yes", "you@thunderbird-host", "node", "/absolute/path/to/mcp-bridge.cjs"]
    }
  }
}

SSH 登录必须能在无提示的情况下完成（使用密钥，且主机已存在于 known_hosts 中）：客户端无法回应 提示，而 BatchMode=yes 会立即使连接失败，而不是一直等待。在那台电脑的非交互式 SSH 会话中，node 必须位于 PATH 中；那台电脑可以运行 Windows（OpenSSH Server）、Linux 或 macOS。建议使用此方式，而不是“监听 所有接口”，后者会通过普通 HTTP 在网络上传输令牌和邮件。

沙盒感知连接发现

桥接程序会在每次缓存未命中时重新发现 connection.json。它按以下顺序尝试这些位置：

1. 如果已设置，则使用 COMMONPOST_MCP_CONNECTION_FILE
2. 原生临时目录：<os.tmpdir()>/commonpost-mcp/connection.json
3. macOS 回退位置：由当前用户拥有的 /var/folders/*/*/T/commonpost-mcp/connection.json
4. Linux Snap：仅在确认进程确实是受限的 Thunderbird snap 时使用（/proc/<pid>/exe 解析后位于 /snap/thunderbird/ 下，且其环境中包含 SNAP_NAME=thunderbird）；从其实时 TMPDIR 读取；只有实际发现此类进程后，才会尝试官方 snap 自带的 ~/Downloads/thunderbird.tmp 回退位置
5. Linux Flatpak / Betterbird Flatpak：真实的 /run/user/<uid>（通过 lstat 验证，绝不信任 $XDG_RUNTIME_DIR 中的值），且仅限于指定的应用 ID：org.mozilla.thunderbird、org.mozilla.thunderbird_esr、org.mozilla.Thunderbird、eu.betterbird.Betterbird

这涵盖了原生安装、官方 Thunderbird snap、Thunderbird Flatpak（包括从不同远程源安装但使用相同应用 ID 的 Beta 渠道）以及 Betterbird Flatpak，无需更改扩展程序端。如果同时存在多个沙盒候选文件，桥接程序会先尝试最新的文件。设置 COMMONPOST_MCP_CONNECTION_FILE 可强制指定单一路径。

覆盖设置示例：

{
  "mcpServers": {
    "commonpost-mail": {
      "command": "node",
      "args": ["/absolute/path/to/commonpost-mcp/mcp-bridge.cjs"],
      "env": {
        "COMMONPOST_MCP_CONNECTION_FILE": "/absolute/path/to/connection.json"
      }
    }
  }
}

就这样。现在，你的 AI 可以访问 Thunderbird 了。

从 thunderbird-mcp 迁移

两个扩展程序可以同时安装：它们使用不同的 ID、首选项、端口（这里是 8780-8789，另一方是 8765-8774）和临时目录。它们之间不会共享或自动迁移任何内容：

• 设置（extensions.thunderbird-mcp.*）不会复制；请在此扩展程序的选项页面中重新设置。在此之前，MCP 客户端可以看到所有账户和工具：你的账户和工具限制不会沿用；
• MCP 客户端必须将其桥接程序指向此仓库中的 mcp-bridge.cjs（或 commonpost-mcp 二进制文件）；如果设置了路径，还必须使用 COMMONPOST_MCP_CONNECTION_FILE（旧的 THUNDERBIRD_MCP_CONNECTION_FILE 会被有意忽略，以确保一个桥接程序不会读取另一个扩展程序的文件）；
• 如果保留两者，选项页面会显示提示，并且每个 MCP 客户端都必须配置为使用你想用的那个。为避免两个服务同时操作同一个邮箱，请停用你不用的那个。

---

安全性

• 身份验证令牌：HTTP 服务器需要一个作用域限于会话的持有者令牌。令牌在启动时生成，并以 0600 权限写入 <TmpD>/commonpost-mcp/connection.json。桥接程序会在原生安装、Snap、Flatpak、Betterbird Flatpak 和 macOS 临时目录中自动重新查找该文件。选项页面还提供一个稳定令牌，它在重启后保持不变，并存储在 Thunderbird 首选项中，而非连接文件中；在插件仍处于启用状态时将其移除会清除该首选项，但如果先禁用插件再移除，则不会清除，因此移除已禁用的插件前，请自行清除该首选项（在选项页面取消勾选“使用稳定令牌”）。
• 动态端口：依次尝试 8780-8789 端口，并将实际使用的端口记录在连接文件中。不依赖硬编码端口。
• 账户访问控制：通过设置页面限制 MCP 客户端可查看的电子邮件账户。更改会立即生效。
• 工具访问控制：通过设置页面禁用特定工具。已禁用的工具不会显示在 tools/list 中，并且会在分发时被拦截。
• 仅限 localhost：默认情况下，服务器仅绑定到 localhost。设置中的“监听所有接口”选项会将服务器绑定到所有 IPv4 接口，以供 WSL、Docker 或远程访问使用。**这会让本地网络上的所有设备都能通过未加密的 HTTP 访问 MCP 服务：令牌和邮件均未加密。**仅在可信网络中启用。始终需要身份验证令牌。从另一台计算机访问时，请改为通过 SSH 运行桥接程序（从另一台计算机访问（SSH））。
• 自动更新完整性：自动更新是一种代码分发渠道，其完整性取决于对 GitHub 仓库、GitHub Actions 令牌和 commonpost GitHub 组织的持续控制。
• 桥接程序版本：桥接程序会在每个请求中通告其版本（X-Commonpost-Bridge 标头）。插件会对低于其推荐版本的桥接程序发出警告，并且可以拒绝低于其代码中设定的安全下限的桥接程序（该功能随附时处于禁用状态）；不会通过互联网检查或下载任何内容。该标头由自身声明：保护服务器的是令牌，而非标头。请参阅 SECURITY.md。

拒绝附件

如果 sendMail、saveDraft、replyToMessage 或 forwardMessage 调用中的附件路径符合以下任一条件，则会拒绝该调用，并使整个调用失败（不会发送、保存或打开任何内容），而不是悄悄丢弃有问题的附件：

• 路径中的任何位置包含点文件或点目录（.ssh、.aws、.config/gcloud、.git-credentials 等）；
• 文件名本身包含凭据或机密，无论文件位于何处（credentials.json、*.ppk、*.jks、*.pem、*.p12、*.kdbx、wallet.dat、terraform.tfstate*、Local State、浏览器 Cookie/登录信息存储等）；
• 系统目录（/etc、/proc、C:\Windows\System32 等）以及每个邮件客户端自己的配置文件目录（Thunderbird 和其他邮件客户端保存凭据的位置）；
• 每个 Thunderbird 配置文件的文件夹，以及每个邮件帐户的本地文件夹，无论它们位于何处（其他驱动器、便携式安装、你选择的文件夹）：扩展会在连接文件中列出这些文件夹，并通过路径、实际路径和文件夹标识来拒绝其中的所有内容，因此指向这些文件夹的链接或同一文件夹的第二个挂载点也会被拒绝。这需要 0.17.1 或更高版本的扩展和桥接程序。不包括：当前运行配置文件之外其他配置文件的帐户文件夹、驱动器根目录下的邮件存储、桥接程序通过另一条路径看到的文件夹（例如在 WSL 或容器中运行的桥接程序），以及在这些文件夹之外创建的副本；
• 在 macOS 上，已登录用户的 Library 文件夹中的任何内容（Mail、Messages、Keychains、Application Support 等），包括其 APFS Data 卷的实际路径形式；
• 在 Windows 上，AppData 及其兼容性联接别名（Local Settings、Application Data、Cookies、Recent、SendTo 等）——但有一个例外：扩展自己的 <TEMP>\commonpost-mcp\ 备份文件夹，因此仍可附加此前保存在其中的附件；即使在该文件夹中，connection.json 本身也会被拒绝；
• UNC 或设备路径（\\server\share\...、\\?\...）、备用数据流，或解析后名称与给定名称不同的 Windows 路径形式（8.3 短文件名、尾随句点或空格）。

桥接程序还会解析附件的实际路径（通过符号链接，以及在 Windows 上通过联接和重解析点），并检查该路径，因此即使被拒绝的文件通过看似无害的名称访问，也仍会被拒绝。扩展无法在 Windows 上执行此操作（Gecko 的 nsLocalFile::IsSymlink 在该平台上没有实现），因此会直接拒绝 Windows 上所有字符串形式的文件路径附件；请在该平台上通过桥接程序附加文件。

---

如果 Thunderbird 在 Release 通道上禁用 Experiment 扩展

此扩展使用 Thunderbird Experiment API（参见 docs/experiment-inventory.md）。Thunderbird 的 Add-ons 团队已宣布计划停止在 Release 通道上运行 Experiment API 扩展，并继续在 ESR（Extended Support Release）通道上支持它们。截至 2026 年 11 月，此事尚未发生。

如果你的 Thunderbird 发生这种情况，导致此扩展停止工作，请切换到 Thunderbird ESR。各平台的下载均可在 Thunderbird 官方网站找到（查找“ESR”版本）。自 0.8.2 起，此扩展便支持 Thunderbird ESR（最低版本为 140.0；参见上方徽章和 CHANGELOG.md）。

---

故障排除

问题	解决方法
扩展未加载	检查“工具”>“附加组件和主题”。错误：工具 > 开发者工具 > 错误控制台
连接被拒绝	确保 Thunderbird 正在运行且已启用扩展
Bridge 找不到 connection.json	如果你的环境使用非标准临时目录/运行时路径，请显式设置 COMMONPOST_MCP_CONNECTION_FILE
在 Windows 上，bridge 找到了文件但仍拒绝访问	文件必须位于 bridge 进程自身的 %TEMP% 下。在 WSL 或容器中运行 bridge 时，它使用的 %TEMP% 与 Thunderbird（原生 Windows）使用的不同，即使可以通过 \\wsl.localhost\... 或挂载访问该文件也是如此——这是正确的拒绝行为，并非错误。请将 COMMONPOST_MCP_CONNECTION_FILE 设置为文件的实际路径
在容器或 WSL 中运行的 bridge 曾通过挂载的临时文件夹找到连接文件，现在却因进程过期或不匹配而被拒绝	bridge 不再信任无法确认与正在运行的 Thunderbird 关联的文件。请将 COMMONPOST_MCP_CONNECTION_FILE 设置为文件的实际路径
在 Windows 上，位于 %TEMP% 下的附件被拒绝	%TEMP% 位于 AppData\Local 下，拒绝列表会将其与 AppData 的其他部分一样处理（其中存有 Windows 上其他程序的凭据和应用数据）。请先将文件复制到其他文件夹，例如“文档”
缺少近期邮件	IMAP 文件夹可能已过时。点击 Thunderbird 中的文件夹进行同步，或右键点击 > 属性 > 修复文件夹
更新后找不到工具	重新连接 MCP（在 Claude Code 中使用 /mcp），以获取新工具
searchBody 未返回结果	IMAP 账户需要启用离线同步，Gloda 才能为邮件正文编制索引
rawSource 在 IMAP 上失败	需要本地/离线邮件副本。启用离线同步，或先点击邮件以将其缓存。

---

开发

# Build the extension
./scripts/build.sh

# Test via the bridge (handles auth automatically)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-bridge.cjs

# Test the HTTP API directly.
# On Snap / Flatpak / Betterbird Flatpak / macOS, point CONN_FILE at the
# real file or export COMMONPOST_MCP_CONNECTION_FILE first.
CONN_FILE="${COMMONPOST_MCP_CONNECTION_FILE:-/tmp/commonpost-mcp/connection.json}"
TOKEN=$(jq -r .token "$CONN_FILE")
PORT=$(jq -r .port "$CONN_FILE")
curl -X POST http://127.0.0.1:$PORT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

直接调用 HTTP API、而不使用 bridge 的程序不会发送 X-Commonpost-Bridge 标头，因此会被视为使用 bridge 0.11 或更早版本：工具结果可能会附带更新 bridge 的提示，并且 replyToMessage / forwardMessage 使用 mode: "send" 或 "draft" 时会被拒绝（旧版 bridge 会在 30 s 后停止等待）。等待这些调用至少 180 s 的直接客户端可以通过 -H "X-Commonpost-Bridge: 0.12.0; packaging=file" 声明自身。如果某个版本启用了 bridge 安全下限，则不带标头的客户端会被完全拒绝。

仅限开发环境的扩展重载： 在本地修改扩展源代码后，请从 Thunderbird 中移除该附加组件，重启 Thunderbird，重新安装 XPI，然后再次重启。Thunderbird 的缓存机制非常激进。

运行测试：npm ci --ignore-scripts && npm test；参见 CONTRIBUTING.md。所有需要 Thunderbird 完整权限的内容都列在 docs/experiment-inventory.md 中。

各部分如何协同工作：docs/architecture.md。设计为何被认为安全，以及其已知局限：docs/assurance-case.md。由谁决策以及如何决策：GOVERNANCE.md。 后续计划：ROADMAP.md。

---

项目结构

commonpost-mcp/
├── mcp-bridge.cjs              # stdio <-> HTTP bridge (auth, port discovery)
├── extension/
│   ├── manifest.json
│   ├── background.js           # Extension entry point
│   ├── httpd.sys.mjs           # Embedded HTTP server (Mozilla)
│   ├── options.html            # Settings page UI
│   ├── options.js              # Settings page logic
│   ├── icons/                  # Extension icons
│   └── mcp_server/
│       ├── api.js              # All 40 MCP tools + auth + access control
│       └── schema.json
├── test/                       # Test suite (node:test; fast-check for the property tests)
├── docs/                       # Experiment inventory, filter API notes
└── scripts/
    ├── build-xpi-reproducible.cjs   # release build (byte-for-byte reproducible)
    ├── build.sh                # quick development build
    └── install.sh

已知问题

• IMAP 文件夹数据库可能会过时，直到你在 Thunderbird 中点击相应文件夹
• 仅含 HTML 的邮件会转换为纯文本（原始格式会丢失）
• 定期日历事件的 CRUD 操作针对整个系列，而非单个事件
• IMAP 文件夹操作（重命名、删除、移动）为异步操作——之后请使用 listFolders 验证
• 在 IMAP 上同时使用标签和移动/移至废纸篓，可能无法在移动后的副本中保留标签——请分开调用
• 预先存在的 Thunderbird 筛选器若将移动/复制目标设为其他账户，不受账户访问控制限制
• 在未启用离线同步的 IMAP 上使用 searchBody 时只会搜索标头（Gloda 的限制）
• rawSource 在 IMAP 上需要离线邮件副本——仅在线的邮件会报错

---

许可证和致谢

MIT（参见 LICENSE）：版权所有 Tomasz Kasperczyk（原始项目）和 Commonpost 贡献者。extension/httpd.sys.mjs 是 Mozilla 的嵌入式 HTTP 服务器，采用 MPL-2.0 许可证（参见 THIRD-PARTY.md）。采纳自上游拉取请求的修复和想法仍归其作者所有：Tony（TKasperczyk/thunderbird-mcp#209）、safrano9999（TKasperczyk/thunderbird-mcp#214）、Daniel Glaser（the78mole；TKasperczyk/thunderbird-mcp#195，后被 TKasperczyk/thunderbird-mcp#222 取代）、Neel Radhakrishnan（TKasperczyk/thunderbird-mcp#175）、JordanRO2（TKasperczyk/thunderbird-mcp#126，以及过滤器发送保护的想法和首选项名称，TKasperczyk/thunderbird-mcp#127）、KinJLy 和 coulof（分支）。