Commonpost MCP for Thunderbird

Commonpost MCP for Thunderbird

Give your AI assistant full access to Thunderbird -- search mail, compose messages, manage filters, and organize your inbox. All through the Model Context Protocol.

A continuation of [thunderbird-mcp](https://github.com/TKasperczyk/thunderbird-mcp) by Tomasz Kasperczyk (MIT), started from its 0.7.5 release with its full history kept. It is an independent project by the Commonpost community, not the original and not endorsed by it; it can be installed beside the original (see Migrating). If the original author wants any of this work back, we hand it over: our changes are MIT-licensed and offered upstream too. Thunderbird is a trademark of the Mozilla Foundation; this project is not affiliated with Mozilla or MZLA.

The original was inspired by bb1/thunderbird-mcp. What is in this release is listed in the changelog.

---

Quick install (about 3 minutes)

Requirements: Windows, macOS or Linux, with Thunderbird 140 or later and Node.js 22 or later. On Windows, attach files through the bridge (see Attachments refused).

1. Install the extension. Download commonpost-mcp-v .xpi from the latest release. In Thunderbird: Tools > Add-ons and Themes > gear menu > Install Add-on From File. Restart Thunderbird.
2. Download mcp-bridge.cjs from the same release and put it in a folder you will keep, for example ~/commonpost-mcp/. The bridge is a single file and needs nothing else: the release does not ship a package.json. (The bridge carries its own version; it reads no package.json.)
3. Check Node.js: node --version must show 22 or later.
4. Register the bridge with your MCP client.

• Claude Code, with the plugin (no file to download or to update by hand; see Claude Code plugin):

claude plugin marketplace add commonpost/thunderbird-mcp claude plugin install commonpost-mcp@commonpost

• Claude Code, with the file (use the absolute path of the file):

claude mcp add commonpost-mail -- node /absolute/path/to/mcp-bridge.cjs

• Claude Code on Windows, for example:

claude mcp add commonpost-mail -- node C:\Users\ \commonpost-mcp\mcp-bridge.cjs

• Other clients: add this to the client's MCP config (Claude Desktop, VS Code, Cursor, Codex CLI and Gemini CLI have their own file and format: see Other MCP clients). In JSON, write Windows paths with / or double the backslashes ("C:/Users/ /commonpost-mcp/mcp-bridge.cjs").

json { "mcpServers": { "commonpost-mail": { "command": "node", "args": ["/absolute/path/to/mcp-bridge.cjs"] } } }

1. Test it. Keep Thunderbird open and ask your assistant: "list my Thunderbird accounts".

The bridge is not updated automatically, and each MCP client has its own. When one should be replaced, the extension says so in a tool result (your assistant passes it on) and in its options page (section Bridge), which lists the bridges that connected with "Up to date", "Newer version available" (it works; updating is optional) or "Update recommended". For a bridge to update or one the extension refuses, Thunderbird also shows a system notification, once per bridge and per Thunderbird session; the hidden preference extensions.commonpost-mcp.bridgeUpdateAlert set to false turns it off. Every release page starts with what the release brings, whether it changes the bridge, and the steps: download mcp-bridge.cjs and put it in place of your copy (its path is in the MCP configuration of your client; in Claude Code: claude mcp get ), then reconnect your MCP client (/mcp in Claude Code); in Claude Desktop, install the .mcpb bundle again; with the Claude Code plugin, update the plugin. A release that does not change the bridge ships the same bridge again. The extension's version is shown in Tools > Add-ons and Themes.

Right after installing, open the extension's options page (Tools > Add-ons and Themes > Commonpost MCP for Thunderbird > Options) and choose which accounts and tools your assistant may use. Until you do, every account and tool is visible to MCP clients.

Snap, Flatpak and macOS need no extra step in most cases; see Sandbox-aware connection discovery. If something fails, see Troubleshooting.

---

Why?

Thunderbird has no official API for AI tools. Your AI assistant can't read your email, can't help you draft replies, can't organize your inbox. This extension fixes that -- it exposes 41 tools over MCP so any compatible AI (Claude, GPT, local models) can work with your mail the way you'd expect. The list is kept to about 40 tools so that assistants choose among them reliably; older Cursor versions also sent an agent only the first 40 tools of all servers combined (since January 2026 Cursor loads tool descriptions only when needed), and VS Code allows 128 tools per request.

Mail sends and event/task creation require review by default because Block `skipReview` starts enabled. skipReview: true is honored only after you explicitly disable that safety setting. By default, nothing is sent or created without your review.

---

How it works

                    stdio              HTTP (localhost:8780-8789)

MCP Client <-----------> Bridge <---------------------> Thunderbird (Claude, etc.) mcp-bridge.cjs Extension + HTTP Server

The Thunderbird extension embeds a local HTTP server with session-scoped auth tokens. The Node.js bridge translates between MCP's stdio protocol and HTTP, discovering the port and token automatically via a connection file. The bridge handles MCP lifecycle methods (initialize, ping) locally, so clients can connect even before Thunderbird is fully loaded.

---

What you can do

Mail

| getMessages | Read full email content for up to the configured batch limit in one call (default 10, max 20). Uses the same bodyFormat, rawSource, and attachment options as getMessage; each item supplies messageId and folderPath. Bodies are capped per message (maxBodyChars, default 4000). headersOnly returns only the headers as received and the flags, for up to 200 messages whatever that limit, without parsing any body; a List-Unsubscribe header also comes parsed as unsubscribe (`ma