thunderbird-mcp by PreistlyPython - MCP Server

Thunderbird MCP Server

A Model Context Protocol (MCP) server that provides comprehensive email management tools for Thunderbird. Features 55+ tools for email operations, contact management, bulk campaigns, and smart automation.

Features

📧 Core Email Operations

Email Management: Send, read, search, organize emails
Folder Operations: Create, move, delete folders with safety checks
Contact Management: Thunderbird address book integration
Bulk Operations: Mass email campaigns with templates

🤖 AI-Powered Tools

Smart Email Organization: Automatically categorize inbox emails
Auto-Draft Responses: Generate intelligent email replies
Smart Filters: AI-created email filtering rules
Usage Analytics: Email patterns and productivity metrics

🛡️ Advanced Features

Deliverability Testing: Email bounce detection and spam scoring
OAuth Token Management: Authentication status monitoring
Performance Optimization: Thunderbird analysis and recommendations
Scheduled Delivery: Time-delayed email sending

Quick Start

Prerequisites

Python 3.8+
Thunderbird installed
MCP-compatible client (Claude Desktop, etc.)

Installation

Clone the repository

git clone https://github.com/yourusername/thunderbird-mcp.git
cd thunderbird-mcp

Install dependencies
```
pip install -r requirements.txt
```

Configure environment

Option A: Environment Variables (Recommended)

export EMAIL_HOST="your.imap.server.com"
export EMAIL_USER="your-email@domain.com"
export EMAIL_PASS="your-password"
export THUNDERBIRD_PROFILE_PATH="/path/to/thunderbird/profile"

Option B: Configuration File

cp config/config.example.py config/config.py
# Edit config/config.py with your email settings

Add to Claude Desktop

{
  "mcpServers": {
    "thunderbird": {
      "command": "python",
      "args": ["/path/to/thunderbird-mcp/main.py"],
      "env": {
        "EMAIL_HOST": "your.imap.server.com",
        "EMAIL_USER": "your-email@domain.com", 
        "EMAIL_PASS": "your-password",
        "THUNDERBIRD_PROFILE_PATH": "/path/to/thunderbird/profile"
      }
    }
  }
}

Configuration

Environment Variables

# Email Server Settings
EMAIL_HOST=imap.example.com          # IMAP server
EMAIL_PORT=993                       # IMAP port
EMAIL_SECURE=true                    # Use SSL/TLS
EMAIL_USER=user@example.com          # Email address
EMAIL_PASS=your_password_here        # Email password
SMTP_PORT=465                        # SMTP port
SMTP_SECURE=true                     # SMTP SSL/TLS

# Thunderbird Settings  
THUNDERBIRD_PROFILE_PATH=~/.thunderbird/default-release
THUNDERBIRD_DEFAULT_FOLDER=INBOX

# Server Settings
LOG_LEVEL=INFO
CONNECTION_TIMEOUT=30000
MAX_RETRIES=3

Finding Your Thunderbird Profile

# Linux
~/.thunderbird/
# macOS  
~/Library/Thunderbird/Profiles/
# Windows
%APPDATA%\Thunderbird\Profiles\

Available Tools

Email Operations (14 tools)

list_folders - List email folders
list_emails - List emails with filtering
read_email - Read specific email content
send_email - Send emails with attachments
search_emails - Advanced email search
delete_email - Delete emails
move_email - Move emails between folders
mark_as_read - Mark emails as read
And more...

Contact Management (8 tools)

get_thunderbird_contacts - Retrieve contacts
add_thunderbird_contact - Add new contacts
find_duplicate_contacts - Find duplicates
merge_duplicate_contacts - Merge contacts
tag_contact - Tag/categorize contacts
And more...

Bulk Operations (5 tools)

send_bulk_emails - Mass email campaigns
validate_email_list - Email deliverability checks
create_email_template - Template management
generate_email_template_from_prompt - AI template generation
send_bulk_emails_with_template - Template-based campaigns

Smart Automation (7 tools)

organize_inbox_emails - AI email organization
generate_auto_draft_responses - Auto-reply generation
create_smart_filters - AI filter creation
smart_email_workflow - Complete automation
generate_usage_analytics - Email metrics
optimize_thunderbird_performance - Performance analysis
test_email_deliverability - Deliverability testing

Usage Examples

Send a Simple Email

await send_email(
    to="recipient@example.com",
    subject="Hello from MCP",
    body="This email was sent via Thunderbird MCP!"
)

Bulk Email Campaign

recipients = '[{"email": "user1@example.com", "name": "John"}]'
await send_bulk_emails(
    recipients_data=recipients,
    subject_template="Hello {name}!",
    body_template="Dear {name}, welcome to our service!"
)

Smart Inbox Organization

result = await organize_inbox_emails(
    dry_run=False,  # Set to True for testing
    create_folders=True,
    limit=100
)

Security Features

No Hardcoded Credentials: All sensitive data via environment variables
Safe Operations: Dry-run modes for testing
Input Validation: Comprehensive parameter validation
Error Handling: Graceful failure modes
Logging: Detailed operation logs

Development

Project Structure

thunderbird-mcp/
├── src/
│   ├── mcp_server.py      # Main MCP server with all tools
│   ├── thunderbird_client.py  # Thunderbird integration
│   └── logger.py          # Logging configuration
├── config/
│   └── config.example.py  # Configuration template
├── scripts/
│   └── launch-inspector.sh # Development utilities
├── docs/                  # Documentation
├── requirements.txt       # Python dependencies
└── main.py               # Entry point

Running Tests

python test_simplified_tools.py  # Test core functionality

Troubleshooting

Common Issues

"No module named 'thunderbird_client'"

Ensure you're running from the project root directory
Check Python path includes the src/ directory

"IMAP connection failed"

Verify EMAIL_HOST, EMAIL_PORT settings
Check firewall/network connectivity
Ensure Thunderbird profile path is correct

"Authentication failed"

Verify EMAIL_USER and EMAIL_PASS
Check if 2FA requires app-specific password
Ensure OAuth tokens are valid

Debug Mode

LOG_LEVEL=DEBUG python main.py

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built for the Model Context Protocol (MCP)
Integrates with Thunderbird email client
Designed for Claude Desktop integration