thunderbird-mcp

An MCP server that gives Claude access to Thunderbird — read and search emails across all connected accounts (including iCloud), look up contacts, and access the unified calendar.

The read path works directly with your Thunderbird profile files and does not require Thunderbird to be running. Sending email requires Thunderbird to be running with the bundled WebExtension loaded (see below).

Status

• ✅ Email read path: list accounts/folders, search emails, read full messages
• ✅ Contacts read path: list address books, list/search contacts
• ✅ Calendar read path: list calendars, list events (requires Thunderbird closed)
• ✅ Local HTTP bridge + WebExtension: heartbeat + send email
• ✅ Message management: move, delete, mark read/unread, add/remove tags
• ✅ Contact writes: create/update contacts
• ❌ Calendar writes — blocked, no standard browser.calendar WebExtension API exists (see docs/DECISIONS.md D-010); calendar remains read-only

Setup

1. Find your Thunderbird profile directory:

   cat ~/.thunderbird/profiles.ini
   ls ~/.thunderbird/
   

   Pick the profile directory containing Mail/, ImapMail/, abook.sqlite, etc.

2. Install dependencies:

   npm install
   

3. Copy .env.example to .env and set THUNDERBIRD_PROFILE to your profile directory:

   cp .env.example .env
   # edit .env
   

4. Verify it works:

   npm run test:tools
   

Wiring into Claude Desktop / Cowork

Add an entry to ~/.config/Claude/claude_desktop_config.json under mcpServers:

"thunderbird": {
  "command": "node",
  "args": ["/absolute/path/to/thunderbird-mcp/src/index.js"],
  "env": {
    "THUNDERBIRD_PROFILE": "/home/<you>/.thunderbird/<profile-dir>"
  }
}

Restart Claude Desktop. You should then be able to ask things like "list my Thunderbird accounts" or "search my inbox for invoices".

Tools

• list_accounts — lists configured Thunderbird accounts
• list_folders — lists the folder tree for an account
• search_emails — search by account, folder, sender, subject, keyword, date range
• read_email — full headers, text body, and attachment metadata for one message
• list_address_books — lists configured address books and their synced account
• list_contacts — lists/searches contacts by name or email
• list_calendars — lists configured calendars
• list_events — lists calendar events by calendar/date range (requires Thunderbird to be closed)
• bridge_status — reports whether the Thunderbird WebExtension is connected
• send_email — composes and sends a new email from a connected account (requires Thunderbird running with the extension loaded; check bridge_status first)
• list_tags — lists configured message tags/labels (key, name, color)
• move_message — moves a message to another folder/account (requires the extension)
• delete_message — deletes a message, to Trash by default (requires the extension)
• set_message_read — marks a message read or unread (requires the extension)
• update_message_tags — adds/removes tags on a message (requires the extension)
• create_contact — creates a contact in an address book (requires the extension)
• update_contact — updates fields on an existing contact (requires the extension)

See docs/ARCHITECTURE.md for how email parsing, message addressing, and the WebExtension bridge work, and docs/BRIEF.md for the full project scope and roadmap.

WebExtension

extension/ is a Manifest V2 Thunderbird WebExtension that connects to the local bridge. To load it:

1. In Thunderbird: Settings → General → "Add-ons and Themes" → gear icon → "Debug Add-ons" → "Load Temporary Add-on" → select extension/manifest.json.
2. With npm start running, call the bridge_status tool (or curl http://127.0.0.1:8084/health) — extensionConnected should become true within ~30 seconds.

Once connected, send_email, the message management tools (move_message, delete_message, set_message_read, update_message_tags), and the contact write tools (create_contact, update_contact) are available. Calendar write operations are not implemented — see docs/DECISIONS.md D-010.

Constraints

• Local only — no network exposure, no Cloudflare tunnel. The bridge binds to 127.0.0.1:8084 (override with BRIDGE_PORT) and must never be tunneled.
• sqlite3, not better-sqlite3 (required for Node v24 compatibility)
• THUNDERBIRD_PROFILE must be set via environment variable — never hardcoded

Known limitations

• Calendar is read-only. create_event/update_event/delete_event are not implemented — Thunderbird has no standard browser.calendar WebExtension API (see docs/DECISIONS.md D-010). Workaround for Google-backed calendars: if your Thunderbird calendar is CalDAV-synced from a Google account, use Claude's separate Google Calendar connector to create/update/delete events on that account directly — the change syncs back into Thunderbird and shows up via list_events. This doesn't help with iCloud-backed calendars.
• list_events requires Thunderbird to be closed — the calendar cache database (calendar-data/local.sqlite) is held with an exclusive lock while Thunderbird runs (D-006).
• Reply/reply-all are not implemented — only compose-and-send (D-008).
• Message ids from search_emails/read_email are based on mbox byte offsets and can go stale after Thunderbird compacts a folder (e.g. emptying Trash) — re-run search_emails if a tool reports "message not found".

Troubleshooting

• bridge_status reports extensionConnected: false: make sure Thunderbird is running and the extension is loaded (see "WebExtension" above), and that no other thunderbird-mcp process is bound to the same BRIDGE_PORT (only one process can hold the port; npm run test:tools uses a separate port for this reason).
• list_events/list_contacts report a "locked" error: list_events requires Thunderbird to be closed (D-006). list_contacts can hit this transiently while Thunderbird is actively CardDAV-syncing an address book — wait a moment and retry (D-008).
• A management tool (move_message, etc.) reports "message not found": the id is stale — re-run search_emails to get a fresh one.
• Send/management/contact-write tools time out: the extension didn't respond within 30s. Check the Browser Console (Settings → General → "Add-ons and Themes" → gear icon → "Debug Add-ons" → "Inspect") for errors in background.js.