Skip to main content
Glama
pyfastmail-mcp
by pjosols

pyfastmail-mcp

An MCP server that gives AI assistants full access to your Fastmail account — email, contacts, calendars, and file storage.

⚠️ This server can send email, delete messages, and modify contacts/calendars on your behalf. AI assistants may act on content from untrusted sources (emails, web pages, files) which could contain prompt injection attacks. Review tool calls before approving them, especially actions that send email or delete data.

Features

Domain

Protocol

Tools

Mail

JMAP

Send, reply, forward, search, read, pin, archive, keywords, masked email, attachments, threads, import/export, identities

Contacts

JMAP

List address books, CRUD contacts, query

Calendar

CalDAV

List calendars, CRUD events (optional — requires app password)

Files

WebDAV

List, upload, download, move, delete, create folders (optional — requires app password)

Related MCP server: Fastmail MCP Server

Installation

pip install pyfastmail-mcp

Or run directly with uvx:

uvx pyfastmail-mcp

Configuration

1. Get Fastmail Credentials

You need an API token from Fastmail. An app password is optional (only needed for calendar and file storage).

If you only set the API token, the server starts with mail and contacts tools. Calendar and file tools are registered only when the app password is also provided.

2. Set Environment Variables

export FASTMAIL_API_TOKEN="fmu1-..."
export FASTMAIL_APP_PASSWORD="your-app-password"
export FASTMAIL_EMAIL="you@fastmail.com"

3. Add to Your MCP Client

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "fastmail": {
      "command": "uvx",
      "args": ["pyfastmail-mcp"],
      "env": {
        "FASTMAIL_API_TOKEN": "fmu1-...",
        "FASTMAIL_APP_PASSWORD": "your-app-password",
        "FASTMAIL_EMAIL": "you@fastmail.com"
      }
    }
  }
}

For Kiro CLI, add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "fastmail": {
      "command": "uvx",
      "args": ["pyfastmail-mcp"],
      "env": {
        "FASTMAIL_API_TOKEN": "${FASTMAIL_API_TOKEN}",
        "FASTMAIL_EMAIL": "${FASTMAIL_EMAIL}",
        "FASTMAIL_APP_PASSWORD": "${FASTMAIL_APP_PASSWORD}"
      }
    }
  }
}

Tools

Mail (mail_*)

Tool

Description

health_check

Verify connection and auth

mail_list_mailboxes

List all mailboxes (folders/labels)

mail_create_mailbox

Create a mailbox

mail_rename_mailbox

Rename a mailbox

mail_delete_mailbox

Delete a mailbox

mail_get_email

Get email by ID (with optional headers)

mail_get_recent_emails

Get recent emails

mail_search_emails

Search by query

mail_search_snippets

Highlighted search result snippets

mail_get_email_thread

Get full thread

mail_mark_email_read

Mark read/unread

mail_pin_email

Pin/unpin (flag/star)

mail_move_email

Move to mailbox

mail_delete_email

Move to trash or permanently delete

mail_archive_email

Archive

mail_manage_email_labels

Add/remove keywords

mail_export_email

Download raw .eml file

mail_import_email

Import .eml into mail store

mail_parse_email

Parse a blob as email without importing

mail_list_identities

List send-as identities

mail_set_identity

Create/update/delete identities

mail_send_email

Send new email

mail_reply_to_email

Reply to email

mail_forward_email

Forward email

mail_list_masked_emails

List masked emails

mail_create_masked_email

Create masked email

mail_update_masked_email

Update masked email state, domain, description, or URL

mail_download_attachment

Download attachment

mail_upload_attachment

Upload blob for sending

Contacts (contacts_*)

Tool

Description

contacts_list_address_books

List address books

contacts_list

List contacts (query+get combo)

contacts_get_contact

Get contact(s) by ID

contacts_query_contacts

Query contacts with filters and sorting

contacts_create_contact

Create contact

contacts_update_contact

Update contact fields

contacts_delete_contact

Delete contact(s)

Calendar (calendar_*)

Tool

Description

calendar_list_calendars

List calendars

calendar_list_events

List events

calendar_get_event

Get event details

calendar_create_event

Create event

calendar_update_event

Update event

calendar_delete_event

Delete event

Files (files_*)

Tool

Description

files_list

List files/folders

files_get

Download file

files_upload

Upload file

files_create_folder

Create folder

files_move

Move/rename file

