Thunderbird Mail MCP

English | 简体中文

Give AI agents access to local Thunderbird mail through the Model Context Protocol (MCP): search Inbox and Sent, read messages and attachments, save drafts, and send explicitly authorized mail when enabled. The server defaults to the review profile, which does not expose direct-send tools.

Each writing tool has a separate purpose: send_email sends a new message; reply_email and forward_email send a native reply or attachment forward bound to a source message; create_draft only saves a draft; and compose_email only opens a compose window. Saving a draft is not a prerequisite for sending.

This is a standalone Python MCP server using standard stdio transport. It does not depend on Codex, Qoder, QwenWork, any model provider's SDK or account, API keys, skills, or private client configuration directories. The client starts the server, selects a model, and manages tool-call permissions. The server handles local mail data and its interaction with Thunderbird.

Features

Queries do not modify mbox files or mark messages as read. The server does not connect directly to SMTP, POP, or IMAP; Thunderbird handles account authentication and delivery. Current version: 0.12.0, with 16 tools in total. The default review profile exposes 13, read_only exposes 10, and direct_send exposes all 16. See the tool and behavior reference.

Replies, forwards, and preparation diagnostics require an extension with the corresponding features and a refreshed MCP connection. Updating files does not update a running process.

Related MCP server: Thunderbird MCP Server

Capability profiles

Set THUNDERBIRD_MCP_PROFILE in the environment used to launch the server:

Values must match exactly. An empty or unknown value prevents startup. After changing the setting, restart or reconnect the MCP server and refresh the tool list. get_send_capabilities reports mcp_profile, review_enabled, and direct_send_enabled so clients can verify the connected process.

Profiles control which tools the server registers. They do not replace authorization for individual messages or cancel queued work. Status/capability calls may initialize or update the local journal even in read_only.

Query sent mail

Sent contains saved sent copies. Query it with the folders parameter of query_email. There is no separate sent() tool. send_email sends new mail; the queries below only read local data.

First call list_mail_folders and confirm that the Sent entry has available=true. Then call query_email with:

{
  "folders": ["Sent"],
  "page_size": 50
}

To search Inbox and Sent together, use the same tool:

{
  "folders": ["Inbox", "Sent"],
  "page_size": 50
}

Each result includes its source folder and a locator. Pass locators to read_emails, then use attachment IDs with read_attachment. Follow next_cursor by passing it as cursor with the same query parameters. Omitting folders searches Inbox only; the legacy search_email, read_email, and list_recent_email tools also read Inbox only.

By default, Sent is the Sent mbox beside the configured Inbox file. If it lives elsewhere, set its path explicitly in the client's launch environment:

{
  "THUNDERBIRD_INBOX_PATH": "/absolute/path/to/Inbox",
  "THUNDERBIRD_SENT_PATH": "/absolute/path/to/Sent"
}

These calls do not send, move, or mark messages. Sent does not include pending Outbox messages, and a saved copy does not prove recipient delivery. Full parameters and boundaries are documented in the Inbox and Sent reference.

Client compatibility

A compatible client must be able to start a local process on the machine holding the mail and support MCP stdio initialization, tool discovery, and calls. Switching clients does not require server code changes. Configuration wrappers such as mcpServers or TOML are client conventions, not a universal MCP configuration format.

Native deployment currently targets macOS. The Thunderbird executable path, Native Messaging registration location, and send-state directory follow macOS conventions. Linux CI verifies the protocol and mocked behavior; it does not establish support for native Thunderbird deployment on Linux or Windows.

Requirements

• Python 3.10+, preferably 3.11. Install dependencies with uv 0.13.0 and the checked-in uv.lock.

• Readable local mbox files for Inbox and saved Sent copies, such as an existing Thunderbird POP mail store. Sent defaults to a sibling of Inbox and can be configured separately. There is no automatic account discovery, Outbox support, or direct Maildir reading.

• Thunderbird at /Applications/Thunderbird.app to open native compose windows.

• Thunderbird 153+, the matching 0.12.0 extension, and the native host for drafts, sending, replies, forwards, or preparation diagnostics. Mail queries do not require the extension.

• Node 22.23.0 for development tests only; the Python server does not require Node at runtime.

Quick start

1. Install the server

Install Git, Python, and the specified uv version, then use a fresh checkout:

git clone https://github.com/zhangjian0410/thunderbird-mail-mcp.git
cd thunderbird-mail-mcp
uv lock --check
uv sync --locked --no-install-project
uv sync --locked --no-build-isolation

The first sync installs the locked build tools; the second uses them to install this project without resolving a separate build environment. Validate upgrades in a separate checkout before changing an installation used by a running service.

2. Configure a local MCP client

