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:

   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.
   # 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:

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

   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).

Availa

... View full README on GitHub