files_delete

Delete file/folder

Development

git clone https://github.com/pjosols/pyfastmail-mcp.git
cd pyfastmail-mcp
uv sync --group dev
uv run pytest

License

MIT

Available Tools

48 tools
calendar_create_eventA

Create a new event in a CalDAV calendar.

Args: calendar_href: The href of the calendar (from calendar_list_calendars). title: Event title/summary. start: Start datetime as ISO string (YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD for all-day). end: End datetime as ISO string. location: Optional location string. description: Optional description. all_day: If True, treat start/end as dates (not datetimes).

Inputs: calendar_href (required), title (required), start (required), end (required), +3 more. Returns: result

calendar_delete_eventA

Delete a CalDAV event by its href.

Args: href: The href of the .ics resource (from calendar_list_events).

Inputs: href (required). Returns: result

calendar_get_eventA

Get full details of a single CalDAV event by its href.

Args: href: The href/URL path of the .ics resource (as returned by calendar_list_events).

Inputs: href (required). Returns: result

calendar_list_calendarsA

List all CalDAV calendars for the authenticated Fastmail account.

Inputs: no named parameters. Returns: result

calendar_list_eventsA

List events in a CalDAV calendar within a date range.

Args: calendar_href: The href of the calendar (from calendar_list_calendars). start_date: ISO date string (YYYY-MM-DD). Defaults to today. end_date: ISO date string (YYYY-MM-DD). Defaults to 7 days from start.

Inputs: calendar_href (required), start_date, end_date. Returns: result

calendar_update_eventA

Update fields on an existing CalDAV event.

Args: href: The href of the .ics resource (from calendar_list_events). title: New summary/title (omit to keep existing). start: New start datetime ISO string (omit to keep existing). end: New end datetime ISO string (omit to keep existing). location: New location (omit to keep existing). description: New description (omit to keep existing).

Inputs: href (required), title, start, end, +2 more. Returns: result

contacts_create_contactC

Create a new contact card.

Args: name: Full display name of the contact. emails: List of email addresses. phones: List of phone numbers. org: Organization / company name. notes: Free-text notes. address_book_ids: Address book IDs to add the contact to.

Inputs: name, emails, phones, org, +2 more. Returns: result

contacts_delete_contactB

Delete one or more contacts by ID.

Args: contact_ids: List of ContactCard IDs to delete.

Inputs: contact_ids (required). Returns: result

contacts_get_contactA

Fetch full contact card(s) by ID.

Returns id, addressBookIds, name, emails, phones, addresses, organizations, and notes.

Args: ids: One or more ContactCard IDs to fetch.

Inputs: ids (required). Returns: result

contacts_listA

List contacts, optionally filtered by address book or text search.

Uses a single round trip (ContactCard/query + ContactCard/get).

Args: address_book_id: Restrict to contacts in this address book. text: Full-text search across name, email, phone, etc. limit: Maximum number of contacts to return.

Inputs: address_book_id, text, limit. Returns: result

contacts_list_address_booksA

List all address books with id, name, description, sortOrder, isDefault, and isSubscribed.

Inputs: no named parameters. Returns: result

contacts_query_contactsB

Query contacts with optional filters and sorting.

Args: address_book_id: Filter to contacts in this address book. text: Full-text search across name, email, phone, etc. kind: Filter by kind (e.g. "individual", "org", "group"). limit: Maximum number of results to return. sort_by: Sort field — one of "name/given", "name/surname", "created", "updated".

Inputs: address_book_id, text, kind, limit, +1 more. Returns: result

contacts_update_contactB

Update an existing contact card via JSON patch.

Only the fields you provide will be changed; omitted fields are left as-is.

Args: contact_id: ID of the ContactCard to update. name: New full display name. emails: Replace all email addresses with this list. phones: Replace all phone numbers with this list. org: Replace organization name. notes: Replace notes. address_book_ids: Replace address book membership.

Inputs: contact_id (required), name, emails, phones, +3 more. Returns: result

files_create_folderB

Create a folder on Fastmail Files (WebDAV).

Args: path: Path of the new folder (e.g. "/Documents/NewFolder").

Inputs: path (required). Returns: result

files_deleteB

Delete a file or folder on Fastmail Files (WebDAV).

Args: path: Path to delete (e.g. "/Documents/old.txt").

Inputs: path (required). Returns: result

files_getA