Find Thunderbird's local mail directory in Account Settings and identify the actual mbox Inbox file. Replace the three absolute paths in the generic configuration example:

{
  "mcpServers": {
    "thunderbird_mail": {
      "type": "stdio",
      "command": "/absolute/path/thunderbird-mail-mcp/.venv/bin/python",
      "args": ["/absolute/path/thunderbird-mail-mcp/server.py"],
      "env": {
        "THUNDERBIRD_INBOX_PATH": "/absolute/path/to/Inbox",
        "THUNDERBIRD_MCP_PROFILE": "review"
      }
    }
  }
}

command is the Python executable; the script path is a separate entry in args; env is passed to the server process. Absolute paths avoid dependence on the client's working directory. Even when paths contain spaces, do not combine Python and the script into one command string.

In Qoder IDE, add the configuration under Settings → MCP → My Servers → Add; for the CLI, follow its documented mcpServers format. In QwenWork desktop, import the JSON under Extensions → Connectors → Add, or choose STDIO and enter equivalent launch parameters. Other clients use the same command, args, and env in their own configuration format.

THUNDERBIRD_INBOX_PATH selects Inbox; if omitted, the server uses the placeholder ~/Library/Thunderbird/Inbox. Optional THUNDERBIRD_SENT_PATH selects the Sent mbox; otherwise it uses Sent beside Inbox. Both paths support absolute paths and ~. The server does not scan accounts or verify Thunderbird's configured sent-copy (FCC) location. Set Sent explicitly when its actual location differs.

THUNDERBIRD_MCP_PROFILE defaults to review. Select direct_send only when direct sending is needed and the caller manages message authorization. No mailbox password or model API key is required.

3. Verify mail queries

Enable the server in your client and refresh its tool list. Expect 13 tools with the default review profile, 10 with read_only, or 16 with direct_send. Call get_send_capabilities to verify mcp_profile, then list_mail_folders to confirm Inbox is available. For example, ask your agent:

Find messages from sender@example.test and list their subjects and dates. Read a message I select, without creating drafts or sending mail.

Successful queries prove that local data is readable. They do not establish whether Thunderbird has synchronized with the mail server. See Sent queries for saved sent copies and combined-folder queries; an unavailable Sent file does not prevent default Inbox queries.

4. Use writing tools

compose_email only needs the local Thunderbird installation. Drafts, sending, replies, forwards, and preparation diagnostics need the enabled extension and native host. Follow the optional writing deployment guide.

Check get_send_capabilities for ready=true, the actual sender identity, and the active profile. Sending, replying, and forwarding also require direct_send. Attachments, drafts, HTML, replies, forwards, and diagnostics respectively require attachments_v1, draft_v1, html_v1, reply_v1, forward_v1, and forward_diagnostic_v1.

Use create_draft to save a draft, or send_email when the user has explicitly authorized sending. After either request, poll get_send_status: drafted means the draft was saved; sent means Thunderbird confirmed submission to the outgoing server. pending only means the request was accepted.

Saving a draft does not trigger sending. If a draft is previewed before sending, the later send_email call is a separate request with a new idempotency key. There is no MCP tool for sending an existing draft by its ID. Previewing an HTML draft is recommended, but the server does not enforce it as a prerequisite.

Operational boundaries

• The server registers only the tools allowed by read_only, review, or direct_send. The default review profile excludes direct-send tools. Profiles are fixed at process startup; reconnect after changing the environment. MCP calls to hidden tools fail.

• The caller manages sending authorization. The server neither reads a client's approval allowlist nor interprets natural-language permission. Obtain explicit authorization for the recipients and purpose before sending, replying, or forwarding. The server does not validate per-message human approval records or confirmation tokens; client confirmation prompts depend on the client's settings.

• pending and sending do not mean sent. sent confirms Thunderbird's submission, not receipt by the recipient. Retry the same logical message with the same idempotency key. Never use a new key to resend an uncertain outcome.

• Complete local enumeration does not prove server synchronization. Check query coverage, pagination, and body truncation metadata.

• Mailboxes, native configuration, send databases, XPI files, and deployment backups may contain private data and must not be committed. Automated scans cover tracked files and Git history.

Project layout and documentation

This README is the primary English entry point. A complete Chinese README is also available. The tool reference, development guide, and changelog are available in both languages:

• Tools, data boundaries, and writing deployment

• Development, dependency updates, CI, and sensitive-data checks

• Changelog

Run the full test suite:

uv run --no-sync python -m unittest discover -s tests -v
node --test tests/*.test.cjs

Tests use temporary mailboxes and mocked sending APIs. Protocol tests start independent MCP subprocesses. They do not call model APIs, deploy the extension, or send real mail.

License

MIT License.