MadLlama25/fastmail-mcp

An **unofficial** Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data.
> **Disclaimer:** This is a community project. It is **not affiliated with, endorsed by, or supported by Fastmail**. "Fastmail" is a trademark of Fastmail Pty Ltd; it is used here only to describe compatibility with their public JMAP/CalDAV/WebDAV APIs. Use at your own risk under the terms of the project license.
Features
Core Email Operations
- List mailboxes and get mailbox statistics
- List, search, and filter emails with advanced criteria
- Get specific emails by ID with full content
- Send emails (text and HTML) with proper draft/sent handling
- Reply to emails with proper threading (In-Reply-To, References headers)
- Create, edit, and send email drafts (with or without threading)
- Email management: mark read/unread, delete, move between folders
Advanced Email Features
- **Attachment Handling**: List, download, and send attachments; save attachments straight to WebDAV cloud storage
- **Privacy-lean metadata tools**: Metadata-only variants of list/search/thread tools (no body content)
- **Threading Support**: Get complete conversation threads
- **Advanced Search**: Multi-criteria filtering (sender, date range, attachments, read status)
- **Bulk Operations**: Process multiple emails simultaneously
- **Statistics & Analytics**: Account summaries and mailbox statistics
Contacts Operations
- List all contacts with full contact information
- Get specific contacts by ID
- Search contacts by name or email
- Create, update, and delete contacts (JMAP ContactCard/set; requires an API token with read-write contacts scope)
Calendar Operations
- List, get, create, update, and delete calendar events (via CalDAV)
- All-day and timed events, participants, recurrence-aware updates
Label vs Move Operations
- **move_email/bulk_move**: Replaces ALL mailboxes for an email (folder behavior)
- **add_labels/remove_labels**: Adds/removes SPECIFIC mailboxes while preserving others (label behavior)
Identity & Account Management
- List available sending identities
- Account summary with comprehensive statistics
Setup
Prerequisites
- Node.js 20+
- A Fastmail account with API access
- Fastmail API token
Installation
1. Clone or download this repository
2. Install dependencies:
3. Build the project:
Configuration
1. Get your Fastmail API token:
- Log in to Fastmail web interface
- Go to Settings → Privacy & Security
- Find "Connected apps & API tokens" section
- Click "Manage API tokens"
- Click "New API token"
- Copy the generated token
2. Set environment variables:
Running the Server
Start the MCP server:
For development with auto-reload:
Run from a clone
> Note: npx github:MadLlama25/fastmail-mcp does **not** work on npm 10 (a known npm
> GitFetcher bug). Use the clone above, or install the packaged
> Desktop Extension.
Install as a Claude Desktop Extension (DXT)
You can install this server as a Desktop Extension for Claude Desktop using the packaged .dxt file.
1. Build and pack:
This produces fastmail-mcp.dxt in the project root.
2. Install into Claude Desktop:
- Open the .dxt file, or drag it into Claude Desktop
- When prompted:
- Fastmail API Token: paste your token (stored encrypted by Claude) — required
- Fastmail Base URL: leave blank to use https://api.fastmail.com (default)
- Download Directory: leave blank for ~/Downloads/fastmail-mcp/
- CalDAV Username / Password / Display Name: optional — required for calendar tools (use an app-specific password; see CalDAV Calendar Support)
- WebDAV URL / Username / Password: optional — required for save_attachment_to_webdav (see WebDAV file storage)
3. Use any of the tools (e.g. get_recent_emails).
Available Tools (52 Total)
**Response shape for list/search tools:** the query tools (list_emails, list_emails_metadata, search_emails, search_emails_metadata, get_recent_emails, advanced_search, advanced_search_metadata, list_contacts, search_contacts) return a {"total", "items"} JSON envelope — total is the server-reported match count, items the returned page. When the server reports no total, a bare array is returned.
**🎯 Most Popular Tools:**
- **check_function_availability**: Check what's available and get setup guidance
- **test_bulk_operations**: Safely test bulk operations with dry-run mode
- **send_email**: Full-featured email sending with proper draft/sent handling
- **advanced_search**: Powerful multi-criteria email filtering