thunderbird-cli

thunderbird-cli

通过 Mozilla Thunderbird，让 Claude（以及其他 AI Agent）全面访问你的电子邮件。

为什么

IMAP 库要求你管理凭据、OAuth 流程和同步状态——在 AI Agent 场景中很危险。Thunderbird 已经解决了所有这些问题。 此工具将 Thunderbird 视为事实来源，并将所有功能作为 CLI 命令或 MCP 工具提供，让 AI Agent 无需接触密码即可读取、搜索和撰写电子邮件。

经过大规模测试：22 个账户、249,000 多封邮件、86,000 多封未读邮件——全部通过单个 CLI 实时管理。

功能

• 🔐 凭据零暴露 — 所有 IMAP/SMTP 操作都在 Thunderbird 中进行
• 🤖 可用于 Claude Desktop — 12 个 MCP 工具，一行配置即可
• 📨 38 个 CLI 命令 — 读取、搜索、撰写、回复、批量操作、文件夹 CRUD、附件
• 🛡️ 默认安全 — 撰写/回复/转发会保存为草稿；永久删除需要 --confirm
• 🎯 针对 Token 优化 — 使用 --fields 选择字段、--compact 精简模式、--max-body 截断正文
• 🏠 仅限本地主机 — 无云服务、无遥测，任何数据都不会离开你的设备
• ✅ Thunderbird 128+ — 已签名并获 addons.thunderbird.net 批准
• 🧪 80 项测试 — 46 项 CLI/桥接测试 + 34 项 MCP 集成测试

快速开始

# 1. Install CLI + bridge from npm
npm install -g thunderbird-cli thunderbird-cli-bridge

# 2. Install the signed Thunderbird extension
#    Download: https://github.com/vitalio-sh/thunderbird-cli/releases/latest
#    Thunderbird → Add-ons → ⚙ → Install Add-on From File… → thunderbird_ai_bridge-*.xpi

# 3. Start the bridge daemon (keep running)
tb-bridge

# 4. Try it
tb health
tb stats

完整安装指南（包括后台服务、Docker 和故障排除）：docs/SETUP.md

用法

# How many unread across all accounts?
tb stats

# Find invoices from AWS in the last 30 days
tb search "invoice" --from aws --since 30d --fields id,author,subject,date

# Read a message (token-efficient — headers + text only, max 500 chars)
tb read 89900 --max-body 500

# Reply as draft (never auto-sends)
tb reply 89900 --body "Thanks, I'll review tomorrow"

# Download a PDF attachment
tb attachment-download 11 1.2 --output invoice.pdf

# Bulk archive old newsletters
tb bulk move "account1://INBOX" "account1://Archive" \
  --from "newsletter@" --older-than 30

完整命令参考：docs/COMMANDS.md

与 Claude Desktop 配合使用

添加到 Claude Desktop 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "thunderbird": {
      "command": "npx",
      "args": ["-y", "thunderbird-cli-mcp"]
    }
  }
}

重启 Claude Desktop。现在可以提问：

“我有多少封未读邮件？” “查找上个月来自 AWS 的发票” “回复消息 118，说我会参加——保存为草稿” “下载消息 245 的 PDF 附件”

完整 MCP 指南：mcp/README.md

Claude 配套技能

MCP 服务附带一个 Claude Skill。它会教 Claude 如何使用 这 12 个电子邮件工具——高效选择字段、默认保存草稿以确保安全、执行链接操作前检查信任元数据，以及常见工作流的操作指南。请从 skills/thunderbird-cli/ 安装：

# Claude Code
cp -r skills/thunderbird-cli ~/.claude/skills/

# Claude.ai — zip and upload via Settings → Capabilities → Skills
cd skills && zip -r thunderbird-cli.zip thunderbird-cli

不安装此技能，MCP 仍可正常工作。安装后，Claude 会自动采用最安全的默认设置和最高效的响应格式。

工作原理

组件	作用
扩展（extension/）	Thunderbird WebExtension。调用 messenger.* API。包含 43 个路由处理程序。
桥接（bridge/）	无状态 HTTP↔WebSocket 代理守护进程。不包含业务逻辑。
CLI（cli/）	tb 命令 — 38 个命令。轻量级 HTTP 客户端。输出 JSON。
MCP（mcp/）	tb-mcp 服务 — 为 Claude Desktop 精选的 12 个工具。

Thunderbird 是事实来源。CLI 从不缓存或存储电子邮件数据。

对比

工具	凭据	适用于 AI Agent	撰写 / 发送	多账户	运行时
thunderbird-cli	保存在 Thunderbird 中	✅ CLI + MCP，输出 JSON	✅ 草拟 / 打开 / 发送	✅ 任意 Thunderbird 账户	Node.js
原始 IMAP 库（imapflow、imaplib）	由你管理	需自行接入	SMTP，需单独处理	每个账户需手动配置	不一
notmuch	通过你的 MUA	仅 CLI，输出文本	❌ 仅阅读	通过配置	C
mu / mu4e	通过你的 MUA	仅 CLI，输出 sexp / 文本	❌ 仅阅读	通过配置	C
himalaya	在配置文件中	✅ CLI，输出 JSON	✅	✅	Rust
mutt / neomutt	在 muttrc 中	❌ 交互式 TUI	✅	通过配置	C

它的独特之处：你已经信任 Thunderbird 来管理凭据和账户状态。 这个工具将其作为机器可读的 API 提供出来，无需你在其他地方重新配置 IMAP/SMTP。

文档

文档	内容
docs/SETUP.md	安装、后台服务、Docker、故障排除
docs/COMMANDS.md	全部 38 个 CLI 命令的完整参考
docs/CLAUDE.md	面向 AI Agent 的快速参考 + 安全规则
skills/thunderbird-cli/SKILL.md	配套的 Claude Skill — 操作指南、安全默认设置、令牌模式
mcp/README.md	Claude Desktop 集成指南
AGENTS.md	面向编辑此代码库的 AI Agent 的指南
SPEC.md	完整技术规范
SECURITY.md	威胁模型、提示词注入防御
CONTRIBUTING.md	开发环境设置、代码风格、PR 流程
CHANGELOG.md	发行说明

参与贡献

欢迎贡献。对于较大的更改，请先提交 issue 进行讨论。有关本地开发环境设置和包含 80 个测试的测试套件，请参阅 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE