thunderbird-cli

Give Claude (and other AI agents) full access to your email through Mozilla Thunderbird.

Why

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.

Features

• 🔐 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; permanent delete requires --confirm

• 🎯 Token-optimized — --fields selection, --compact mode, --max-body truncation

• 🏠 Localhost-only — no cloud, no telemetry, nothing leaves your machine

• ✅ Thunderbird 128+ — signed and approved on addons.thunderbird.net

• 🧪 80 tests — 46 CLI/bridge + 34 MCP integration tests

Quick Start

# 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

Usage

# 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

Use with Claude Desktop

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

How It Works

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

How this compares

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.

Documentation

Contributing

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

License

MIT — see LICENSE