Thunderbird MCP

Thunderbird MCP gives an AI agent real control of the Thunderbird already running on your machine — your mail, your folders, your contacts, your calendar, your filters, and your actual settings. Not a copy, not an IMAP re-implementation: the same Thunderbird you have open, driven through its own internals.

Written in Python, built for Claude Code and Codex CLI, and able to drive one Thunderbird from both at the same time.

What you can ask for

• Find things you half-remember. "What did the accountant say about VAT in June?" runs a ranked search over the whole indexed corpus and can reconstruct a thread that spans Inbox, Sent and an archive folder in one call.
• Triage a mailbox. Mark, tag, move, archive and file in bulk — with the source folders reported back so a wrong move is reversible.
• Write mail you get to read first. mail_send produces a reviewable draft by default; sending is a separate, confirmed step, and needs no compose window.
• Change settings, properly. Server ports and connection security, identities and signatures, SMTP servers, junk handling, archive layout, message-pane layout, ~5,700 preferences — read the current value, write the new one, and get the old one back so you can undo it.
• Automate the boring rules. Create and reorder message filters, then run them over an existing folder to check they do what you meant.
• Keep a calendar honest. Events and tasks, with recurring items addressed as a series unless you name one occurrence.

[!NOTE] Everything documented here was verified against a live Thunderbird 153 on Windows 11, not inferred from documentation. The measurements, and the traps found the hard way, are in docs/VERIFIED-FINDINGS.md.

Quick start

There is no PyPI package to install from yet — clone the repo and let it build its own environment:

git clone https://github.com/U-C4N/Thunderbird-MCP
cd Thunderbird-MCP
python bootstrap.py

One command: it picks an interpreter that works, builds the environment, installs the add-on, and verifies the whole chain before it returns. Re-running it is safe — healthy steps are no-ops. Add --clients claude-code,codex to also register those clients in the same run, or do it afterward from "Install into a client" below.

Installing the add-on closes Thunderbird, installs through Thunderbird's own automation channel, and starts it again — no clicking through the Add-ons UI; bootstrap does this for you as its addon step. Prefer to do it by hand, or on its own? tbmcp install-addon --manual builds the package and prints the three clicks.

Already installed? tbmcp bootstrap does the same thing.

For AI agents

python bootstrap.py --json

Emits one object: ok, version, launcher, steps[] (each with name, status, seconds, detail), and next_command — null on success, otherwise the single command that addresses the failure. status is one of ok, repaired, skipped, failed. Parse this instead of the human output; the columns are not a stable interface and the JSON is.

A healthy doctor looks like this:

thunderbird-mcp doctor

Python
  version                    3.14.6
  interpreter                C:\Users\VECTOR\Documents\GitHub\Thunderbird-MCP\.venv\Scripts\python.exe

Thunderbird
  executable                 C:\Program Files\Mozilla Thunderbird\thunderbird.exe
  running                    True
  add-on version (source)    1.2.0
  profile                    C:\Users\VECTOR\AppData\Roaming\Thunderbird\Profiles\81l4u5ba.default-release
  accounts (from prefs.js)   2
  outgoing servers           1
  global index db            True
  add-on startup report      2026-08-11T06:41:40.527Z
  privileged modules         12 loaded
  bridge methods             128

Bridge
  daemon                     pid 31120
  connected                  True
  add-on version (live)      1.2.0
  privileged half            True
  app                        Thunderbird 153.0.2
  tb_status tool call        connected

Tools
  toolsets                   mail,folders,compose,search,admin
  read-only                  False
  send mode                  draft

Install into a client

tbmcp setup claude-code --toolsets all

Or by hand — note the absolute path, because Claude Code spawns without a shell and has no cwd setting:

claude mcp add-json thunderbird '{
  "type": "stdio",
  "command": "C:\\Users\\you\\Thunderbird-MCP\\.venv\\Scripts\\python.exe",
  "args": ["-m", "tbmcp", "serve", "--toolsets", "all"],
  "env": { "PYTHONUTF8": "1", "PYTHONUNBUFFERED": "1" }
}' --scope user

bootstrap picks this for you and tests it first — write it by hand only if you know the console script runs on your machine. Where Windows Application Control blocks pip's console shims (thunderbird-mcp.exe), a config that points at it produces a client that times out with nothing to point at; python -m tbmcp always works.

Verify with claude mcp get thunderbird, or /mcp inside a session.

[!TIP] Run claude mcp add from PowerShell or CMD. Git Bash rewrites /c into C:/ and corrupts the written config; if you must use it, prefix with MSYS_NO_PATHCONV=1.

tbmcp setup codex --toolsets all

Or by hand in ~/.codex/config.toml:

[mcp_servers.thunderbird]
command = 'C:\Users\you\Thunderbird-MCP\.venv\Scripts\python.exe'
args = ["-m", "tbmcp", "serve", "--toolsets", "all"]
env = { PYTHONUTF8 = "1", PYTHONUNBUFFERED = "1" }
startup_timeout_sec = 60
tool_timeout_sec = 120

# Codex ignores tool annotations, so safety has to be stated here.
default_tools_approval_mode = "writes"
[mcp_servers.thunderbird.tools.pref_set]
approval_mode = "approve"
[mcp_servers.thunderbird.tools.mail_send]
approval_mode = "approve"

bootstrap picks this for you and tests it first — write it by hand only if you know the console script runs on your machine. Windows paths must be single-quoted TOML literals — "C:\Users\…" is an invalid escape sequence. Codex also builds the child environment from scratch, so anything your server needs has to be in env. Verify with codex mcp get thunderbird --json.

tbmcp setup claude-desktop cursor vscode gemini zed
tbmcp setup --print-config all      # or just show the blocks and change nothing

setup prefers each client's own CLI when it is on PATH, falls back to editing the config file, backs it up first, and reports added / updated / unchanged per client. It never hand-edits ~/.claude.json, which holds OAuth state and project trust decisions.

Toolsets

Tools are grouped so you only pay context for what you use. The default set is lean; add the rest with --toolsets.

tbmcp serve --toolsets all              # everything
tbmcp serve --toolsets mail,settings    # exactly these
tbmcp serve --toolsets +calendar        # the default set plus one
tbmcp tools --toolsets all              # list what would be registered

112 tools across 10 toolsets; 48 of them read-only. Full signatures in docs/TOOL-REFERENCE.md.