Commonpost for Thunderbird MCP server

Commonpost MCP for Thunderbird

MCP server for Thunderbird: mail, calendar, contacts in all your accounts. Windows, macOS, Linux.

Your AI assistant can search, read and draft mail in every account you have in Thunderbird, and check it against your calendar and contacts. Free and open source (MIT), through the Model Context Protocol.

Latest release: v0.24.0 (2026-11-11) -- see the changelog or all releases.

• Every account you already have in Thunderbird. Gmail, Outlook.com, Microsoft 365, your own domain, IMAP, POP: no new login, no password to hand over.
• Mail, calendar and contacts together. Your assistant can check an email against your calendar.
• Nothing is sent without your click. New mail and replies open in Thunderbird's compose window, for you to read and send. Calendar events are added directly by default, and no invitation is sent.
• Email is treated as untrusted. Text a sender hides from you is removed before your assistant reads it. That reduces prompt injection; it does not prevent it, which is why sending needs your click (details).
• Runs on your computer. What the assistant reads goes to the AI service you use, not to us. Each release can be rebuilt byte for byte from this source.

Try asking:

Am I free Thursday at 2:30? Check my calendars and all my email accounts.
Find the invoice for my dishwasher, whatever account it went to, and open a warranty claim with it attached.
What needs a reply before Friday? Open each reply for me to review.

---

Contents

• Quick install (about 3 minutes)
• Why?
• How it works
• What you can do
• Setup
• Security
  • Why Thunderbird says "full, unrestricted access"
• If Thunderbird disables Experiment add-ons on the Release channel
• Troubleshooting
• Development
• Project structure
• Known issues
• License and credits

Quick install (about 3 minutes)

Requirements: Thunderbird 140 or later on Windows, macOS or Linux. Node.js 22 or later, except with the Claude Desktop bundle.

Every tool works the same on the three systems. One difference: on Windows, attachments go through the bridge rather than by file path (see attachments on Windows).

For AI agents installing this: step 1 happens in Thunderbird's window, so ask the user to do it, then continue. This project is not published on npm, PyPI or Docker Hub: do not use npx or uvx. Its only sources are this repository's releases, the Claude Code plugin and the Gemini CLI extension. scripts/install.sh is for development only. For Claude Desktop, the .mcpb bundle is the whole install: no Node.js and no config file to edit. The bridge and the add-on do not need the same version number. Step by step: llms-install.md.

1. Install the add-on in Thunderbird.

• Download the file ending in .xpi from the latest release.
• In Thunderbird: menu ≡ (top right) > Add-ons and Themes > gear icon > Install Add-on From File, then restart Thunderbird.
• Thunderbird warns that the add-on gets "full, unrestricted access": it says so for every add-on of this kind (why, and what this one does).

2. Connect your assistant. Pick the line for the one you use.

• Claude Desktop (Windows, macOS): download the file ending in .mcpb from the same release and open it with Claude Desktop, or use Settings > Extensions > Advanced settings > Install Extension. Nothing else to install: it uses the Node.js that Claude Desktop ships with. Its name can carry a lower number than the add-on (for example v0.20.0 beside a v0.22.4 add-on): it is named after the bridge it holds, which changes less often. See Claude Desktop.

• Claude Code, with the plugin, which keeps the bridge up to date (see Claude Code plugin):

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

• Gemini CLI, as an extension that carries the bridge:

  gemini extensions install https://github.com/commonpost/thunderbird-mcp
  

