Proton Mail Sifting#

A Python CLI tool and MCP server for analyzing and managing ProtonMail inboxes via Proton Bridge.

Overview#

This tool helps you regain control of an overflowing inbox by:

• Analyzing email patterns and sender statistics
• Identifying newsletters, notifications, and transactional emails
• Extracting unsubscribe links for easy cleanup
• Bulk marking notifications as read
• Providing AI-accessible tools via MCP server

Architecture#

Components#

1. CLI Tool (Typer) - Direct command-line interface for manual use
2. Email Client - IMAP connection handler for Proton Bridge
3. Analyzer - Email classification and pattern detection
4. MCP Server - Exposes functionality as tools for AI assistants

Technology Stack#

• Python 3.11+
• Typer - CLI framework
• imapclient - High-level IMAP library
• email (stdlib) - Email parsing
• fastmcp - MCP server implementation
• rich - Beautiful terminal output
• uv - Fast Python package manager

Features#

Phase 1: Read-Only Analysis (Safe)#

CLI Commands#

# Connect and analyze entire inbox
proton-sift analyze

# Group emails by sender with statistics
proton-sift group-by-sender --limit 50

# Find all newsletters
proton-sift find-newsletters

# Identify notification emails
proton-sift find-notifications

# Extract unsubscribe links
proton-sift list-unsubscribe --export unsubscribe.csv

# Show inbox statistics
proton-sift stats

MCP Tools#

• analyze_inbox() - Returns comprehensive inbox analysis
• group_by_sender(limit: int) - Sender statistics with email counts
• find_newsletters() - List all detected newsletters with unsubscribe info
• find_notifications() - Identify automated notifications
• get_inbox_stats() - Quick statistics overview

Phase 2: Write Operations (Requires Confirmation)#

CLI Commands#

# Mark all notifications as read
proton-sift mark-read --type notifications --dry-run
proton-sift mark-read --type notifications --confirm

# Mark emails from specific sender as read
proton-sift mark-read --sender "noreply@example.com" --confirm

# Move newsletters to folder
proton-sift move --type newsletters --folder "Newsletters" --confirm

# Archive old notifications
proton-sift archive --type notifications --older-than 30d --confirm

MCP Tools#

• mark_notifications_read(dry_run: bool) - Bulk mark notifications
• mark_sender_read(sender: str, dry_run: bool) - Mark specific sender
• move_to_folder(email_ids: list, folder: str) - Organize emails

Phase 3: Advanced Features (Future)#

• Smart filters based on analysis
• Scheduled cleanup automation
• Duplicate detection
• Attachment analysis
• Thread consolidation
• Export to various formats (JSON, CSV, HTML report)

Email Classification#

Detection Heuristics#

Newsletters:

• List-Unsubscribe header present
• Common newsletter keywords in subject/sender
• High HTML-to-text ratio
• Marketing-related headers

Notifications:

• Auto-Submitted: auto-generated header
• Precedence: bulk header
• Sender patterns: noreply@, no-reply@, notifications@
• Subject patterns: "Your order", "Password reset", "New comment"

Transactional:

• Order confirmations
• Receipts and invoices
• Account security alerts
• Shipping notifications

Personal:

• Everything else (default category)

Configuration#

Connection Setup#

# Interactive setup (stores encrypted credentials)
proton-sift configure

# Or use environment variables
export PROTON_IMAP_HOST=127.0.0.1
export PROTON_IMAP_PORT=1143
export PROTON_IMAP_USER=your-email@proton.me
export PROTON_IMAP_PASS=your-bridge-password

Configuration File#

~/.config/proton-sift/config.toml:

[connection]
host = "127.0.0.1"
port = 1143
use_ssl = true

[analysis]
# Senders with more than this count are flagged as high-volume
high_volume_threshold = 10

# Age in days to consider emails "old"
old_email_days = 90

[classification]
# Custom patterns for newsletter detection
newsletter_patterns = ["newsletter", "digest", "weekly roundup"]

# Senders to always treat as notifications
notification_senders = ["noreply@github.com", "notifications@slack.com"]

[safety]
# Require confirmation for operations affecting more than this many emails
bulk_operation_threshold = 50

# Never mark these senders as read automatically
protected_senders = ["boss@company.com", "important@example.com"]

Installation#

