Thunderbird MCP Server

MCP (Model Context Protocol) server that gives AI agents access to Thunderbird email, contacts, and calendars. Works with any MCP-compatible client — Claude, OpenClaw, or custom integrations.

Architecture

MCP Client (stdio JSON-RPC 2.0)
    ↓
mcp-bridge.cjs (Node.js)  ← reads ~/.thunderbird-mcp-token
    ↓ HTTP POST localhost:8765 (Bearer token auth + Host validation)
Thunderbird Extension
    ↓ Thunderbird APIs
Email / Contacts / Calendars

Related MCP server: Thunderbird MCP

Prerequisites

• Thunderbird 102+

• Node.js 18+

• zip command (for building the extension)

Setup

1. Build the extension

./scripts/build.sh

Creates dist/thunderbird-mcp.xpi.

2. Install to Thunderbird

./scripts/install.sh

Auto-detects your Thunderbird profile and copies the extension. Restart Thunderbird after installing.

Alternative (manual install): Open Thunderbird → Tools → Add-ons and Themes → gear icon → Install Add-on From File → select dist/thunderbird-mcp.xpi.

3. Verify

Check the Thunderbird console (Tools → Developer Tools → Error Console) for:

Thunderbird MCP server listening on port 8765

4. Configure your MCP client

Add to your MCP client configuration:

{
  "mcpServers": {
    "thunderbird": {
      "command": "node",
      "args": ["/path/to/thunderbird-mcp/mcp-bridge.cjs"]
    }
  }
}

5. Test

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-bridge.cjs

Should return all 10 tools.

Tools

listAccounts

List all configured email accounts and their identities.

{ "name": "listAccounts", "arguments": {} }

searchMessages

Search message headers with filtering. Good for finding emails by sender, subject, date range.

{
  "name": "searchMessages",
  "arguments": {
    "query": "invoice",
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "maxResults": 20,
    "sortOrder": "desc"
  }
}

fullTextSearch

Full-text search across message bodies using Thunderbird's Gloda index. Faster for body content.

{ "name": "fullTextSearch", "arguments": { "query": "project deadline" } }

getMessage

Read full email content by ID and folder path (from search results).

{
  "name": "getMessage",
  "arguments": {
    "messageId": "abc123@example.com",
    "folderPath": "mailbox://user@imap.example.com/INBOX"
  }
}

sendMail

Open a compose window for user review before sending. Same interface as composeMail.

{
  "name": "sendMail",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "Message body here",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com"
  }
}

composeMail

Open a compose window for user review before sending.

{
  "name": "composeMail",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Draft for review",
    "body": "Please review before sending"
  }
}

replyToMessage

Reply to a message with quoted original and proper threading.

{
  "name": "replyToMessage",
  "arguments": {
    "messageId": "abc123@example.com",
    "folderPath": "mailbox://user@imap.example.com/INBOX",
    "body": "Thanks for your message!",
    "replyAll": true
  }
}

forwardMessage

Forward a message with original attachments preserved.

{
  "name": "forwardMessage",
  "arguments": {
    "messageId": "abc123@example.com",
    "folderPath": "mailbox://user@imap.example.com/INBOX",
    "to": "forward-to@example.com",
    "body": "FYI - see below"
  }
}

searchContacts

Search contacts by name or email across all address books.

{ "name": "searchContacts", "arguments": { "query": "john" } }

listCalendars

List all configured calendars.

{ "name": "listCalendars", "arguments": {} }

Security

• Bearer token authentication: On startup, the extension generates a random 64-character hex token and writes it to ~/.thunderbird-mcp-token (mode 0600). All HTTP requests must include an Authorization: Bearer <token> header. The bridge reads this file automatically on each request.

• DNS rebinding protection: The HTTP server validates the Host header and only accepts requests from localhost, 127.0.0.1, or [::1]. Requests with any other Host header receive a 403 Forbidden response.

• No auto-send: Both sendMail and composeMail open a compose window for user review. Emails are never sent without user confirmation.

Known Limitations

• IMAP folders may be stale: Thunderbird doesn't always sync IMAP folders in the background. Click a folder in the UI to force sync, or the extension will attempt updateFolder() as a best-effort.

• Compose window tools (sendMail, composeMail, replyToMessage, forwardMessage) open a window — user must click Send manually.

• Port 8765 is hardcoded. If another service uses this port, the extension won't start.

Troubleshooting

OpenClaw Integration

Using this with OpenClaw? Two guides available:

• OPENCLAW-SETUP.md — Quick setup: install extension, configure MCPorter, wire it up

• OPENCLAW-AGENT-GUIDE.md — Full agent build: workspace layout, AGENTS.md, SOUL.md, USER.md, openclaw.json config, example conversations, and troubleshooting

Credits

Built by combining approaches from:

• TKasperczyk/thunderbird-mcp — rich tool implementations

• bb1/thunderbird-mcp — clean modular architecture + Gloda search

License

MIT