Read and search Thunderbird email through a CLI, with optional MCP and configurable action permissions.

This fork adds configurable access rights, plus the correctness and transport fixes listed in Unreleased changes. Reading/searching are always available. Attachment downloads and unsent draft preparation default to enabled; sending and changes to existing mail default to disabled. Copy access.example.json, customize it, and build your own add-on. Run tb access to check what the installed add-on permits. MCP is optional. Deletion and emptying Trash are not implemented and cannot be enabled. Use the move command with a Trash folder ID to move mail to Trash. Upstream signed binaries linked below do not contain this fork's changes.

For one authenticated CLI-only installation, use local setup. It includes the bridge service, private XPI builder, attachments on new drafts and replies, native quotation preservation, sender/recipient selection and draft inspection.

IMAP libraries force you to manage credentials, OAuth flows, and sync state — dangerous in an AI-agent context. Thunderbird already solves all of that. This tool treats Thunderbird as the source of truth and exposes every capability as a CLI command or MCP tool, so AI agents can read, search, and write email without ever touching a password.

Tested at scale: 22 accounts, 249,000+ messages, 86,000+ unread — all managed live through a single CLI.

• 🔐 Zero credential exposure — all IMAP/SMTP stays in Thunderbird
• 🤖 Claude Desktop ready — 12 MCP tools, one-line config
• 📨 38 CLI commands — read, search, compose, reply, bulk ops, folder CRUD, attachments
• 🛡️ Safe by default — compose/reply/forward save as drafts; no deletion or empty-Trash capability
• 🎯 Token-optimized — --fields selection, --compact mode, --max-body truncation
• 🏠 Localhost-only — no cloud, no telemetry, nothing leaves your machine
• ✅ Thunderbird 128+ — build this fork to get its restrictions; upstream signed builds differ
• 🧪 80 tests — 46 CLI/bridge + 34 MCP integration tests

# 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

Full setup guide (including background service, Docker, troubleshooting): 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

Full command reference: docs/COMMANDS.md

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. Now ask:

"How many unread emails do I have?" "Find invoices from AWS last month" "Reply to message 118 saying I'll attend — save as draft" "Download the PDF attachment from message 245"

Full MCP guide: mcp/README.md

A Claude Skill ships alongside the MCP server. It teaches Claude how to use the 12 email tools well — token-efficient field selection, draft-by-default safety, trust-metadata checking before acting on links, recipes for common workflows. Install it from 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

Without the skill, the MCP still works. With it, Claude automatically uses the safest defaults and most efficient response shapes.

Thunderbird is the source of truth. The CLI never caches or stores email data.

The niche: you already trust Thunderbird with your credentials and account state. This tool surfaces that as a machine-readable API without asking you to re-configure IMAP/SMTP anywhere else.

Contributions welcome. Please open an issue first to discuss non-trivial changes. See CONTRIBUTING.md for local dev setup and the 80-test suite.

MIT — see LICENSE