Thunderbird Mail MCP

让 AI Agent 通过 Model Context Protocol（MCP） 查询本机 Thunderbird 邮件、读取附件、创建草稿，以及发送用户明确授权的邮件。

这是一个独立的 Python MCP server，使用标准 stdio 传输。它不依赖 Codex、Qoder、QwenWork 或任何模型供应商的 SDK、账号、API Key、Skill、私有配置目录。客户端负责启动服务、选择模型和管理工具调用权限；服务负责邮件数据与 Thunderbird 的交互。

能做什么

查询不修改 mbox，也不标记已读。服务不直接连接 SMTP、POP 或 IMAP；账号认证和真实投递由 Thunderbird 处理。当前版本 0.5.0，提供 12 个工具，详见工具与行为参考。

Related MCP server: Thunderbird MCP Server

Harness 与客户端兼容性

接入条件是：客户端能在邮件所在机器上启动本地进程，并支持 MCP stdio 的握手、工具发现和调用。更换客户端不需要修改服务代码。mcpServers、TOML 或其他配置外层属于客户端约定，不是 MCP 协议统一规定的文件格式。

Harness 无关不等于操作系统无关。当前原生部署面向 macOS：写信程序路径、Native Messaging 注册位置和发送状态目录采用 macOS 约定。Linux CI 验证协议与模拟逻辑，不代表 Linux/Windows 原生 Thunderbird 部署已支持。

环境要求

• Python 3.10+，推荐 3.11；依赖通过 uv 0.13.0 和 uv.lock 安装。

• 查询需要一个可读的本地 mbox 文件。当前入口配置一个 Inbox，适用于已有 Thunderbird 本地 POP 邮件；不会自动发现账户，不支持直接读取 Maildir。

• 打开原生写信窗口需要 Thunderbird 安装在 /Applications/Thunderbird.app。

• 创建草稿或自动发送需要 Thunderbird 153+、本仓库 0.5.0 扩展及 native host；查询功能不需要扩展。

• Node 22.23.0 仅用于开发测试，日常运行 Python 服务不需要 Node。

快速开始

1. 安装服务

安装 Git、Python 和指定版本的 uv 后，在新的检出目录执行：

git clone https://github.com/zhangjian0410/thunderbird-mail-mcp.git
cd thunderbird-mail-mcp
uv lock --check
uv sync --locked --no-install-project
uv sync --locked --no-build-isolation

两步同步先安装锁定的构建工具，再用这些工具安装本项目；不会另外解析未锁定的构建环境。不要在已有服务使用的目录里直接升级；先在独立检出中验证。

2. 配置本地 MCP 客户端

打开 Thunderbird 的账户设置，找到本地目录并确认真实的 mbox Inbox 文件。将通用配置示例中的三个绝对路径替换为自己的路径：

{
  "mcpServers": {
    "thunderbird_mail": {
      "type": "stdio",
      "command": "/absolute/path/thunderbird-mail-mcp/.venv/bin/python",
      "args": ["/absolute/path/thunderbird-mail-mcp/server.py"],
      "env": {
        "THUNDERBIRD_INBOX_PATH": "/absolute/path/to/Inbox"
      }
    }
  }
}

command 是 Python 可执行文件，args 中的 server.py 是单独参数，env 传入服务进程。绝对路径使启动不依赖客户端工作目录；路径含空格时也不要把 Python 与脚本合并成 JSON 的一个 command 字符串。

Qoder IDE 在设置 → MCP → My Servers → Add 中添加配置；CLI 按其官方说明放入 mcpServers。QwenWork 桌面端在扩展 → 连接器 → 添加中导入 JSON，或选择 STDIO 手动填写等价的启动命令及环境变量。其他客户端按自己的格式填写相同的 command、args、env。

唯一的邮件路径环境变量是 THUNDERBIRD_INBOX_PATH。省略时服务使用 ~/Library/Thunderbird/Inbox 占位路径，不会自动扫描账户。无需填写邮箱密码或模型 API Key。

3. 验证查询

在客户端启用服务并刷新工具列表，应能发现 12 个工具。先调用 list_mail_folders 确认 Inbox 可用，再查询和读取邮件，例如：

查询发件人为 sender@example.test 的邮件，列出主题和日期；读取我指定的一封邮件，不创建草稿或发送。

工具调用成功只证明本地数据可读；Thunderbird 是否已与邮件服务器同步需要另外确认。要使用草稿和发送能力，继续阅读可选写信部署。

使用边界

• 当前服务始终公布所有 12 个工具，没有服务端只读模式开关。仅需查询时，应在客户端限制 compose_email、create_draft 和 send_email 的使用。

• 发送权限由调用方管理。服务不读取任何 Harness 的审批白名单，也不解析自然语言授权；调用方须在调用 send_email 前取得收件对象与用途的明确授权。

• pending / sending 不代表发送成功；sent 表示 Thunderbird 确认提交，不保证收件人收到。同一封邮件重试必须复用幂等键，结果不明时不能换键重发。

• 本地完整枚举不等于服务器同步完成；检查查询返回的 coverage、分页和正文截断信息。

• mbox、原生配置、发送数据库、XPI 和部署备份可能含私人数据，不能提交到 Git。自动扫描覆盖受版本控制的当前文件与 Git 历史。

项目结构与文档

• 工具、数据边界与写信部署

• 开发、依赖更新、CI 与敏感信息检查

• 版本变更

完整测试命令：

uv run --no-sync python -m unittest discover -s tests -v
node --test tests/*.test.cjs

测试使用临时邮箱和模拟发送接口，协议测试直接启动独立 MCP 子进程，不调用模型 API、不部署扩展、不发送真实邮件。

许可证

本项目采用 MIT License。