Fastmail MCP Server (Unofficial)

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:

   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)
   # Only api.fastmail.com and www.fastmailusercontent.com are accepted by default,
   # each with an optional regional prefix (phl.api.fastmail.com,
   # phl-www.fastmailusercontent.com) as returned by JMAP session discovery.
   # 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/).
   # download_attachment savePaths are confined to this directory; set it to the root
   # you want attachments saved under to write there directly in one step.
   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 from a clone

git clone https://github.com/MadLlama25/fastmail-mcp && cd fastmail-mcp
npm install && npm run build
FASTMAIL_API_TOKEN="your_token" node dist/index.js

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:

   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) — 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
• get_recent_emails: Quick access to recent emails from any mailbox

Email Tools

• list_mailboxes: Get all mailboxes in your account. On accounts with many mailboxes the full output can be large — pass properties for a slim view.
  • Parameters: properties (optional array of fields to return), parentId (optional; only children of this mailbox, null for top level)
• get_mailbox_by_name: Look up a mailbox by its full path from the root (e.g. Inbox/Receipts)
  • Parameters: path (required)
• create_mailbox: Create a new mailbox (folder/label)
  • Parameters: name (required), parentId (optional, omit or null for top level)
• list_emails: List emails from a specific mailbox or all mailboxes
  • Parameters: mailboxId (optional), limit (default: 20, max: 100), ascending (optional, oldest first)
• list_emails_metadata: List emails from a mailbox, metadata only (headers, no body content)
  • Parameters: mailboxId (optional), limit (default: 20, max: 100), ascending (optional, oldest first)
• get_email: Get a specific email by ID
  • Parameters: emailId (required)
• get_email_metadata: Get a specific email's metadata only (allowlisted headers, no body)
  • Parameters: emailId (required)
• send_email: Send an email (supports threading via optional inReplyTo and references headers)
  • Parameters: to (required — array or comma-separated string), 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), attachments (optional array — see Email attachments on send)
• 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), attachments (optional array — see Email attachments on send)
• create_draft: Create an email draft (at least one of to/subject/body/attachments required; supports threading headers for reply drafts)
  • Parameters: to (optional array), cc (optional array), bcc (optional array), from (optional), mailboxId (optional), subject (optional), textBody (optional), htmlBody (optional), replyTo (optional array), inReplyTo (optional array), references (optional array), attachments (optional array — see Email attachments on send)
• edit_draft: Edit an existing draft in place — only provided fields change; existing attachments are preserved
  • Parameters: emailId (required), to, cc, bcc, from, subject, textBody, htmlBody, replyTo, attachments (all optional)
• send_draft: Send an existing draft
  • Parameters: emailId (required)
• search_emails: Search emails by content
  • Parameters: query (required), limit (default: 20, max: 100), ascending (optional, oldest first), excludeDrafts (optional, omit draft messages)
  • Drafts are included by default. Set excludeDrafts: true to filter them out server-side.
  • Searches all mailboxes including Trash and Spam. For cleanup/verification flows, exclude the Trash mailbox explicitly (e.g. advanced_search with excludeMailboxIds) rather than trusting a bare search count.
• get_recent_emails: Get the most recent emails (inspired by JMAP-Samples top-ten)
  • Parameters: limit (default: 10, max: 50), mailboxName (optional), ascending (optional, oldest first)
  • When mailboxName is omitted, all mailboxes are searched except Trash and Spam. Pass a mailbox