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

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/thunde

... View full README on GitHub