Thunderbird MCP Server v0.2.0

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

Status

Aspect	State
Core development	Complete
Unit tests	5/5 PASS
Deployment	Active (opencode MCP)
Agent integration	communication-drafter (draft-only)

Tools

Tool	Description	Agent access
tb_list_folders	List available Thunderbird mail folders	✅ read
tb_read_messages	Read messages from a folder with pagination	✅ read
tb_search_messages	Search messages by keyword	✅ read
tb_download_attachments	Download attachments from a message	✅ read
tb_draft_message	Create a draft email in Thunderbird	✅ write
tb_send_message	Send email via Thunderbird compose command	❌ forbidden

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.