As a CLI Tool#

# Using uv (recommended)
uv pip install proton-mail-sifting

# Or with pip
pip install proton-mail-sifting

# Run CLI
proton-sift --help

As an MCP Server#

Add to your MCP settings (e.g., Claude Desktop config):

{
  "mcpServers": {
    "proton-mail-sifting": {
      "command": "uvx",
      "args": ["proton-mail-sifting-mcp"]
    }
  }
}

Or with local installation:

{
  "mcpServers": {
    "proton-mail-sifting": {
      "command": "python",
      "args": ["-m", "proton_mail_sifting.mcp_server"]
    }
  }
}

Development Setup#

# Clone repository
git clone <repo-url>
cd proton-mail-sifting

# Install with uv
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Run CLI locally
python -m proton_mail_sifting.cli --help

# Run MCP server locally
python -m proton_mail_sifting.mcp_server

Safety Features#

1. Dry-run mode - Preview all write operations before executing
2. Confirmation prompts - Require explicit confirmation for bulk operations
3. Protected senders - Whitelist important senders from automation
4. Operation limits - Threshold warnings for large batch operations
5. Audit logging - Track all operations performed
6. Read-only by default - Analysis commands never modify emails

Privacy & Security#

• Credentials stored locally - Encrypted using system keyring
• No external API calls - All processing happens locally via IMAP
• No data collection - Your emails never leave your machine
• Open source - Audit the code yourself

Prerequisites#

1. Proton Bridge installed and running

   • Download from: https://proton.me/mail/bridge
   • Configure your account in Bridge
   • Note the IMAP credentials Bridge provides

2. Python 3.11 or higher

Example Workflow#

# 1. Configure connection
proton-sift configure

# 2. Get overview
proton-sift stats

# 3. Analyze inbox
proton-sift analyze

# 4. Find newsletters
proton-sift find-newsletters

# 5. Export unsubscribe links
proton-sift list-unsubscribe --export unsubscribe.csv

# 6. Preview marking notifications as read
proton-sift mark-read --type notifications --dry-run

# 7. Confirm and execute
proton-sift mark-read --type notifications --confirm

# 8. Group by sender to find high-volume senders
proton-sift group-by-sender --limit 20

MCP Usage Example#

Once configured as an MCP server, you can ask your AI assistant:

"Analyze my ProtonMail inbox and show me the top 10 senders"

"Find all newsletters in my inbox and extract unsubscribe links"

"Mark all notification emails as read"

The AI will use the MCP tools to interact with your inbox safely.

Project Structure#

proton-mail-sifting/
├── src/
│   └── proton_mail_sifting/
│       ├── __init__.py
│       ├── cli.py              # Typer CLI commands
│       ├── email_client.py     # IMAP connection & operations
│       ├── analyzer.py         # Email classification logic
│       ├── models.py           # Data models (Email, Sender, Stats)
│       ├── config.py           # Configuration management
│       ├── mcp_server.py       # MCP server implementation
│       └── utils.py            # Helper functions
├── tests/
│   ├── test_analyzer.py
│   ├── test_email_client.py
│   └── test_cli.py
├── pyproject.toml
├── README.md
└── LICENSE

Roadmap#

• Phase 1: Read-only analysis and reporting
• Phase 2: Write operations with safety checks
• Phase 3: Advanced features (filters, automation, exports)
• Web UI for visual inbox exploration
• Support for other email providers (Gmail, Outlook via IMAP)
• Machine learning for better classification
• Email thread analysis

Contributing#

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

License#

MIT License - See LICENSE file for details

Questions for Review#

1. Scope: Is Phase 1 (read-only) the right starting point?
2. Classification: Are the email type heuristics comprehensive enough?
3. Safety: Are the safety features sufficient for your comfort level?
4. MCP Tools: Should we expose more granular tools or keep them high-level?
5. Configuration: Is TOML config preferred, or would you prefer JSON/YAML?
6. Credentials: Use system keyring, or plain environment variables?
7. Output Format: Rich terminal output for CLI, JSON for MCP - correct?
8. Folder Operations: Should Phase 2 include creating/managing IMAP folders?
9. Batch Size: Should we limit operations to batches (e.g., 100 emails at a time)?
10. Undo Feature: Should we implement an undo mechanism for write operations?