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., "@Fastmail MCP Server show me my latest 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.
A Model Context Protocol (MCP) server for Fastmail. Enables any MCP-compatible AI assistant to read, search, send, and manage emails, calendars, and contacts in a Fastmail account via the JMAP protocol.
Node.js 18 or later
A Fastmail account (Standard or Professional plan)
A Fastmail API token with JMAP access
Related MCP server: fastmail-mcp
Log in to Fastmail
Go to Settings → Privacy & Security → Manage API tokens
Click New API token
Grant access to Mail, Calendars, and Contacts (read and write)
Copy the generated token
npm install @jordonh19/fastmail-mcp-serverOr run directly:
npx @jordonh19/fastmail-mcp-serverThis MCP server works with any AI assistant that supports the Model Context Protocol. Below are examples for popular MCP clients.
Add to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"fastmail": {
"command": "npx",
"args": ["@jordonh19/fastmail-mcp-server"],
"env": {
"FASTMAIL_API_TOKEN": "your-api-token-here"
}
}
}
}export FASTMAIL_API_TOKEN="your-api-token-here"
claude mcp add fastmail -- npx @jordonh19/fastmail-mcp-serverAdd to your Cursor MCP configuration (.cursor/mcp.json):
{
"mcpServers": {
"fastmail": {
"command": "npx",
"args": ["@jordonh19/fastmail-mcp-server"],
"env": {
"FASTMAIL_API_TOKEN": "your-api-token-here"
}
}
}
}Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"fastmail": {
"command": "npx",
"args": ["@jordonh19/fastmail-mcp-server"],
"env": {
"FASTMAIL_API_TOKEN": "your-api-token-here"
}
}
}
}Add to your VS Code MCP configuration (.vscode/mcp.json):
{
"servers": {
"fastmail": {
"command": "npx",
"args": ["@jordonh19/fastmail-mcp-server"],
"env": {
"FASTMAIL_API_TOKEN": "your-api-token-here"
}
}
}
}For any MCP-compatible client, run the server with the FASTMAIL_API_TOKEN environment variable set:
FASTMAIL_API_TOKEN="your-api-token-here" npx @jordonh19/fastmail-mcp-serverThe server communicates over stdio by default, following the standard MCP transport protocol. To run over HTTP instead, use the --transport flag:
FASTMAIL_API_TOKEN="your-api-token-here" npx @jordonh19/fastmail-mcp-server --transport http --port 3000search_emails: Search emails by mailbox, text, sender, date range, attachments, and more.
get_email: Get full email content by ID.
get_email_headers: Get selected email headers without returning the full message body.
get_thread: Get all emails in a conversation thread.
get_unread_emails: Quickly retrieve unread emails, optionally filtered by mailbox.
get_latest_emails: Get the most recent emails from all or a specific mailbox.
get_mailbox_emails: List emails in a specific mailbox with pagination.
get_email_attachments: List attachments on an email without returning the full message body.
send_email: Compose and send a new email.
reply_email: Reply or reply-all to an email.
forward_email: Forward an email to new recipients.
create_draft: Save an email as a draft without sending.
send_draft: Send a previously saved draft email.
move_email: Move an email to a different mailbox.
add_labels: Add mailbox labels to an email while preserving existing mailbox assignments.
remove_labels: Remove mailbox labels from an email while preserving other mailbox assignments.
update_email_flags: Mark emails as read/unread or flagged/unflagged.
delete_email: Move to Trash or permanently delete.
bulk_email_action: Perform actions on multiple emails at once.
bulk_add_labels: Add mailbox labels to multiple emails at once.
bulk_remove_labels: Remove mailbox labels from multiple emails at once.
archive_email: Move one or more emails to the Archive mailbox.
mark_mailbox_read: Mark all emails in a mailbox as read.
get_mailbox_stats: Get compact mailbox-level unread, email, and thread counts.
get_account_summary: Get a compact account overview with unique email totals and top mailboxes.
download_attachment: Download an email attachment by blob ID.
one_click_unsubscribe: Send a one-click unsubscribe request for an email.
list_mailboxes: List all mailboxes or folders with roles and email counts.
create_mailbox: Create a new mailbox or folder.
rename_mailbox: Rename an existing mailbox or folder.
delete_mailbox: Delete a mailbox or folder, optionally with force delete.
list_calendars: List all calendars with names, colors, and visibility.
get_calendar_events: Search or list calendar events by date range, calendar, or title.
get_calendar_event: Get full details of a specific calendar event.
create_calendar_event: Create a new calendar event with location, participants, and alerts.
update_calendar_event: Update an existing calendar event.
delete_calendar_event: Delete a calendar event.
list_address_books: List all address books or contact groups.
search_contacts: Search contacts by name, email, or other criteria.
get_contact: Get full details of a specific contact.
create_contact: Create a new contact with email, phone, organization, and more.
update_contact: Update an existing contact's information.
delete_contact: Delete a contact.
get_identities: List available sender identities.
check_function_availability: Check which Fastmail feature groups and MCP client capabilities are available, with setup guidance for missing access.
The server supports two transport modes:
Standard input/output transport. Used by most MCP clients (Claude Desktop, Cursor, VS Code, etc.):
FASTMAIL_API_TOKEN="your-token" npx @jordonh19/fastmail-mcp-serverRuns as an HTTP server for remote access or multi-client scenarios:
FASTMAIL_API_TOKEN="your-token" npx @jordonh19/fastmail-mcp-server --transport http --port 3000The HTTP transport exposes a single /mcp endpoint that supports the MCP Streamable HTTP protocol.
When running in HTTP mode, a built-in web dashboard is available at the server root. It provides:
Live tool-call log — see every MCP tool invocation in real time via SSE
Connection tracking — monitor active MCP client connections
Server uptime — at-a-glance health status
On startup the server prints a one-time access token to the console. Open http://localhost:<port>/ in a browser and enter the token to log in. The token is bound to an HttpOnly cookie so it never appears in URLs.
A pre-packaged .dxt extension can be built for one-click installation in Claude Desktop:
npm run build:dxtThis produces fastmail-mcp-server-v<version>.dxt in the project root. Double-click the file (or drag it into Claude Desktop) to install. Claude will prompt for your Fastmail API token on first use.
The server can be configured via environment variables or a JSON config file.
FASTMAIL_API_TOKEN: Required. Fastmail API token with JMAP access.
Create a .fastmail-mcp.json file in your project root or home directory:
{
"transport": "stdio",
"port": 3000
}The server searches for config files in this order:
./.fastmail-mcp.json (current directory)
~/.fastmail-mcp.json (home directory)
Environment variables and CLI flags always take precedence over config file values.
See CONTRIBUTING.md for detailed development guidelines.
git clone https://github.com/Jordonh18/fastmail-mcp-server.git
cd fastmail-mcp-server
npm install
npm run build
npm testCommand | Description |
| TypeScript compilation |
| Build + package as a Claude Desktop |
| Watch mode build |
| Run tests (Vitest) |
| Tests with v8 coverage |
| Type check without emitting |
Run locally:
FASTMAIL_API_TOKEN="your-token" node dist/index.jsMIT
Add one or more mailbox labels to an email without removing its existing mailbox assignments.
Inputs: emailId (required), mailboxIds (required).
Move one or more emails to the Archive mailbox. A convenient one-step operation for archiving emails you've dealt with.
Inputs: emailIds (required).
Add one or more mailbox labels to multiple emails at once while preserving their other mailbox assignments.
Inputs: emailIds (required), mailboxIds (required).
Perform an action on multiple emails at once. Supports marking as read/unread, flagging/unflagging, moving, and deleting.
Inputs: action (required), emailIds (required), mailboxId.
Remove one or more mailbox labels from multiple emails at once while preserving any other mailbox assignments.
Inputs: emailIds (required), mailboxIds (required).
Check which major Fastmail feature groups are available for this account and MCP client, including setup guidance for missing mail, submission, contacts, calendars, or sampling support.
Inputs: no named parameters.
Create a new calendar event. Use list_calendars first to get calendar IDs.
Inputs: start (required), title (required), calendarId (required), status, +8 more.
Create a new contact in the Fastmail address book
Inputs: addressBookId (required), notes, emails, phones, +6 more.
Save an email as a draft without sending. The draft can be edited or sent later using send_draft.
Inputs: to (required), body (required), subject (required), cc, +2 more.
Create a new mailbox (folder) in the Fastmail account
Inputs: name (required), parentId.
Delete a calendar event by its ID
Inputs: eventId (required).
Delete a contact by their ID
Inputs: contactId (required).
Delete an email. By default moves to Trash. Set permanent=true to permanently destroy the email.
Inputs: emailId (required), permanent.
Delete a mailbox (folder). The mailbox must be empty or you must set force=true to delete with all contents. System mailboxes (Inbox, Trash, etc.) cannot be deleted.
Inputs: mailboxId (required), force.
Download an email attachment by its blob ID. Use get_email first to find attachment blob IDs. Returns text content directly for text files, or base64-encoded data for binary files. Maximum attachment size is 10 MB.
Inputs: blobId (required), name.
Forward an existing email to new recipients with an optional message
Inputs: to (required), emailId (required), body, identityId.
Get a compact account-level summary with unique email totals, unread counts, mailbox counts, and top mailboxes. Prefer this over large list calls when you only need an overview.
Inputs: no named parameters.
Get the full details of a specific calendar event by its ID
Inputs: eventId (required).
Get calendar events within a date range. Optionally filter by calendar ID or search text.
Inputs: after, limit, title, before, +1 more.
Get full details of a specific contact by their ID
Inputs: contactId (required).
Get the full content of a specific email by its ID, including headers, body text, and attachment info
Inputs: emailId (required).
List the attachments on a specific email without returning the full email body. Use this when you only need filenames, types, sizes, and blob IDs before calling download_attachment.
Inputs: emailId (required).
Get selected raw email headers for a message without returning the full body. Defaults to unsubscribe, reply routing, return path, and authentication headers.
Inputs: emailId (required), headers.
List all sender identities (email addresses) available for sending emails
Inputs: no named parameters.
Get the most recent emails sorted by date. Best for quickly checking recent activity without specific search criteria. Do not use search_emails for this purpose.
Inputs: limit, mailboxId.
List emails in a specific mailbox with pagination support. Use this when browsing a folder's contents page by page. Use list_mailboxes first to find available mailbox IDs.
Inputs: mailboxId (required), page, limit.
Get compact mailbox statistics such as email counts, unread counts, and thread counts. Use this when you need an overview instead of listing mailbox contents.
Inputs: mailboxId.
Get all emails in a conversation thread, showing the full discussion chronologically
Inputs: threadId (required).
Retrieve unread emails, optionally filtered by mailbox. Best for checking what needs attention. Do not use search_emails for this purpose.
Inputs: limit, mailboxId.
List all address books (contact groups) in the Fastmail account
Inputs: no named parameters.
List all calendars in the Fastmail account with their names, colors, and visibility status
Inputs: no named parameters.
List all mailboxes (folders) in the Fastmail account with their roles, email counts, and IDs
Inputs: no named parameters.
Mark all emails in a specific mailbox as read. Useful for clearing unread counts on a mailbox. Processes up to 500 unread emails at a time.
Inputs: mailboxId (required).
Move an email to a different mailbox (folder). Use list_mailboxes to find mailbox IDs.
Inputs: emailId (required), mailboxId (required).
Unsubscribe from a message using one-click unsubscribe headers. Only posts to safe HTTPS List-Unsubscribe URLs when List-Unsubscribe-Post advertises one-click unsubscribe.
Inputs: emailId (required).
Remove one or more mailbox labels from an email while preserving any other mailbox assignments.
Inputs: emailId (required), mailboxIds (required).
Rename an existing mailbox (folder). Use list_mailboxes to find the mailbox ID.
Inputs: newName (required), mailboxId (required).
Reply to an existing email. Automatically sets threading headers (In-Reply-To, References) and determines recipients.
Inputs: body (required), emailId (required), replyAll, identityId.
Search contacts by name, email, or other criteria. Returns a summary list of matching contacts.
Inputs: email, limit, query, addressBookId.
Search for emails using filters like sender, recipient, subject, date range, or full-text query. Use this tool when you need to find specific emails matching particular criteria. For simply checking recent emails, use get_latest_emails instead. For unread emails only, use get_unread_emails instead.
Inputs: to, from, after, limit, +5 more.
Send a previously saved draft email. The draft must already exist in the Drafts mailbox.
Inputs: emailId (required), identityId.
Compose and send a new email. Use get_identities first to find available sender identities.
Inputs: to (required), body (required), subject (required), cc, +2 more.
Use the connected LLM to draft a reply to an email based on the provided intent or instructions. Requires the MCP client to support sampling.
Inputs: intent (required), emailId (required).
Use the connected LLM to produce a concise summary of an email's subject, sender, and body. Requires the MCP client to support sampling.
Inputs: emailId (required).
Update an existing calendar event. Only specified fields will be changed.
Inputs: eventId (required), start, title, status, +5 more.
Update an existing contact's information. Only the fields you provide will be updated; other fields remain unchanged.
Inputs: contactId (required), notes, emails, phones, +6 more.
Update email flags (read/unread status, flagged/unflagged status)
Inputs: emailId (required), isRead, isFlagged.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 47 tools
Multiple email retrieval tools (search_emails, get_latest_emails, get_unread_emails, get_mailbox_emails) overlap in functionality, though descriptions explicitly clarify when to use each. Bulk actions also duplicate single-item operations, but most other tools have clear boundaries.
Most tools use a consistent verb_noun pattern (get_, list_, create_, update_, delete_, send_, etc.). Minor deviations like 'one_click_unsubscribe' and 'check_function_availability' don't fit the pattern, and 'bulk_email_action' is inconsistent with 'bulk_add_labels'/'bulk_remove_labels'.
47 tools is excessive for a single server, even covering email, calendar, and contacts. The granularity is inflated by many specialized bulk operations and retrieval variants (latest, unread, mailbox, search) that could be consolidated.
Email functionality is thorough, with full CRUD, search, drafts, labels, flags, and bulk actions. Calendar and contacts have basic CRUD, but calendar-level management (create/update/delete calendars) and a simple list-all-contacts endpoint are missing. These are workable gaps.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.