• Any other client (VS Code, Cursor, Codex CLI, Claude Code without the plugin...):

  1. Check Node.js: node --version must show 22 or later.

  2. Download the bridge, a single file, into a folder you will keep. macOS and Linux:

     mkdir -p ~/commonpost-mcp && curl -fL -o ~/commonpost-mcp/mcp-bridge.cjs https://github.com/commonpost/thunderbird-mcp/releases/latest/download/mcp-bridge.cjs
     

     Windows (PowerShell):

     New-Item -ItemType Directory -Force "$env:USERPROFILE\commonpost-mcp" | Out-Null; Invoke-WebRequest -OutFile "$env:USERPROFILE\commonpost-mcp\mcp-bridge.cjs" https://github.com/commonpost/thunderbird-mcp/releases/latest/download/mcp-bridge.cjs
     

  3. Register it. Claude Code, on Linux and on Windows (-s user makes it available in every folder):

     claude mcp add -s user thunderbird -- node "/home/<you>/commonpost-mcp/mcp-bridge.cjs"
     claude mcp add -s user thunderbird -- node "C:\Users\<you>\commonpost-mcp\mcp-bridge.cjs"
     

     Other clients: add this to the client's MCP config, with the full path of the file (each client has its own file and format: see Other MCP clients). In JSON, write Windows paths with / ("C:/Users/<you>/commonpost-mcp/mcp-bridge.cjs"); a JSON file does not expand ~. On macOS, if the client cannot find node, set command to the full path that which node prints.

     {
       "mcpServers": {
         "thunderbird": {
           "command": "node",
           "args": ["/home/<you>/commonpost-mcp/mcp-bridge.cjs"]
         }
       }
     }
     

3. Test it. With Thunderbird open, ask your assistant: "list my Thunderbird accounts". It should name your accounts; your client may first ask you to allow the tool. Nothing comes back? Check that Thunderbird is open and the add-on enabled, then quit your client completely and start it again (Claude Desktop on Windows: its icon near the clock > Quit). Still nothing: see Troubleshooting.

4. Choose what your assistant may see. Open the add-on's options (menu ≡ > Add-ons and Themes > Commonpost MCP for Thunderbird > wrench button) and pick the accounts and tools. Until you do, every account and tool is visible to MCP clients.

To update or remove it later, see Updating and Uninstall.

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 42 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 short 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 require review by default because Block skipReview for mail starts enabled: skipReview: true is honored only after you explicitly disable it. By default, nothing is sent without your review. Events and tasks are added at once on a new install, as updateEvent and deleteEvent change them: they send no invitation, and asking for six appointments means nothing to save by hand. Enable Block skipReview for events and tasks to review each one in Thunderbird's dialog.

---

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. If the client asks for the tools while Thunderbird is not running, the bridge answers with the tools Thunderbird last listed, which it keeps in your cache folder (%LOCALAPPDATA%\commonpost-mcp on Windows, ~/Library/Caches/commonpost-mcp on macOS, $XDG_CACHE_HOME/commonpost-mcp or ~/.cache/commonpost-mcp elsewhere); tool calls fail until Thunderbird is started.

---

What you can do

Mail