Download a file from Fastmail Files (WebDAV), returned as base64.

Args: path: Path to the file (e.g. "/Documents/report.pdf").

Inputs: path (required). Returns: result

files_listA

List files and folders at a WebDAV path on Fastmail Files.

Args: path: Path to list (default: root "/"). depth: "0" for the item itself only, "1" for immediate children (default).

Inputs: path, depth. Returns: result

files_moveA

Move or rename a file or folder on Fastmail Files (WebDAV).

Args: source: Source path (e.g. "/Documents/old.txt"). destination: Destination path (e.g. "/Archive/old.txt").

Inputs: source (required), destination (required). Returns: result

files_uploadA

Upload a file to Fastmail Files (WebDAV).

Args: path: Destination path (e.g. "/Documents/report.pdf"). content: Base64-encoded file content. content_type: MIME type of the file (default: application/octet-stream).

Inputs: path (required), content (required), content_type. Returns: result

health_checkA

Verify connectivity to Fastmail and return account info.

Inputs: no named parameters. Returns: result

mail_archive_emailA

Move one or more emails to the Archive mailbox.

Args: email_ids: List of JMAP email IDs to archive.

Inputs: email_ids (required). Returns: result

mail_create_mailboxA

Create a new JMAP mailbox (folder or label) with the given name.

In Fastmail, mailboxes serve as both folders and labels. To create a nested folder, provide the parent mailbox's ID via parent_id. Top-level mailboxes have no parentId. An email can belong to multiple mailboxes (labels).

Inputs: name (required), parent_id. Returns: result

mail_create_masked_emailA

Create a new masked email address.

Args: for_domain: Origin of the site this address is for, e.g. 'https://example.com'. Should be origin only — no path component. description: Short user-supplied description of what this address is for. email_prefix: Optional prefix for the generated address (a-z, 0-9, _ only). url: Optional deep link back to the integrator (e.g. sign-up page URL). 'createdBy' is set server-side from auth credentials; do not try to set it.

Inputs: for_domain, description, email_prefix, url. Returns: result

mail_delete_emailB

Delete one or more emails by moving to Trash, or permanently destroy them.

Args: email_ids: List of JMAP email IDs to delete. permanent: If True, permanently destroy emails. Default moves to Trash.

Inputs: email_ids (required), permanent. Returns: result

mail_delete_mailboxA

Delete a mailbox (folder or label) by its ID.

System mailboxes (inbox, trash, sent, drafts, archive, spam) cannot be deleted. Deleting a folder does not automatically delete its child mailboxes — remove nested folders first. If the mailbox contains emails, set on_destroy_remove_emails=True to delete them along with the mailbox.

Args: mailbox_id: ID of the mailbox to delete. on_destroy_remove_emails: If True, also delete all emails in the mailbox. Default False — the server will reject deletion if emails exist.

Inputs: mailbox_id (required), on_destroy_remove_emails. Returns: result

mail_download_attachmentA

Download an attachment blob by blobId.

Args: blob_id: The blobId of the attachment (from email attachments list). name: The filename to use for the download. content_type: MIME type of the attachment (default: application/octet-stream).

Inputs: blob_id (required), name (required), content_type. Returns: result

mail_export_emailA

Download the raw RFC 5322 .eml source of an email.

Returns the full raw message including all headers and MIME parts. Use this when you need all headers — mail_get_email only fetches headers by name.

Args: email_id: The JMAP email ID. blob_id: Optional blobId; fetched automatically if not provided.

Inputs: email_id (required), blob_id. Returns: result

mail_forward_emailB

Forward an email to one or more recipients, preserving the original content.

Args: email_id: ID of the email to forward. to: List of recipient email addresses. text_body: Optional introductory text prepended before the quoted original. identity_id: Sender identity ID; auto-selects first if omitted.

Inputs: email_id (required), to (required), text_body, identity_id. Returns: result

mail_get_emailA

Get a single email by ID with full body content and attachment metadata.

Optionally fetch specific headers by name. JMAP requires headers to be requested by name — no wildcard fetch is supported. Use mail_export_email to retrieve all raw headers.

Common useful headers:

  • X-Delivered-To: original envelope recipient

  • X-SimpleLogin-Envelope-To: SimpleLogin alias that received the email

  • X-SimpleLogin-Original-From: real sender behind a SimpleLogin reverse alias

