# 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:
   ```bash
   cat ~/.thunderbird/profiles.ini
   ls ~/.thunderbird/
   ```
   Pick the profile directory containing `Mail/`, `ImapMail/`, `abook.sqlite`, etc.

2. Install dependencies:
   ```bash
   npm install
   ```

3. Copy `.env.example` to `.env` and set `THUNDERBIRD_PROFILE` to your profile
   directory:
   ```bash
   cp .env.example .env
   # edit .env
   ```

4. Verify it works:
   ```bash
   npm run test:tools
   ```

## Wiring into Claude Desktop / Cowork

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

```json
"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`.