Fastmail MCP Server

An MCP (Model Context Protocol) server for interacting with Fastmail via JMAP. Designed for interactive email cleanup - finding and managing newsletters, receipts, marketing emails, and other accumulated mail.

Features

• List Mailboxes - See all folders and their email counts
• Search Emails - Find emails by sender, recipient (alias), age, read status
• Analyze Senders - See who sends you the most email
• Analyze Aliases - See which of your addresses receive the most mail
• Get Cleanup Candidates - Find newsletters, shipping notifications, marketing emails
• Delete Emails - Move to trash or permanently delete

Setup

1. Create Fastmail API Token

1. Go to Fastmail Settings → Privacy & Security → API Tokens
2. Click "Generate API Token"
3. Name it something like "Claude MCP"
4. Enable these scopes:
   • Email (required) - for reading and managing mail
   • Masked Email (optional) - for seeing your aliases
5. Leave "Read-only access" OFF (we need write access to delete)
6. Click "Generate API token" and copy the token

2. Configure Environment

Create a .env file in this directory:

FASTMAIL_API_TOKEN=fmu1-your-token-here

3. Install Dependencies

cd ~/repos/fastmail-mcp
pip install -e .

Or install dependencies directly:

pip install mcp httpx python-dotenv pydantic

4. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/Users/greg/repos/fastmail-mcp/server.py"]
    }
  }
}

Or if you installed it as a package:

{
  "mcpServers": {
    "fastmail": {
      "command": "fastmail-mcp"
    }
  }
}

5. Test It

Restart Claude Desktop, then try:

• "What mailboxes do I have in Fastmail?"
• "Who sends me the most email?"
• "Find newsletters older than 30 days"
• "Show me emails sent to lowes@802ski.com"

Available Tools

fastmail_get_session_info

Verify your connection and see account details.

fastmail_list_mailboxes

List all folders with email counts.

fastmail_search_emails

Search with filters:

• mailbox_name - Folder to search
• from_address - Sender email or domain
• to_address - Recipient (your alias)
• older_than_days - Age filter
• is_read - Read/unread status
• subject_contains - Subject text search
• limit - Max results (1-100)

fastmail_analyze_senders

Top senders by volume in a mailbox.

fastmail_analyze_aliases

Which of your addresses receive the most mail.

fastmail_get_cleanup_candidates

Find cleanup targets by category:

• newsletters - Newsletter-like emails
• shipping - Shipping/tracking notifications
• marketing - Promotional emails
• old_unread - Old emails you never read
• all - Check all categories

fastmail_delete_emails

Delete emails by ID:

• email_ids - List of IDs to delete
• permanent - True to permanently delete, False (default) to move to Trash

Example Workflows

Weekly Cleanup

1. "What's accumulating in my mail?"
2. "Find newsletters older than 14 days"
3. "Show me shipping notifications older than 30 days"
4. [Review the list]
5. "Delete these emails" [paste IDs]

Analyze a Sender

1. "Who sends me the most email?"
2. "Show me all emails from newsletter@example.com"
3. "Delete all those older than 7 days"

Check an Alias

1. "Show me emails sent to lowes@802ski.com"
2. "Which are shipping notifications vs receipts?"
3. "Delete the shipping ones older than 60 days"

Security Notes

• Your API token is stored in .env and never transmitted except to Fastmail's API
• The token has full email access - treat it like a password
• Add .env to .gitignore (already done if you cloned this repo)

Troubleshooting

"FASTMAIL_API_TOKEN not set"

• Make sure .env file exists in the project directory
• Make sure the token starts with fmu1-

"Authentication failed"

• Token may be expired or revoked
• Generate a new one in Fastmail settings

"Permission denied"

• Check that the Email scope is enabled for your token
• Make sure "Read-only access" is OFF

License

MIT