add_labels
Add one or more mailbox labels to an email without removing its existing mailbox assignments.
LABSCO SUMMARY
Mail, calendar and contacts on one token, with tools shaped around the questions people actually ask.
The design detail worth noticing is the anti-search tooling: unread mail, latest mail, mailbox statistics and an account summary each have their own tool, so "what needs attention" does not become a search query returning a wall of messages. Bulk operations and label add/remove that preserve other mailbox assignments make inbox cleanup safe to hand over, and one-click unsubscribe is deliberately narrow — HTTPS only, and only where the message advertises support for it.
What it is
A Fastmail server over JMAP. It covers mail, mailboxes, calendars and contacts in one account, with separate tools for the common questions so you are not writing search filters for everything.
What you get
- Search by sender, recipient, subject, date range, attachments or full text — and dedicated tools for the two questions search is usually misused for: what is unread, and what arrived most recently
- One email in full, one thread in chronological order, or just the headers — unsubscribe, reply routing, return path and authentication — without pulling the body
- A mailbox browsed page by page, attachments listed before you fetch them, and one attachment downloaded by blob ID as text or base64
- Sending: a new message from one of your sender identities, a reply with In-Reply-To and References set for you, a forward, or a draft saved now and sent later
- Filing: move between mailboxes, add or remove labels while leaving other assignments alone, flag and unflag, mark read and unread, archive, and delete to Trash or permanently
- The same operations across many messages at once, plus marking a whole mailbox read in one call
- Compact overviews instead of long listings — per-mailbox email, unread and thread counts, and an account-level summary with top mailboxes
- One-click unsubscribe, which only posts to HTTPS List-Unsubscribe URLs where List-Unsubscribe-Post advertises it
- Mailboxes created, renamed and deleted, with force required to delete one that still has contents
- Calendars listed, events read by date range or ID, created, updated and deleted
- Address books listed, contacts searched, read, created, updated and deleted
- Summaries and drafted replies produced through your own client's model, when the client supports sampling
- A capability check that reports which Fastmail feature groups and client capabilities are actually available, with setup guidance for the missing ones
Requirements
A Fastmail account on the Standard or Professional plan and an API token with JMAP access. Create it under Settings → Privacy & Security → Manage API tokens and grant Mail, Calendars and Contacts read and write, then pass it as FASTMAIL_API_TOKEN. Node.js 18 or later; run it with npx @jordonh19/fastmail-mcp-server over stdio, from the npm package @jordonh19/fastmail-mcp-server, currently 1.3.0. Adding --transport http --port 3000 serves a single /mcp endpoint over Streamable HTTP plus a browser dashboard, whose one-time access token is printed to the console at startup. The summarize and reply-drafting tools need an MCP client that supports sampling.
Setup effort
One command plus a key — npx @jordonh19/fastmail-mcp-server, then supply credentials
USE CASES
01
Finding out what actually needs attention this morning
Pull the account summary and the unread mail rather than searching, then open the threads that matter.
02
Clearing a newsletter backlog
Search the sender, check the headers advertise it, and send the one-click unsubscribe before archiving the rest in bulk.
03
Replying to a thread without breaking the threading
Read the thread, then reply — In-Reply-To and References are set for you and the recipients worked out.
04
Getting a file out of an email
List the attachments first for names, types and blob IDs, then download the one you want.
05
Filing a batch of mail into the right folders
List the mailboxes for their IDs, then move or relabel many messages in one call.
06
Turning an email into a calendar entry
Read the message, list the calendars, and create the event on the right one.
07
Working out why something is not working before you debug it
Run the capability check — it reports which Fastmail feature groups and client capabilities are available.
47 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
archive_email
Move one or more emails to the Archive mailbox. A convenient one-step operation for archiving emails you've dealt with.
bulk_add_labels
Add one or more mailbox labels to multiple emails at once while preserving their other mailbox assignments.
bulk_email_action
Perform an action on multiple emails at once. Supports marking as read/unread, flagging/unflagging, moving, and deleting.
bulk_remove_labels
Remove one or more mailbox labels from multiple emails at once while preserving any other mailbox assignments.
check_function_availability
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.
create_calendar_event
Create a new calendar event. Use list_calendars first to get calendar IDs.
create_contact
Create a new contact in the Fastmail address book
create_draft
Save an email as a draft without sending. The draft can be edited or sent later using send_draft.
create_mailbox
Create a new mailbox (folder) in the Fastmail account
delete_calendar_event
Delete a calendar event by its ID
delete_contact
Delete a contact by their ID
delete_email
Delete an email. By default moves to Trash. Set permanent=true to permanently destroy the email.
delete_mailbox
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.
download_attachment
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.
forward_email
Forward an existing email to new recipients with an optional message
get_account_summary
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.
get_calendar_event
Get the full details of a specific calendar event by its ID
get_calendar_events
Get calendar events within a date range. Optionally filter by calendar ID or search text.
get_contact
Get full details of a specific contact by their ID
get_email
Get the full content of a specific email by its ID, including headers, body text, and attachment info
get_email_attachments
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.
get_email_headers
Get selected raw email headers for a message without returning the full body. Defaults to unsubscribe, reply routing, return path, and authentication headers.
get_identities
List all sender identities (email addresses) available for sending emails
get_latest_emails
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.
get_mailbox_emails
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.
get_mailbox_stats
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.
get_thread
Get all emails in a conversation thread, showing the full discussion chronologically
get_unread_emails
Retrieve unread emails, optionally filtered by mailbox. Best for checking what needs attention. Do not use search_emails for this purpose.
list_address_books
List all address books (contact groups) in the Fastmail account
list_calendars
List all calendars in the Fastmail account with their names, colors, and visibility status
list_mailboxes
List all mailboxes (folders) in the Fastmail account with their roles, email counts, and IDs
mark_mailbox_read
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.
move_email
Move an email to a different mailbox (folder). Use list_mailboxes to find mailbox IDs.
one_click_unsubscribe
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.
remove_labels
Remove one or more mailbox labels from an email while preserving any other mailbox assignments.
rename_mailbox
Rename an existing mailbox (folder). Use list_mailboxes to find the mailbox ID.
reply_email
Reply to an existing email. Automatically sets threading headers (In-Reply-To, References) and determines recipients.
search_contacts
Search contacts by name, email, or other criteria. Returns a summary list of matching contacts.
search_emails
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.
send_draft
Send a previously saved draft email. The draft must already exist in the Drafts mailbox.
send_email
Compose and send a new email. Use get_identities first to find available sender identities.
suggest_reply
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.
summarize_email
Use the connected LLM to produce a concise summary of an email's subject, sender, and body. Requires the MCP client to support sampling.
update_calendar_event
Update an existing calendar event. Only specified fields will be changed.
update_contact
Update an existing contact's information. Only the fields you provide will be updated; other fields remain unchanged.
update_email_flags
Update email flags (read/unread status, flagged/unflagged status)
BEFORE YOU INSTALL
What to know first
Tools you get
47 tools when we connected. suggest_reply and summarize_email are available but undocumented. Grant the token Mail, Calendars and Contacts read-write; a Mail-only token leaves calendar and contact tools failing.
Requires
- npx on PATH
- Node.js 18 or later
- FASTMAIL_API_TOKEN in your environment
CONTEXT COST
Moderate Standing cost
Rated by the size of the 47 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx @jordonh19/fastmail-mcp-serverMCP Clients
Claude Desktop, Cursor, Windsurf
JSON
{
"mcpServers": {
"fastmail": {
"command": "npx",
"args": [
"@jordonh19/fastmail-mcp-server"
],
"env": {
"FASTMAIL_API_TOKEN": "<YOUR_FASTMAIL_API_TOKEN>"
}
}
}
}Claude Code
CLAUDE CODE · TERMINAL
export FASTMAIL_API_TOKEN="<YOUR_FASTMAIL_API_TOKEN>"
claude mcp add fastmail -- npx @jordonh19/fastmail-mcp-serverThe server reads FASTMAIL_API_TOKEN from the environment Claude Code runs in, so start claude from a shell where it is set.
VS Code
VS CODE · JSON
{
"servers": {
"fastmail": {
"command": "npx",
"args": [
"@jordonh19/fastmail-mcp-server"
],
"env": {
"FASTMAIL_API_TOKEN": "<YOUR_FASTMAIL_API_TOKEN>"
}
}
}
}Any MCP client
ANY MCP CLIENT · TERMINAL
FASTMAIL_API_TOKEN="<YOUR_FASTMAIL_API_TOKEN>" npx @jordonh19/fastmail-mcp-server