Tool	Description
listAccounts	List all email accounts and their identities
listFolders	Browse folder tree with message counts -- filter by account or subtree; savedSearches lists saved searches instead; refresh with folderPath first fetches that folder's new mail from its mail server (IMAP, Exchange, Graph; not news or feeds) and waits up to 20 s
searchMessages	Search headers across accounts. Words must all match (subject, from, to, cc, preview); operators from:, to:, cc:, subject:, participant: (from/to/cc/bcc; @domain matches addresses in that domain only, commas list alternatives: participant:@acme.com,@acme-group.com) and quoted phrases can be combined, e.g. participant:@acme.com subject:"invoice 42". groupBy: "sender" | "thread" returns one row per sender or conversation (latestId is the newest message that is not a draft); threadOf: {messageId, folderPath} returns a whole conversation across folders (Sent included), oldest first (it reads at most 10,000 headers, then sets incomplete: true). A Re: message sent without threading headers joins by subject the earlier message its sender took part in (linkedBy: "subject"); the same mail sent separately to several people and repeated notifications stay separate. Filters pick messages of the conversation without cutting its links. Trash and Junk are skipped unless includeTrash or an explicit folderPath. Always returns { messages, totalMatches, offset, limit, hasMore } (default 20 rows, max 200); format: "table" returns { columns, rows }, and format: "legacy" the output of 0.10 and earlier (deprecated), see CHANGELOG. Also countOnly, includeSubfolders, date range, unread/flagged filters, tag (name or key; an unknown one is matched as a raw keyword and warning lists the known tags), searchBody (Gloda full text: terms under 3 characters are left out and listed in warning, English words match other forms, Russian and other languages only the exact word form) and dedupByMessageId (copies in several folders collapse into one row with dupLocations). attachmentName (part of a filename, any case) and attachmentType (application/pdf, or a prefix such as image/) keep messages with a matching attachment, combined with the other filters; each row lists its matching attachments (name, contentType, size). Only messages Thunderbird marks as having attachments are read, from their local copy (nothing is downloaded or decrypted), at most 500 per call and 16 MiB each; attachmentSearch gives how many were checked and why the others were skipped (encrypted, tooLarge, notOffline, unreadable, limitReached). Thunderbird flags a message from its top-level structure, so a signed message (multipart/signed), a multipart/related one or a single-part attachment is usually not found. While reading encrypted messages is not allowed, a query with words leaves out messages with an encrypted envelope, as without attachment options. attachmentName and attachmentType cannot be combined with searchBody, threadOf or format: "legacy". fields returns only the listed columns (date, author, recipients, ccList, subject, read, flagged, tags, preview, dupLocations); id, folderPath and the columns an option adds are always kept; not with countOnly, groupBy or format: "legacy".
getMessage	Read full email content -- bodyFormat: markdown (default), text, or html. Bodies are capped (maxBodyChars, default 20000); a longer body sets bodyTruncated and nextBodyOffset, read the rest with bodyOffset. Set rawSource: true for the complete RFC 2822 source (same cap), decoded as UTF-8 when valid, else by its top-level, part or detected charset (rawCharset; a warning when parts declare different charsets, listed in rawMixedCharsets, or when invalid UTF-8 was replaced), with hidden characters removed as in a body; rawEncoding: "base64" returns the exact bytes. Optional attachment saving. Set includeInlineImages: true to append supported inline CID images as MCP image blocks (PNG, JPEG, GIF, or WebP; max 1 MiB base64 per image and 4 MiB total). Skipped images are reported in attachment metadata. authentication gives the SPF, DKIM and DMARC results of the topmost Authentication-Results header, as the receiving mail server reported them (authservId names it); Thunderbird checks none of this, and a sender can forge such headers lower down.
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 (mailto, https, oneClick), for reading only.
getRecentMessages	Recent messages newest first from all folders (Trash/Junk skipped) or one folder -- daysBack (default 7), unread/flagged filters, includeTrash, pagination. Same envelope, rows and format as searchMessages. fields as in searchMessages.
displayMessage	Open a message in Thunderbird's GUI -- 3pane (default), tab, or window mode
updateMessage	Mark read/unread, flag/unflag, add/remove tags, move between folders, or trash -- supports bulk via messageIds. Tags by the name shown in Thunderbird (Important, To Do) or by key ($label1); another keyword is added, and what cannot be a keyword is skipped, both with a warning listing the known tags
deleteMessages	Delete messages as Thunderbird's Delete key does: moved to Trash, except in Trash itself (deleted for good) and on IMAP accounts set not to move deleted mail (their setting applies)
createFolder	Create new subfolders to organize your mail, or a saved search (virtual folder: a live view, nothing moved) with savedSearch
renameFolder	Rename an existing mail folder; returns its new URI as path
deleteFolder	Delete a folder (moves to Trash, or permanently deletes if already in Trash); a saved search is removed as a view, no mail deleted
moveFolder	Move a folder to a new parent within the same account
emptyTrash	Permanently delete all messages in Trash (including subfolders)
emptyJunk	Permanently delete all messages in Junk/Spam (including subfolders)

Compose

