Thunderbird CLI Enhanced

Give Claude (and other AI agents) full access to your email through Mozilla Thunderbird, with an installation-wide access policy that decides what they may change.

This is a maintained fork of vitalio-sh/thunderbird-cli. It integrates fixes and features from the community forks listed under Why this fork and adds an access policy, a signed-XPI release pipeline, draft editing, and (since 1.3.0) calendar, tasks, notes and one-click Fast Actions.

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.

Features

• 🔐 Zero credential exposure — all IMAP/SMTP stays in Thunderbird
• 🤖 Claude Desktop ready — 42 MCP tools, one-line config
• 📨 74 CLI commands — read, search, compose, reply, edit drafts, bulk ops, folder CRUD, attachments, contacts (read/write)
• 📅 Calendar & tasks — list calendars and events, create/update/delete events, cross-calendar clash detection, task CRUD, and deterministic action-item extraction from an email (needs add-on 2.4.0)
• ⚡ Fast Actions & skills — one-click Email → Note / Task / Event / Contact (CLI, MCP and Thunderbird's context menu); tb today/week/clashes/from render compact Markdown without spending LLM tokens
• 📝 Notes workspace — local Markdown notes ("Use as Context", "Save to Notes", render to a draft) and local voice-memo transcription (tb notes transcribe, whisper.cpp / faster-whisper, nothing leaves the machine)
• 🛡️ Access policy — one policy baked into the add-on gates every write/send route for CLI, MCP and raw bridge calls; deletion and contact/calendar/task writes (contactsWrite, calendarWrite, tasksWrite) are off by default and unknown routes fail closed (docs/ACCESS-CONTROL.md)
• ✉️ Safe by default — compose/reply/forward/edit save as drafts; permanent delete requires --confirm
• 🚀 Bridge auto-start — the CLI and MCP server start the bridge daemon on first use
• 🎯 Token-optimized — --fields selection, --compact mode, --max-body truncation, -f json|compact|table, opt-in leaner output with --output-version 2
• ⚡ Fast on large folders — server-side full-text query, sort (TB 148+), indexed --unread/--flagged plus date/size/tag filtering, --subject/--from search
• 🏠 Localhost-only — no cloud, no telemetry, nothing leaves your machine
• ✅ Thunderbird 128+ — Mozilla-signed XPI built and signed by CI (dist/releases/; add-on 2.4.0 is awaiting ATN review, see Quick Start)
• 🧪 Tested — npm run test:all runs the CLI/bridge, bridge security, extension, access-control, signing and MCP suites

Quick Start

Install the CLI, bridge and MCP server from npm (Node.js 20+):

npm i -g @odience-network/thunderbird-cli-enhanced   # gives you tb, tb-bridge and tb-mcp

Coming from upstream thunderbird-cli? The unscoped npm packages thunderbird-cli, thunderbird-cli-bridge and thunderbird-cli-mcp are upstream's and don't contain this fork's changes. They install the same tb, tb-bridge and tb-mcp commands, so remove them first: npm uninstall -g thunderbird-cli thunderbird-cli-bridge thunderbird-cli-mcp (and npm unlink -g any source checkouts you linked).

Or install from source, which links the same three commands:

git clone https://github.com/odience-network/thunderbird-cli-enhanced
cd thunderbird-cli-enhanced

./setup.sh       # macOS / Linux
.\setup.ps1      # Windows (PowerShell)

Then:

1. Install the signed extension from dist/releases/: Thunderbird → Add-ons → ⚙ → Install Add-on From File… → the *-tb.xpi file. The only ATN-signed build is 2.1.0 (thunderbird_ai_bridge-2.1.0-tb.xpi): it predates the rename, shows as "Thunderbird AI Bridge" in the Add-ons Manager, and has no calendar, tasks or Fast Actions. Add-on 2.4.0 ("Thunderbird CLI Enhanced") is attached unsigned to the v1.3.0 GitHub Release while ATN's manual review is pending; load it via Tools → Developer Tools → Debug Add-ons → Load Temporary Add-on…, or on a Thunderbird build that allows unsigned add-ons. Details: docs/SETUP.md.

2. Try it — the bridge starts automatically on first use:

   tb health
   tb stats

Full setup guide (background service, Docker, access policy, 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"

# Edit an existing draft (messageId may change after save)
tb edit 12001 --body "Revised body — please review"

# 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

# Today's events plus unread/flagged counts as compact Markdown (no LLM tokens)
tb today

# Turn an email into a task (needs add-on 2.4.0 and tasksWrite)
tb email-to-task 89900 --calendar <calendarId> --due 2026-10-03

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). npx fetches the package on demand, no global install needed:

{
  "mcpServers": {
    "thunderbird": {
      "command": "npx",
      "args": ["-y", "-p", "@odience-network/thunderbird-cli-enhanced", "tb-mcp"]
    }
  }
}

With a global install (npm i -g) or the setup script, "command": "tb-mcp" with no args works too. For Claude Code:

claude mcp add thunderbird -- npx -y -p @odience-network/thunderbird-cli-enhanced tb-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 42 MCP tools well — token-efficient field selection, draft-by-default safety, checking trust signals before acting on links, recipes for common workflows. Install it from skills/thunderbird-cli/:

# Claude Code
cp -r skills/thunderbird-cli ~/.claude/skills/
# ...or from the npm install
cp -r "$(npm root -g)/@odience-network/thunderbird-cli-enhanced/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

_{Click for the interactive version. More diagrams: docs/diagrams/}

Component	Role
Extension (extension/)	Thunderbird WebExtension. Calls messenger.* APIs, plus vendored calendar/task Experiment APIs; adds the Fast Actions context-menu items. Every route is classified by the access policy.
Bridge (bridge/)	HTTP↔WebSocket proxy daemon on 127.0.0.1:7700/7701. No business logic; buffers recent extension events for long-polling.
CLI (cli/)	tb command — 74 commands (mail, contacts, calendar, tasks, notes, skills, Fast Actions). Thin HTTP client. JSON output.
MCP (mcp/)	tb-mcp server — 42 curated tools for Claude Desktop.

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

Why this fork

Upstream baseline is vitalio-sh/thunderbird-cli@465613d (1.1.0). Each row below is merged on main and linked to the PR that landed it. Planned work is listed separately under Roadmap.

Feature	Enhanced	Upstream	Origin	Landed in
Access policy for every write/send route, fail-closed on unknown routes	✅	❌	reinhardullrich (93178cb), extended	#6
Deletion disabled unless the policy enables it	✅	❌	reinhardullrich (b5b7714), modified	#4
Filters applied before --limit; accurate hasMore	✅	❌	reinhardullrich	#2
Reply keeps the receiving identity and the quoted body	✅	❌	bfg1981	#1
Conversation history on reply/forward, --no-history	✅	❌	inrainbws	#3
Folder-info cache for list/stats, MCP concurrency tests, live smoke scripts	✅	❌	le-dawg	#8
One-command setup scripts (setup.sh, setup.ps1)	✅	❌	KaiSingL	#9
Attachment extension inference, general-query and empty-query search, recipient parsing	✅	❌	KaiSingL	#11
--keep-unread on delete/archive	✅	❌	KaiSingL	#12
Bridge auto-start from CLI and MCP	✅	❌	KaiSingL	#13
Server-side sort, filters and full-text query	✅	❌	KaiSingL	#14
Edit existing drafts (tb edit, MCP email_edit)	✅	❌	KaiSingL	#15
Extension icons and toolbar connection-status indicator	✅	❌	KaiSingL	#16
tb extension-reload and the /bridge/events long-poll feed	✅	❌	KaiSingL (0b3a5d7)	#17
Opt-in v2 output: TTY tables, no envelope, short field presets (--output-version 2)	✅	❌	KaiSingL, made opt-in	#19
CI builds, lints, tests and Mozilla-signs the XPI	✅	❌	this fork	#5, #7
Bridge enforces TB_AUTH_TOKEN	✅	✅	jctots	upstream a052c8d
--account filtering for recent/thread, accountId inside pagination	✅	✅	dboeckenhoff (equivalent fix already upstream)	verified in 54cd46d

How one search travels through the system (#13, #14)

Roadmap

Shipped in 1.3.0, toward feature parity with atbridge.ai:

• Calendar read, event CRUD and cross-calendar clash detection (tb calendar list/events/create/update/delete/clashes, gated by calendarWrite), via chrome-privileged Experiment APIs since Thunderbird's WebExtension model has no calendar access — see docs/decisions/calendar-backend.md for the tradeoffs, including the ATN manual-review requirement this adds to every signed release that touches it.
• Task CRUD (tb tasks, gated by tasksWrite) and deterministic action-item extraction (tb action-items).
• Contacts write (tb contacts create/update, gated by contactsWrite).
• Notes workspace and local voice-memo transcription (tb notes, tb notes transcribe).
• Deterministic skills (tb today/week/clashes/from) and one-click Fast Actions (tb email-to-note/email-to-task/email-to-event/email-to-contact, plus matching context-menu items in Thunderbird).

Planned, not on main:

• Extension stability pass: audit against the known reconnect/backoff and lifecycle fixes, with regression tests.
• Remaining atbridge.ai parity items from docs/PLAN.md §4 not covered above.
• ATN signing of add-on 2.4.0 (manual review pending; until then 2.4.0 ships unsigned).

Details and status: docs/PLAN.md.

How this compares

Tool	Credentials	AI-agent ready	Compose / send	Multi-account	Runtime
Thunderbird CLI Enhanced	stay in Thunderbird	✅ CLI + MCP, JSON out	✅ draft / open / send / edit draft	✅ any Thunderbird account	Node.js
Raw IMAP libs (imapflow, imaplib)	you manage them	you wire it yourself	SMTP, separate	manual per account	varies
notmuch	via your MUA	CLI only, text output	❌ reader only	via config	C
mu / mu4e	via your MUA	CLI only, sexp/text	❌ reader only	via config	C
himalaya	in config files	✅ CLI, JSON out	✅	✅	Rust
mutt / neomutt	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	Installation, background service, Docker, troubleshooting
docs/COMMANDS.md	Full reference for all 74 CLI commands
docs/ACCESS-CONTROL.md	The access policy: switches, defaults, how to change them
docs/diagrams/	Architecture, search sequence, access control, release and roadmap diagrams
docs/CLAUDE.md	AI-agent-focused quick reference + security rules
skills/thunderbird-cli/SKILL.md	Companion Claude Skill — recipes, safety defaults, token patterns
mcp/README.md	Claude Desktop integration guide
AGENTS.md	Guide for AI agents editing this codebase
SPEC.md	Full technical specification
docs/PLAN.md	Fork integration plan and roadmap status
SECURITY.md	Threat model, prompt-injection defenses
CONTRIBUTING.md	Dev setup, tests, diagram builds, PR process
docs/RELEASING.md	Cutting a release, npm publishing, rollback
CHANGELOG.md	Release notes

Contributing

Contributions welcome. Please open an issue first to discuss non-trivial changes. See CONTRIBUTING.md for local dev setup, the test suites and how to rebuild the diagrams.

Acknowledgements

• Vitalii Ionov / vitalio-sh/thunderbird-cli — the original project: extension, bridge, CLI, MCP server, companion skill and the upstream security hardening this fork builds on.
• bfg1981 — reply identity and quoted-body preservation (#1).
• reinhardullrich — filter-before-limit pagination, the deletion gate and the access-control groundwork (#2, #4, #6).
• inrainbws — conversation history on reply/forward (#3).
• le-dawg — folder-info cache, MCP concurrency tests and live smoke scripts (#8).
• KaiSingL — setup scripts, search and attachment fixes, --keep-unread, bridge auto-start, server-side search, draft editing, removal of the stale 2.0.0 XPI, extension icons and status indicator, tb extension-reload and the v2 output format (#9–#17, #19).
• jctots — bridge TB_AUTH_TOKEN enforcement, merged upstream (a052c8d).
• dboeckenhoff — multi-account --account filter fixes; an equivalent fix was already upstream (54cd46d).

Diagrams are built with archify.

License

MIT — see LICENSE. The original copyright notice (Vitalii Ionov) is retained; contributions from the forks above are used under the same license.