# thunderbird-cli > Give Claude (and other AI agents) full access to your email through Mozilla Thunderbird. [![tests](https://github.com/vitalio-sh/thunderbird-cli/actions/workflows/test.yml/badge.svg)](https://github.com/vitalio-sh/thunderbird-cli/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org) [![Thunderbird](https://img.shields.io/badge/thunderbird-128%2B-blue)](https://www.thunderbird.net) [![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)

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 ```bash # 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](docs/SETUP.md)** ## Usage ```bash # 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](docs/COMMANDS.md)** ## Use with Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "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](mcp/README.md)** ### Companion skill for Claude A [Claude Skill](https://agentskills.io) 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/`](skills/thunderbird-cli/)**: ```bash # 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. ## How It Works

thunderbird-cli architecture β€” clients β†’ npm entrypoints β†’ bridge daemon β†’ Thunderbird

| Component | Role | |---|---| | **Extension** (`extension/`) | Thunderbird WebExtension. Calls `messenger.*` APIs. 43 route handlers. | | **Bridge** (`bridge/`) | Stateless HTTP↔WebSocket proxy daemon. No business logic. | | **CLI** (`cli/`) | `tb` command β€” 38 commands. Thin HTTP client. JSON output. | | **MCP** (`mcp/`) | `tb-mcp` server β€” 12 curated tools for Claude Desktop. | Thunderbird is the source of truth. The CLI never caches or stores email data. ## How this compares | Tool | Credentials | AI-agent ready | Compose / send | Multi-account | Runtime | |---|---|---|---|---|---| | **thunderbird-cli** | stay in Thunderbird | βœ… CLI + MCP, JSON out | βœ… draft / open / send | βœ… any Thunderbird account | Node.js | | Raw IMAP libs (imapflow, imaplib) | you manage them | you wire it yourself | SMTP, separate | manual per account | varies | | [notmuch](https://notmuchmail.org) | via your MUA | CLI only, text output | ❌ reader only | via config | C | | [mu / mu4e](https://www.djcbsoftware.nl/code/mu/) | via your MUA | CLI only, sexp/text | ❌ reader only | via config | C | | [himalaya](https://github.com/soywod/himalaya) | in config files | βœ… CLI, JSON out | βœ… | βœ… | Rust | | [mutt / neomutt](http://www.mutt.org) | in muttrc | ❌ interactive TUI | βœ… | via config | C | 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 | Doc | What's inside | |---|---| | [docs/SETUP.md](docs/SETUP.md) | Installation, background service, Docker, troubleshooting | | [docs/COMMANDS.md](docs/COMMANDS.md) | Full reference for all 38 CLI commands | | [docs/CLAUDE.md](docs/CLAUDE.md) | AI-agent-focused quick reference + security rules | | [skills/thunderbird-cli/SKILL.md](skills/thunderbird-cli/SKILL.md) | **Companion Claude Skill** β€” recipes, safety defaults, token patterns | | [mcp/README.md](mcp/README.md) | Claude Desktop integration guide | | [AGENTS.md](AGENTS.md) | Guide for AI agents editing this codebase | | [SPEC.md](SPEC.md) | Full technical specification | | [SECURITY.md](SECURITY.md) | Threat model, prompt-injection defenses | | [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, code style, PR process | | [CHANGELOG.md](CHANGELOG.md) | Release notes | ## Contributing Contributions welcome. Please open an issue first to discuss non-trivial changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for local dev setup and the 80-test suite. ## License MIT β€” see [LICENSE](LICENSE)