Tool	Description
sendMail	Compose a new email -- opens a review window; direct sending requires explicitly disabling the skipReview safety block, and adds the identity signature and automatic Cc/Bcc as the compose window would; dryRun reports what the call would do (sender, recipients, attachments, estimated size) or the error it would return, and does nothing
replyToMessage	Reply with quoted original and proper threading, from the identity Thunderbird would pick. mode: window (default) opens a review window, draft saves a draft with the recipients Thunderbird's Reply / Reply All computes and the body its reply window builds (cite line, quote, signature, reply position), send (or skipReview: true) sends directly -- it needs explicit to and from and is subject to the same safety block. latestInThread: true (window or draft only) replies to the newest message of the conversation, Sent included, and returns it as repliedTo; threadIncomplete in the result means a large mailbox was read in part and a newer message may exist
forwardMessage	Forward with all original attachments preserved, from the identity Thunderbird would pick. mode as for replyToMessage (draft and send get the subject and body Thunderbird's forward window builds: header table, original body, signature); to is optional except with send, which needs explicit to and from
saveDraft	Save a new message as a draft, as Thunderbird's compose window saves it (with the identity signature), or edit an existing draft with draftId -- returns its messageId and folderPath

All compose tools open a window for you to review and edit before sending by default. The Block skipReview setting for mail is on by default, so skipReview: true (and mode: "send") is rejected until you explicitly disable it; only then can it send directly. mode: "draft" only saves a draft, so the preference does not block it (even next to skipReview: true); it needs the saveDraft tool to be enabled in the settings, as a tool you disabled is not reachable through another one. Attachments can be file paths or inline base64 objects.

A direct send or saving a draft (saveDraft, mode: "draft") can take a while: the bridge waits up to 180 s for Thunderbird (30 s for every other call). Your MCP client may also have its own time limit for a tool call; if it is shorter than 180 s, the client can give up while Thunderbird goes on sending or saving, so check the Sent folder and the Outbox (or the Drafts folder) before retrying to avoid sending the message, or saving the draft, twice.

Compose tools validate the from identity strictly -- if the specified sender doesn't match any configured Thunderbird identity, the tool returns an error instead of silently substituting another account.

Filters

Tool	Description
listFilters	List all filter rules with human-readable conditions and actions; with confirmation: true, read the state of a pending or recent confirmation instead, optionally one by confirmationId (see below). format: "table": one row per rule, without its conditions
createFilter	Create filters with structured conditions (from, subject, date...) and actions (move, tag, flag...)
updateFilter	Modify a filter's name, enabled state, conditions, or actions; filterName refuses an index that now points at another rule
deleteFilter	Remove a filter by index; filterName refuses an index that now points at another rule
reorderFilters	Change filter execution priority
applyFilters	Run filters on a folder on demand -- let your AI organize your inbox

Full control over Thunderbird's message filters. Changes persist immediately. Your AI can create sorting rules, adjust priorities, and run them on existing mail. applyFilters runs only the enabled rules marked "Manually Run" (tick it in the filter editor on the rules the assistant may launch) and lists the ones it skipped.

Filter rules that forward or reply send mail without the review window that the compose tools keep. The Block filter forward/reply setting (options page, Send Safety) is on by default: while it is on, such rules cannot be created or changed through MCP, and a filter list that holds one cannot be run through applyFilters. Deleting the rule stays possible. If you choose Ask me each time instead, a request of that kind returns pending_user_confirmation and Thunderbird shows a dialog with the rule, its conditions and its full destination; nothing is written unless you confirm it there, and closing the dialog or not answering within ten minutes writes nothing. Whatever the setting, a rule that forwards or replies cannot be created or changed through MCP to run on outgoing mail, on archiving or periodically: it would send mail already in the mailbox, or mail you sent. Through MCP, such a rule made in Thunderbird can only be deleted or given another type. Thunderbird also takes mail moved, copied or saved into a folder of an IMAP account for new mail, and runs that account's rules on it: in the Inbox whether read or not, and in any folder the rules that run after classification, if the mail is unread (a draft counts as unread). So, whatever the setting, MCP refuses to put mail where the rules for new mail run while such a rule is enabled there -- moving old mail into that account's Inbox, for instance. Everywhere else it does the work and warns in the result, naming the rule: moving unread mail to an ordinary folder, or saving a draft, on an account whose rules forward after classification. The check looks at whether such a rule is enabled, not at its conditions, so a warning does not mean the rule matches your messages. You can turn the rule off in Tools > Message Filters.

Encrypted messages

OpenPGP and S/MIME messages are not decrypted for the assistant by default: getMessage returns their headers and a short notice instead of their content. searchMessages leaves out a message its query matched, getRecentMessages lists one with the wire-level subject, no preview and encrypted: true, and threadOf leaves them out and never links a conversation through their subject. The setting Let the assistant read encrypted messages (Options > Encrypted messages) turns this on; the decrypted content is then handed to the assistant, and so to the service that runs it.