Args: email_id: The JMAP email ID. prefer_html: Return HTML body if available; defaults to plain text. headers: Optional list of header names to fetch (e.g. ["X-Delivered-To"]).

Inputs: email_id (required), prefer_html, headers. Returns: result

mail_get_email_threadA

Return all emails in the same thread as the given email, in chronological order.

Args: email_id: ID of any email in the thread.

Inputs: email_id (required). Returns: result

mail_get_recent_emailsA

Get emails received in the last N days.

Args: days: How many days back to look (default 7). limit: Max results (default 20).

Inputs: days, limit. Returns: result

mail_import_emailA

Import a raw RFC 5322 message blob into the mail store.

The blob must already be uploaded (use mail_upload_attachment to get a blobId). The .eml content must be a valid RFC 5322 message with at minimum Date and Message-Id headers — a bare body without proper headers will be rejected.

Args: blob_id: blobId of the uploaded .eml blob. mailbox_ids: List of mailbox IDs to place the email in. keywords: Optional JMAP keywords (e.g. ["$seen", "$flagged"]). received_at: Optional UTC timestamp (ISO 8601) for receivedAt.

Inputs: blob_id (required), mailbox_ids (required), keywords, received_at. Returns: result

mail_list_identitiesA

List all sender identities available on this Fastmail account.

Returns each identity's id, name, and email address.

Inputs: no named parameters. Returns: result

mail_list_mailboxesA

List all JMAP mailboxes (Fastmail folders and labels) with id, name, role, email counts, and parentId.

In Fastmail, both folders and labels are represented as JMAP mailboxes. An email can belong to multiple mailboxes simultaneously — this is how labels work. Nested folders have a parentId pointing to their parent mailbox. System mailboxes (inbox, sent, trash, drafts, archive, spam) have a role field set.

Inputs: no named parameters. Returns: result

mail_list_masked_emailsA

List masked email addresses, optionally filtered by domain or state.

Args: domain: Filter by forDomain (partial match). state: Filter by state: 'enabled', 'disabled', 'deleted', 'pending'. 'pending' addresses auto-enable on first received message and auto-delete after 24 hours if no message is received.

Inputs: domain, state. Returns: result

mail_manage_email_labelsA

Add or remove keywords/labels on one or more emails.

Use this to pin/flag, mark read/unread, or apply custom labels. Common keywords: $flagged (pin/star), $seen (read), $draft, $answered, $forwarded. At least one of add or remove must be provided.

Args: email_ids: List of JMAP email IDs to update. add: Keywords to add (e.g. ["$flagged"] to pin, ["$seen"] to mark read). remove: Keywords to remove (e.g. ["$flagged"] to unpin, ["$seen"] to mark unread).

Inputs: email_ids (required), add, remove. Returns: result

mail_mark_email_readB

Set or unset the $seen flag on one or more emails.

Args: email_ids: List of JMAP email IDs to update. read: True to mark as read, False to mark as unread (default True).

Inputs: email_ids (required), read. Returns: result

mail_move_emailB

Move one or more emails to a mailbox identified by name.

Args: email_ids: List of JMAP email IDs to move. mailbox_name: Name of the destination mailbox (case-insensitive).

Inputs: email_ids (required), mailbox_name (required). Returns: result

mail_parse_emailA

Parse one or more blobs as RFC 5322 messages without importing them.

Useful for viewing .eml attachments or forwarded messages stored as blobs. Metadata fields (mailboxIds, keywords, receivedAt) will be null since the message is not in the mail store.

Args: blob_ids: List of blobIds to parse (e.g. from mail_download_attachment).

Inputs: blob_ids (required). Returns: result

mail_pin_emailA

Pin or unpin one or more emails (sets the $flagged keyword).

Pinned emails appear with a flag/star/pin icon in the mail client.

Args: email_ids: List of JMAP email IDs to pin or unpin. pin: True to pin, False to unpin (default True).

Inputs: email_ids (required), pin. Returns: result

mail_rename_mailboxC

Rename a mailbox (folder or label) by its ID.

Inputs: mailbox_id (required), new_name (required). Returns: result

mail_reply_to_emailA

Reply to an email, preserving threading headers and quoting the original.

Args: email_id: ID of the email to reply to. text_body: Your reply text (original message is quoted below). reply_all: If True, CC all original recipients. identity_id: Sender identity ID; auto-selects first if omitted.

Inputs: email_id (required), text_body (required), reply_all, identity_id. Returns: result

