Thunderbird MCP

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

Inspired by bb1/thunderbird-mcp. Rewritten from scratch with a bundled HTTP server, proper MIME decoding, and UTF-8 handling throughout.

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 24 tools over MCP so any compatible AI (Claude, GPT, local models) can work with your mail the way you'd expect.

Compose tools open a review window before sending. Nothing gets sent without your approval.

How it works

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

The Thunderbird extension embeds a local HTTP server. The Node.js bridge translates between MCP's stdio protocol and HTTP. Your AI talks stdio, Thunderbird talks HTTP, the bridge connects them. The bridge handles MCP lifecycle methods (initialize, ping) locally, so clients can connect even before Thunderbird is fully loaded.

What you can do

Mail

Compose

All compose tools open a window for you to review and edit before sending.

Filters

Full control over Thunderbird's message filters. Changes persist immediately. Your AI can create sorting rules, adjust priorities, and run them on existing mail.

Contacts & Calendar

Setup

1. Install the extension

git clone https://github.com/TKasperczyk/thunderbird-mcp.git

Install dist/thunderbird-mcp.xpi in Thunderbird (Tools > Add-ons > Install from File), then restart. A pre-built XPI is included in the repo — no build step needed.

2. Configure your MCP client

Add to your MCP client config (e.g. ~/.claude.json for Claude Code):

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

That's it. Your AI can now access Thunderbird.

Security

The extension listens on localhost:8765 only. No remote access. However, any local process can reach it while Thunderbird is running — keep this in mind on shared machines.

Troubleshooting

Development

# Build the extension
./scripts/build.sh

# Test the HTTP API directly
curl -X POST http://localhost:8765 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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

After changing extension code: remove from Thunderbird, restart, reinstall the XPI, restart again. Thunderbird caches aggressively.

Project structure

thunderbird-mcp/
├── mcp-bridge.cjs              # stdio <-> HTTP bridge
├── extension/
│   ├── manifest.json
│   ├── background.js           # Extension entry point
│   ├── httpd.sys.mjs           # Embedded HTTP server (Mozilla)
│   └── mcp_server/
│       ├── api.js              # All 24 MCP tools
│       └── schema.json
└── scripts/
    ├── build.sh
    └── install.sh

Known issues

• IMAP folder databases can be stale until you click on them in Thunderbird

• Email bodies with control characters are sanitized to avoid breaking JSON

• HTML-only emails are converted to plain text (original formatting is lost)

• Recurring calendar event CRUD operates on the series, not individual occurrences

License

MIT. The bundled httpd.sys.mjs is from Mozilla and licensed under MPL-2.0.