Thunderbird MCP Server v0.2.0

Centralizes Thunderbird email operations as MCP tools: read, send, draft, search, attachments.

Status

Related MCP server: thunderbird-cli

Tools

Configuration

Environment variables:

• THUNDERBIRD_PROFILE_DIR — Thunderbird profile directory (default: ~/.thunderbird)

• THUNDERBIRD_MAIL_DIR — Local mail data directory (default: ~/Downloads/thunderbird.tmp)

• THUNDERBIRD_SEND_COMMAND — Command to invoke Thunderbird (default: thunderbird)

• THUNDERBIRD_DEFAULT_ACCOUNT — Default account identifier (optional)

• THUNDERBIRD_DRAFT_FOLDER — Drafts folder name (default: Drafts)

Installation

Due to PEP 668 restrictions, use PYTHONPATH approach:

export PYTHONPATH=src
python3 -m thunderbird_mcp_server

Or use the provided wrapper:

bash run.sh

Development:

.venv/bin/pip install -e ".[dev]"

Running

bash run.sh
# or directly with PYTHONPATH:
PYTHONPATH=src python3 -m thunderbird_mcp_server

Testing

PYTHONPATH=src .venv/bin/pytest tests/ -v

Test coverage:

• test_list_folders — discovers mbox folders from temp mail dir

• test_read_messages — parses mbox with verified subject/body extraction

• test_search_messages — keyword search across folders

• test_list_folders_uses_unique_relative_names — multi-account path dedup

• test_modified_utf7_folder_name_decoding — IMAP modified UTF-7 decoding (e.g. Chinese folder names)

Integration with opencode

Registered in .opencode/opencode.json:

{
  "mcp": {
    "thunderbird-mcp-server": {
      "type": "local",
      "command": ["bash", "/home/gw/opt/thunderbird-mcp-server/run.sh"],
      "enabled": true,
      "environment": {
        "THUNDERBIRD_PROFILE_DIR": "/home/gw/snap/thunderbird/common/.thunderbird/34p30y9x.default",
        "THUNDERBIRD_MAIL_DIR": "/home/gw/snap/thunderbird/common/.thunderbird/34p30y9x.default/ImapMail",
        "THUNDERBIRD_SEND_COMMAND": "/snap/bin/thunderbird"
      }
    }
  }
}

Agent integration: communication-drafter is the sole authorized agent, granted read/search/draft tools only. tb_send_message is forbidden at the static check level (scripts/check_agent_tool_budget.py). Sending remains a manual user action.

Architecture

• config.py — ThunderbirdConfig dataclass, reads from env vars

• client.py — ThunderbirdClient: reads mbox folders, parses messages, sends via CLI

• server.py — MCP Server with 6 tool definitions and stdio transport

• tools/ — Shared tool parameter schemas

Limitations

• Large mbox timeout: Folders with thousands of messages (e.g. INBOX) may exceed MCP timeouts during read/search. Mitigation: use limit and offset for pagination, or target smaller subfolders.

• Local mbox dependency: Read operations require Thunderbird to have downloaded mail locally (offline storage enabled). Folders with only .msf indexes return placeholder messages.

• Send is interactive: tb_send_message opens the Thunderbird compose window; it is not fully automated. This tool is explicitly denied to all agents — sending is a manual user action.

• MSF-only folders: Return [MSF index only — no message data] placeholder.

• PEP 668: pip install -e . is blocked; use PYTHONPATH=src approach.

• tb_send_message denied: Static check in scripts/check_agent_tool_budget.py prevents any agent from being granted this tool.