pyfastmail-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pyfastmail-mcp Summarize my recent unread emails"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
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-mcpOr run directly with uvx:
uvx pyfastmail-mcpConfiguration
1. Get Fastmail Credentials
You need an API token from Fastmail. An app password is optional (only needed for calendar and file storage).
API Token (required — mail and contacts): Fastmail Settings → Privacy & Security → API Tokens — enable the
urn:ietf:params:jmap:contactscapabilityApp Password (optional — calendars and files): Fastmail Settings → Privacy & Security → App Passwords — create one with the "DAV (CardDAV, CalDAV, WebDAV)" scope
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 |
| Verify connection and auth |
| List all mailboxes (folders/labels) |
| Create a mailbox |
| Rename a mailbox |
| Delete a mailbox |
| Get email by ID (with optional headers) |
| Get recent emails |
| Search by query |
| Highlighted search result snippets |
| Get full thread |
| Mark read/unread |
| Pin/unpin (flag/star) |
| Move to mailbox |
| Move to trash or permanently delete |
| Archive |
| Add/remove keywords |
| Download raw .eml file |
| Import .eml into mail store |
| Parse a blob as email without importing |
| List send-as identities |
| Create/update/delete identities |
| Send new email |
| Reply to email |
| Forward email |
| List masked emails |
| Create masked email |
| Update masked email state, domain, description, or URL |
| Download attachment |
| Upload blob for sending |
Contacts (contacts_*)
Tool | Description |
| List address books |
| List contacts (query+get combo) |
| Get contact(s) by ID |
| Query contacts with filters and sorting |
| Create contact |
| Update contact fields |
| Delete contact(s) |
Calendar (calendar_*)
Tool | Description |
| List calendars |
| List events |
| Get event details |
| Create event |
| Update event |
| Delete event |
Files (files_*)
Tool | Description |
| List files/folders |
| Download file |
| Upload file |
| Create folder |
| Move/rename file |
| Delete file/folder |
Development
git clone https://github.com/pjosols/pyfastmail-mcp.git
cd pyfastmail-mcp
uv sync --group dev
uv run pytestLicense
MIT
Available Tools
48 toolscalendar_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
Scored across 48 tools
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.
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.
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.
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
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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 npmMIT
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data.38MIT
- AlicenseNot gradedqualityCmaintenanceUnified MCP server for Fastmail email (JMAP), calendar (CalDAV), and contacts (CardDAV). Enables sending emails, managing events, and syncing contacts through natural language.MIT
- FlicenseNot gradedqualityAmaintenanceAn 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.-