Fastmail

Interact with Fastmail email, contacts, and calendar data using the Fastmail API.

GitHub
122

Documentation

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/).
# 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 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/[email protected] 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), excludeDrafts (optional, omit draft messages)
    • Drafts are included by default. Set excludeDrafts: true to filter them out server-side.
  • 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 name (e.g. 'inbox', 'sent') to scope to one folder.
  • 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)
    • savePath may be absolute or relative. Relative paths (including a bare filename) resolve against the download directory, so an attachment lands there in one step. Absolute paths must fall within that directory; traversal or symlink escape outside it is rejected. To save directly into your own location, set FASTMAIL_DOWNLOAD_DIR to that root ā€” confinement stays on, scoped to the directory you choose.
  • 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), includeDrafts (optional, include in-progress drafts)
    • Draft messages are excluded by default (an in-progress reply is noise when reading a conversation). Set includeDrafts: true to include them. Drafts are identified by the $draft keyword, so the asymmetry with search_emails (which includes drafts by default) is deliberate: a search should still find everything you've written.

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 (core fields only ā€” no participants for token efficiency)
    • Parameters: calendarId (optional), startDate (optional, ISO 8601), endDate (optional, ISO 8601), limit (default: 50)
  • get_calendar_event: Get a specific calendar event by ID. Returns organizer and participants when available.
    • Parameters: eventId (required)
  • create_calendar_event: Create a new calendar event. Supports date-only (e.g. 2026-04-01) for all-day events. DTEND is exclusive per RFC 5545 ā€” a one-day event on April 1 needs end: "2026-04-02".
    • Parameters: calendarId (required), title (required), description (optional), start (required, ISO 8601 or date-only), end (required, ISO 8601 or date-only), location (optional), participants (optional array of {email, name?})
  • update_calendar_event: Patch an existing calendar event. Preserves all existing data (attendees, reminders, recurrence rules, etc.) not being changed. Omit a field to leave it unchanged; passing an empty or whitespace-only string for title, description, or location is rejected (it won't silently blank the property). To delete description or location, list them in clearFields. Floating times (no Z/offset) preserve the original timezone. WARNING: providing participants replaces ALL existing attendee data; participants: [] removes all attendees (and the now-orphaned ORGANIZER).
    • Parameters: eventId (required), title, description, start, end, location, participants (array of {email, name?}), clearFields (array of "description"/"location" to delete), confirmRecurring (boolean)
  • delete_calendar_event: Delete a calendar event
    • Parameters: eventId (required)

Calendar known limitations

  • Recurring events: Only "all events" modification is supported (master VEVENT). "This event only" or "this and future events" are not supported. Changing start/end on recurring events with exception overrides requires confirmRecurring: true ā€” orphaned exceptions are pruned to prevent server errors.
  • Attendee parameters: RSVP, ROLE, CUTYPE and other attendee parameters are parsed on read but not settable on create/update ā€” only email and name are accepted.

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). Calendar tools run over CalDAV, so calendar is reported available when CalDAV credentials are configured, regardless of the JMAP calendar capability.
  • 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 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). 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. All calendar tools use CalDAV directly.

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:

    export FASTMAIL_CALDAV_USERNAME="[email protected]"
export FASTMAIL_CALDAV_PASSWORD="your-app-specific-password"
# Optional: display name for ORGANIZER when creating events with participants
export FASTMAIL_CALDAV_DISPLAY_NAME="Your Name"

When these variables are set, all calendar tools are available. When they are not set, calendar tools will return an error with setup instructions.

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

npm run build

Development Mode

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.