Thunderbird Cli

thunderbird-cli

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

[tests] [License: MIT] [Node] [Thunderbird] [MCP]

[thunderbird-cli demo — Claude answering an email-overview question via MCP]

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 npmnpm 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 ittb healthtb 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 daystb 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 attachmenttb attachment-download 11 1.2 --output invoice.pdf
# Bulk archive old newsletterstb 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

Companion skill for Claude

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 Codecp -r skills/thunderbird-cli ~/.claude/skills/
# Claude.ai — zip and upload via Settings → Capabilities → Skillscd 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.

How It Works

[thunderbird-cli architecture — clients → npm entrypoints → bridge daemon → Thunderbird]

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