fastmail-mcp

# Fastmail MCP Server A Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data. ## 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 and save email drafts (with or without threading) - Email management: mark read/unread, delete, move between folders ### Advanced Email Features - **Attachment Handling**: List and download email attachments - **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 ### Calendar Operations - List all calendars and calendar events - Get specific calendar events by ID - Create new calendar events with participants and details ### 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: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ### 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: ```bash export FASTMAIL_API_TOKEN="your_api_token_here" # Optional: customize base URL (defaults to https://api.fastmail.com) # Only api.fastmail.com and www.fastmailusercontent.com are accepted by default. # For self-hosted JMAP servers, also set FASTMAIL_ALLOW_UNSAFE_BASE_URL=true. export FASTMAIL_BASE_URL="https://api.fastmail.com" # Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/) export FASTMAIL_DOWNLOAD_DIR="/path/to/your/downloads" ``` ### Running the Server Start the MCP server: ```bash npm start ``` For development with auto-reload: ```bash npm run dev ``` ### Run via npx (GitHub) Default to `main` branch: ```bash FASTMAIL_API_TOKEN="your_token" FASTMAIL_BASE_URL="https://api.fastmail.com" \ npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp ``` Windows PowerShell: ```powershell $env:FASTMAIL_API_TOKEN="your_token" $env:FASTMAIL_BASE_URL="https://api.fastmail.com" npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp ``` Pin to a tagged release: ```bash FASTMAIL_API_TOKEN="your_token" \ npx --yes github:MadLlama25/fastmail-mcp@v1.9.4 fastmail-mcp ``` ## 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: ```bash npm run build npx @anthropic-ai/dxt 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) - Fastmail Base URL: leave blank to use `https://api.fastmail.com` (default) 3. Use any of the tools (e.g. `get_recent_emails`). ## Available Tools (38 Total) **🎯 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 - **get_recent_emails**: Quick access to recent emails from any mailbox ### Email Tools - **list_mailboxes**: Get all mailboxes in your account - **list_emails**: List emails from a specific mailbox or all mailboxes - Parameters: `mailboxId` (optional), `limit` (default: 20), `ascending` (optional, oldest first) - **get_email**: Get a specific email by ID - Parameters: `emailId` (required) - **send_email**: Send an email (supports threading via optional `inReplyTo` and `references` headers) - Parameters: `to` (required array), `cc` (optional array), `bcc` (optional array), `from` (optional), `mailboxId` (optional), `subject` (required), `textBody` (optional), `htmlBody` (optional), `inReplyTo` (optional array), `references` (optional array), `replyTo` (optional array) - **reply_email**: Reply to an existing email with proper threading headers (automatically builds In-Reply-To and References). Set `send=false` to save as draft instead of sending. - Parameters: `originalEmailId` (required), `to` (optional array, defaults to original sender), `cc` (optional array), `bcc` (optional array), `from` (optional), `textBody` (optional), `htmlBody` (optional), `send` (optional boolean, default: true), `replyTo` (optional array) - **save_draft**: Save an email as a draft without sending (supports threading headers for reply drafts) - Parameters: `to` (required array), `cc` (optional array), `bcc` (optional array), `from` (optional), `subject` (required), `textBody` (optional), `htmlBody` (optional), `inReplyTo` (optional array), `references` (optional array) - **create_draft**: Create a minimal email draft (at least one of to/subject/body required) - Parameters: `to` (optional array), `cc` (optional array), `bcc` (optional array), `from` (optional), `mailboxId` (optional), `subject` (optional), `textBody` (optional), `htmlBody` (optional), `replyTo` (optional array) - **search_emails**: Search emails by content - Parameters: `query` (required), `limit` (default: 20), `ascending` (optional, oldest first) - **get_recent_emails**: Get the most recent emails from a mailbox (inspired by JMAP-Samples top-ten) - Parameters: `limit` (default: 10, max: 50), `mailboxName` (default: 'inbox'), `ascending` (optional, oldest first) - **mark_email_read**: Mark an email as read or unread - Parameters: `emailId` (required), `read` (default: true) - **delete_email**: Delete an email (move to trash) - Parameters: `emailId` (required) - **move_email**: Move an email to a different mailbox (replaces all mailboxes) - Parameters: `emailId` (required), `targetMailboxId` (required) - **add_labels**: Add labels (mailboxes) to an email without removing existing ones - Parameters: `emailId` (required), `mailboxIds` (required array) - **remove_labels**: Remove specific labels (mailboxes) from an email - Parameters: `emailId` (required), `mailboxIds` (required array) ### Advanced Email Features - **get_email_attachments**: Get list of attachments for an email - Parameters: `emailId` (required) - **download_attachment**: Download an email attachment. If savePath is provided, saves the file to disk and returns the file path and size. Otherwise returns a download URL. - Parameters: `emailId` (required), `attachmentId` (required), `savePath` (optional) - **advanced_search**: Advanced email search with multiple criteria - Parameters: `query` (optional), `from` (optional), `to` (optional), `subject` (optional), `hasAttachment` (optional), `isUnread` (optional), `mailboxId` (optional), `after` (optional), `before` (optional), `limit` (default: 50), `ascending` (optional, oldest first) - **get_thread**: Get all emails in a conversation thread - Parameters: `threadId` (required) ### Email Statistics & Analytics - **get_mailbox_stats**: Get statistics for a mailbox (unread count, total emails, etc.) - Parameters: `mailboxId` (optional, defaults to all mailboxes) - **get_account_summary**: Get overall account summary with statistics ### Bulk Operations - **bulk_mark_read**: Mark multiple emails as read/unread - Parameters: `emailIds` (required array), `read` (default: true) - **bulk_move**: Move multiple emails to a mailbox - Parameters: `emailIds` (required array), `targetMailboxId` (required) - **bulk_delete**: Delete multiple emails (move to trash) - Parameters: `emailIds` (required array) - **bulk_add_labels**: Add labels to multiple emails simultaneously - Parameters: `emailIds` (required array), `mailboxIds` (required array) - **bulk_remove_labels**: Remove labels from multiple emails simultaneously - Parameters: `emailIds` (required array), `mailboxIds` (required array) ### Contact Tools - **list_contacts**: List all contacts - Parameters: `limit` (default: 50) - **get_contact**: Get a specific contact by ID - Parameters: `contactId` (required) - **search_contacts**: Search contacts by name or email - Parameters: `query` (required), `limit` (default: 20) ### Calendar Tools - **list_calendars**: List all calendars - **list_calendar_events**: List calendar events - Parameters: `calendarId` (optional), `limit` (default: 50) - **get_calendar_event**: Get a specific calendar event by ID - Parameters: `eventId` (required) - **create_calendar_event**: Create a new calendar event - Parameters: `calendarId` (required), `title` (required), `description` (optional), `start` (required, ISO 8601), `end` (required, ISO 8601), `location` (optional), `participants` (optional array) ### Identity & Testing Tools - **list_identities**: List sending identities (email addresses that can be used for sending) - **check_function_availability**: Check which functions are available based on account permissions (includes setup guidance) - **test_bulk_operations**: Safely test bulk operations with dry-run mode - Parameters: `dryRun` (default: true), `limit` (default: 3) ## API Information This server uses the JMAP (JSON Meta Application Protocol) API provided by Fastmail. JMAP is a modern, efficient alternative to IMAP for email access. ### Inspired by Fastmail JMAP-Samples Many features in this MCP server are inspired by the official [Fastmail JMAP-Samples](https://github.com/fastmail/JMAP-Samples) repository, including: - Recent emails retrieval (based on top-ten example) - Email management operations - Efficient chained JMAP method calls ### Authentication The server uses bearer token authentication with Fastmail's API. API tokens provide secure access without exposing your main account password. ### Rate Limits Fastmail applies rate limits to API requests. The server handles standard rate limiting, but excessive requests may be throttled. ## CalDAV Calendar Support Fastmail does not currently expose calendar access via JMAP API tokens — the `urn:ietf:params:jmap:calendars` scope is not available because the JMAP Calendars specification is still an IETF Internet-Draft ([draft-ietf-jmap-calendars](https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/)). Fastmail has stated they will add JMAP calendar support once the spec becomes an RFC, but there is no public timeline. However, Fastmail fully supports **CalDAV** for calendar access via `caldav.fastmail.com`. This server automatically falls back to CalDAV when JMAP calendar access is unavailable. ### Setup 1. Create an app-specific password on Fastmail: - Go to **Settings → Privacy & Security → Manage app passwords** - Create a new app password (you can name it "CalDAV MCP" or similar) 2. Set the following environment variables: ```bash export FASTMAIL_CALDAV_USERNAME="your-email@fastmail.com" export FASTMAIL_CALDAV_PASSWORD="your-app-specific-password" ``` When these variables are set, the calendar tools (`list_calendars`, `list_calendar_events`, `get_calendar_event`, `create_calendar_event`) will automatically fall back to CalDAV if JMAP calendars are not available. When these variables are not set, the server behaves exactly as before (JMAP only). ## Development ### Project Structure ``` src/ ├── index.ts # Main MCP server implementation ├── auth.ts # Authentication handling ├── jmap-client.ts # JMAP client wrapper ├── contacts-calendar.ts # Contacts and calendar extensions └── caldav-client.ts # CalDAV calendar client (fallback) ``` ### Building ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ## License MIT ## Contributing Contributions are welcome! Please ensure that: 1. Code follows the existing style 2. All functions are properly typed 3. Error handling is implemented 4. Documentation is updated for new features ## Troubleshooting ### Common Issues 1. **Authentication Errors**: Ensure your API token is valid and has the necessary permissions 2. **Missing Dependencies**: Run `npm install` to ensure all dependencies are installed 3. **Build Errors**: Check that TypeScript compilation completes without errors using `npm run build` 4. **Calendar/Contacts "Forbidden" Errors**: Use `check_function_availability` to see setup guidance ### Email Tools Failing with Serialization Errors? If `get_email`, `list_emails`, `search_emails`, or `advanced_search` fail with "content serialization" or "Cannot read properties of undefined" errors, upgrade to v1.7.1+. This was caused by incomplete JMAP response validation that surfaced after the MCP SDK v1.x upgrade added stricter result checking. ### Calendar/Contacts Not Working? If calendar and contacts functions return "Forbidden" errors, this is likely due to: 1. **Account Plan**: Calendar/contacts API may require business/professional Fastmail plans 2. **API Token Scope**: Your API token may need calendar/contacts permissions enabled 3. **Feature Enablement**: These features may need explicit activation in your account **Solution**: Run `check_function_availability` for step-by-step setup guidance. ### Testing Your Setup Use the built-in testing tools: - **check_function_availability**: See what's available and get setup help - **test_bulk_operations**: Safely test bulk operations without making changes For more detailed error information, check the console output when running the server. ## Privacy & Security - API tokens are stored encrypted by Claude Desktop when installed via the DXT and are never logged by this server. - The server avoids logging raw errors and sensitive data (tokens, email addresses, identities, attachment names/blobIds) in error messages. - Tool responses may include your email metadata/content by design (e.g., listing emails) but internal identifiers and credentials are not disclosed beyond what Fastmail returns for the requested data. - If you encounter errors, messages are sanitized and summarized to prevent leaking personal information.