{
  "markdown": "# thunderbird-cli\n\n> Give Claude (and other AI agents) full access to your email through Mozilla Thunderbird.\n\n[![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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![Thunderbird](https://img.shields.io/badge/thunderbird-128%2B-blue)](https://www.thunderbird.net)\n[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"thunderbird-cli demo — Claude answering an email-overview question via MCP\" width=\"700\">\n</p>\n\n## Why\n\nIMAP 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.\n\nTested at scale: **22 accounts, 249,000+ messages, 86,000+ unread** — all managed live through a single CLI.\n\n## Features\n\n- 🔐 **Zero credential exposure** — all IMAP/SMTP stays in Thunderbird\n- 🤖 **Claude Desktop ready** — 12 MCP tools, one-line config\n- 📨 **38 CLI commands** — read, search, compose, reply, bulk ops, folder CRUD, attachments\n- 🛡️ **Safe by default** — compose/reply/forward save as drafts; permanent delete requires `--confirm`\n- 🎯 **Token-optimized** — `--fields` selection, `--compact` mode, `--max-body` truncation\n- 🏠 **Localhost-only** — no cloud, no telemetry, nothing leaves your machine\n- ✅ **Thunderbird 128+** — signed and approved on addons.thunderbird.net\n- 🧪 **80 tests** — 46 CLI/bridge + 34 MCP integration tests\n\n## Quick Start\n\n```bash\n# 1. Install CLI + bridge from npm\nnpm install -g thunderbird-cli thunderbird-cli-bridge\n\n# 2. Install the signed Thunderbird extension\n#    Download: https://github.com/vitalio-sh/thunderbird-cli/releases/latest\n#    Thunderbird → Add-ons → ⚙ → Install Add-on From File… → thunderbird_ai_bridge-*.xpi\n\n# 3. Start the bridge daemon (keep running)\ntb-bridge\n\n# 4. Try it\ntb health\ntb stats\n```\n\nFull setup guide (including background service, Docker, troubleshooting): **[docs/SETUP.md](docs/SETUP.md)**\n\n## Usage\n\n```bash\n# How many unread across all accounts?\ntb stats\n\n# Find invoices from AWS in the last 30 days\ntb search \"invoice\" --from aws --since 30d --fields id,author,subject,date\n\n# Read a message (token-efficient — headers + text only, max 500 chars)\ntb read 89900 --max-body 500\n\n# Reply as draft (never auto-sends)\ntb reply 89900 --body \"Thanks, I'll review tomorrow\"\n\n# Download a PDF attachment\ntb attachment-download 11 1.2 --output invoice.pdf\n\n# Bulk archive old newsletters\ntb bulk move \"account1://INBOX\" \"account1://Archive\" \\\n  --from \"newsletter@\" --older-than 30\n```\n\nFull command reference: **[docs/COMMANDS.md](docs/COMMANDS.md)**\n\n## Use with Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"thunderbird\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"thunderbird-cli-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Now ask:\n\n> *\"How many unread emails do I have?\"*\n> *\"Find invoices from AWS last month\"*\n> *\"Reply to message 118 saying I'll attend — save as draft\"*\n> *\"Download the PDF attachment from message 245\"*\n\nFull MCP guide: **[mcp/README.md](mcp/README.md)**\n\n### Companion skill for Claude\n\nA [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/)**:\n\n```bash\n# Claude Code\ncp -r skills/thunderbird-cli ~/.claude/skills/\n\n# Claude.ai — zip and upload via Settings → Capabilities → Skills\ncd skills && zip -r thunderbird-cli.zip thunderbird-cli\n```\n\nWithout the skill, the MCP still works. With it, Claude automatically uses the safest defaults and most efficient response shapes.\n\n## How It Works\n\n<p align=\"center\">\n  <img src=\"assets/architecture.png\" alt=\"thunderbird-cli architecture — clients → npm entrypoints → bridge daemon → Thunderbird\" width=\"900\">\n</p>\n\n| Component | Role |\n|---|---|\n| **Extension** (`extension/`) | Thunderbird WebExtension. Calls `messenger.*` APIs. 43 route handlers. |\n| **Bridge** (`bridge/`) | Stateless HTTP↔WebSocket proxy daemon. No business logic. |\n| **CLI** (`cli/`) | `tb` command — 38 commands. Thin HTTP client. JSON output. |\n| **MCP** (`mcp/`) | `tb-mcp` server — 12 curated tools for Claude Desktop. |\n\nThunderbird is the source of truth. The CLI never caches or stores email data.\n\n## How this compares\n\n| Tool | Credentials | AI-agent ready | Compose / send | Multi-account | Runtime |\n|---|---|---|---|---|---|\n| **thunderbird-cli** | stay in Thunderbird | ✅ CLI + MCP, JSON out | ✅ draft / open / send | ✅ any Thunderbird account | Node.js |\n| Raw IMAP libs (imapflow, imaplib) | you manage them | you wire it yourself | SMTP, separate | manual per account | varies |\n| [notmuch](https://notmuchmail.org) | via your MUA | CLI only, text output | ❌ reader only | via config | C |\n| [mu / mu4e](https://www.djcbsoftware.nl/code/mu/) | via your MUA | CLI only, sexp/text | ❌ reader only | via config | C |\n| [himalaya](https://github.com/soywod/himalaya) | in config files | ✅ CLI, JSON out | ✅ | ✅ | Rust |\n| [mutt / neomutt](http://www.mutt.org) | in muttrc | ❌ interactive TUI | ✅ | via config | C |\n\nThe 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.\n\n## Documentation\n\n| Doc | What's inside |\n|---|---|\n| [docs/SETUP.md](docs/SETUP.md) | Installation, background service, Docker, troubleshooting |\n| [docs/COMMANDS.md](docs/COMMANDS.md) | Full reference for all 38 CLI commands |\n| [docs/CLAUDE.md](docs/CLAUDE.md) | AI-agent-focused quick reference + security rules |\n| [skills/thunderbird-cli/SKILL.md](skills/thunderbird-cli/SKILL.md) | **Companion Claude Skill** — recipes, safety defaults, token patterns |\n| [mcp/README.md](mcp/README.md) | Claude Desktop integration guide |\n| [AGENTS.md](AGENTS.md) | Guide for AI agents editing this codebase |\n| [SPEC.md](SPEC.md) | Full technical specification |\n| [SECURITY.md](SECURITY.md) | Threat model, prompt-injection defenses |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, code style, PR process |\n| [CHANGELOG.md](CHANGELOG.md) | Release notes |\n\n## Contributing\n\nContributions 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.\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 7117,
  "sha": "198693fcc51f181b38d01f47f6e430b0137fe55d843faeaa511e6cacb947e3d0",
  "repo_slug": "vitalio-sh/thunderbird-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vitalio_sh_thunderbird_cli_46eae59d/readme"
}