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 18+
• A Fastmail account with API access
• Fastmail API token

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install
   

3. Build the project:

   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:

   export FASTMAIL_API_TOKEN="your_api_token_here"
   # Optional: customize base URL (defaults to https://api.fastmail.com)
   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:

npm start

For development with auto-reload:

npm run dev

Run via npx (GitHub)

Default to main branch:

FASTMAIL_API_TOKEN="your_token" FASTMAIL_BASE_URL="https://api.fastmail.com" \
  npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp

Windows 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:

FASTMAIL_API_TOKEN="your_token" \
  npx --yes github:MadLlama25/fastmail-mcp@v1.9.1 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:

   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