mail_search_emailsA

Search emails with optional filters. Returns id, subject, from, date.

Args: text: Full-text search query. from_: Filter by sender address. to: Filter by recipient address. subject: Filter by subject text. has_attachment: Filter by attachment presence. in_mailbox: Mailbox ID to restrict search to. Use mail_list_mailboxes to get the ID. limit: Max results (default 20). newest_first: Sort newest first (default True).

Inputs: text, from_, to, subject, +4 more. Returns: result

mail_search_snippetsB

Get highlighted subject/preview snippets for a list of emails matching a filter.

Returns subject (with tags around matches) and a preview snippet per email. Use the same filter params as mail_search_emails to get relevant highlights.

Args: email_ids: List of email IDs to fetch snippets for. text: Full-text search query (used for highlighting). from_: Filter by sender address. to: Filter by recipient address. subject: Filter by subject text. has_attachment: Filter by attachment presence.

Inputs: email_ids (required), text, from_, to, +2 more. Returns: result

mail_send_emailA

Send an email via Fastmail.

Args: to: List of recipient email addresses. subject: Email subject line. text_body: Plain-text body content. cc: Optional list of CC addresses. bcc: Optional list of BCC addresses. html_body: Optional HTML body content. Passed verbatim to the JMAP API with no sanitisation. When this tool is driven by an AI agent that processes external content, ensure the html_body value originates from a trusted source to prevent prompt- injection attacks from causing malicious emails to be sent. identity_id: Sender identity ID; auto-selects first identity if omitted.

Inputs: to (required), subject (required), text_body (required), cc, +3 more. Returns: result

mail_set_identityA

Create, update, or destroy a sender identity.

To create: provide create_email (required) and optionally create_name. To update: provide update_id plus any fields to change (name, replyTo, bcc, textSignature, htmlSignature). To destroy: provide destroy_id. Fails if mayDelete is false on that identity.

replyTo and bcc are lists of EmailAddress objects: [{"email": "...", "name": "..."}].

Requires urn:ietf:params:jmap:submission capability.

Inputs: create_email, create_name, update_id, update_name, +5 more. Returns: result

mail_update_masked_emailA

Update a masked email address.

Args: masked_email_id: The ID of the masked email to update. state: New state: 'enabled', 'disabled', or 'deleted'. 'deleted' soft-deletes the address (mail will bounce). for_domain: Update the origin domain, e.g. 'https://example.com' (no path). description: Update the description. url: Update the deep link URL.

Inputs: masked_email_id (required), state, for_domain, description, +1 more. Returns: result

mail_upload_attachmentA

Upload a blob for use in email composition.

Args: data: Base64-encoded file content. content_type: MIME type of the file. name: Filename (informational only; not stored with the blob).

Inputs: data (required), content_type (required), name (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 48 tools

    Disambiguation5/5

    Tools are clearly grouped by domain (calendar_, contacts_, files_, mail_) with distinct actions (create, delete, get, list, update, etc.). Overlaps like mail_mark_email_read and mail_manage_email_labels are clarified by descriptions, making each tool's purpose unambiguous.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with domain prefix (e.g., calendar_create_event, mail_send_email). Even longer names like mail_manage_email_labels keep the convention, ensuring predictability.

    Tool Count4/5

    48 tools is high but well-justified by the breadth of Fastmail's capabilities (mail, calendar, contacts, files). The organization into clear domains prevents confusion, though the sheer number may feel heavy.

    Completeness5/5

    Mail tools cover sending, receiving, searching, labeling, identities, masked emails, attachments, importing/exporting, forwarding, replying, and more. Calendar and contacts have full CRUD. Files have basic operations. No obvious gaps for the stated domains.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Fastmail that provides access to email, contacts, and calendars via the JMAP protocol. It enables users to search, send, and bulk-manage emails while also interacting with calendar events and address books through natural language.
      76 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Unified MCP server for Fastmail email (JMAP), calendar (CalDAV), and contacts (CardDAV). Enables sending emails, managing events, and syncing contacts through natural language.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      An unofficial MCP server that lets AI assistants work with a Fastmail account through its JMAP, CalDAV, and WebDAV APIs, covering mailbox and message listing, searching, sending, replying, drafting, attachments, labels, contacts, and calendar events. It also supports security-conscious metadata-only queries and can be installed as a Claude Desktop extension.
      -