thunderbird-cli-mcp

thunderbird-cli MCP Server

MCP server that gives Claude Desktop full access to your email through Mozilla Thunderbird.

Read, search, compose, reply, and manage 22+ email accounts and 250K+ messages from any MCP-compatible client. All credentials stay in Thunderbird — nothing leaves your machine.

Part of the thunderbird-cli project.

What it does

Exposes 12 email management tools to Claude Desktop:

Tool	Description
email_stats	Account/folder overview, unread counts, totals
email_search	Cross-account search (15 filter options, relative dates)
email_list	List folder contents with sort/pagination
email_read	Read message (5 modes: default, headers, full, raw, check-download)
email_thread	Get full conversation thread
email_compose	Send/draft new email (default: draft, never auto-sends)
email_reply	Reply to message (default: draft)
email_forward	Forward to new recipient (default: draft)
email_mark	Read/flagged/junk flags (batch supported)
email_archive	Archive, move, or delete messages
email_attachments	List + download attachments (base64)
email_folders	List folders, get info, trigger sync

Safe defaults: compose/reply/forward all default to draft mode. Claude must explicitly pass mode: "send" to actually send anything. Permanent delete requires confirm: true.

Architecture

Claude Desktop ──stdio──> tb-mcp ──HTTP──> bridge daemon ──WS──> Thunderbird Extension
                                                                      ↓
                                                            All your email accounts

The MCP server is stateless. It calls the bridge daemon which forwards to the Thunderbird WebExtension. Your email accounts stay configured in Thunderbird where they always were.

Prerequisites

You need three things running on your machine:

• Mozilla Thunderbird 128+ with your email accounts configured
• The thunderbird-cli bridge daemon running on 127.0.0.1:7700
• The thunderbird-cli WebExtension loaded in Thunderbird

See the main repo setup guide for installing the bridge and extension.

Installation

Option A: npx (recommended, no install)

Add to your Claude Desktop config (no installation step needed — npx fetches it on demand):

{
  "mcpServers": {
    "thunderbird": {
      "command": "npx",
      "args": ["-y", "thunderbird-cli-mcp"]
    }
  }
}

Option B: Global install

npm install -g thunderbird-cli-mcp

Then in Claude Desktop config:

{
  "mcpServers": {
    "thunderbird": {
      "command": "tb-mcp"
    }
  }
}

Option C: From source

git clone https://github.com/vitalio-sh/thunderbird-cli
cd thunderbird-cli
npm install

Then in Claude Desktop config:

{
  "mcpServers": {
    "thunderbird": {
      "command": "node",
      "args": ["/absolute/path/to/thunderbird-cli/mcp/src/server.js"]
    }
  }
}

Claude Desktop Config Location

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

After editing, restart Claude Desktop. You should see "thunderbird" in the MCP servers list when you click the tool icon.

Configuration

The MCP server reads these environment variables (set in your Claude Desktop config under env):

Variable	Default	Purpose
TB_BRIDGE_HOST	127.0.0.1	Bridge daemon host
TB_BRIDGE_PORT	7700	Bridge daemon HTTP port
TB_AUTH_TOKEN	(none)	Optional auth token

Example with custom bridge host:

{
  "mcpServers": {
    "thunderbird": {
      "command": "npx",
      "args": ["-y", "thunderbird-cli-mcp"],
      "env": {
        "TB_BRIDGE_HOST": "127.0.0.1",
        "TB_BRIDGE_PORT": "7700"
      }
    }
  }
}

Example prompts

Once configured, try these in Claude Desktop:

"How many unread emails do I have across all accounts?"

"Search for invoices from AWS in the last 30 days"

"Show me the thread about the GMI Cloud SCALE program"

"Reply to message ID 118 saying I'll be there Monday — save as draft so I can review"

"List all attachments on message 245 and download the PDF"

"Mark all messages from [e-mail] in my inbox as read"

Safety

• Compose/reply/forward default to draft mode. Claude cannot send emails without explicitly requesting mode: "send".
• Permanent delete is gated behind confirm: true.
• Search excludes junk/spam by default to prevent prompt injection from adversarial emails.
• All traffic stays on localhost. Bridge listens on 127.0.0.1 only.
• No credentials are exposed. Thunderbird handles all IMAP/SMTP — your passwords never leave its config.

See SECURITY.md for the full threat model and prompt-injection defenses.

Troubleshooting

"Bridge unreachable" / connection errors

• Is the bridge daemon running on 127.0.0.1:7700? Test: curl http://127.0.0.1:7700/bridge/status
• Is Thunderbird running with the extension loaded?
• Check Thunderbird's add-on debugging console for WebSocket errors

Tools don't appear in Claude Desktop

• Did you restart Claude Desktop after editing the config?
• Check the Claude Desktop logs (View → Developer → Open Logs)
• Verify the JSON config is valid

"Request timed out" on send

• SMTP send can take 30-60s on first connection
• The MCP server uses a 30s default — for sends, use the CLI directly with --timeout 60000

Development

git clone https://github.com/vitalio-sh/thunderbird-cli
cd thunderbird-cli
npm install
npm run test:mcp    # 34 integration tests against mock bridge

License

MIT — see LICENSE