fastmail-mcp

A Model Context Protocol (MCP) server for Fastmail built with FastMCP, httpx, and Pydantic.

Communicates with Fastmail via JMAP (RFC 8620 / 8621) — no IMAP, no Node, no forks.

Features

Area	Tools	JMAP methods
Session	get_jmap_session	GET /jmap/session
Mailboxes	list_mailboxes, create_mailbox, update_mailbox, destroy_mailbox	Mailbox/get, Mailbox/set
Email (read)	query_emails, get_emails, get_recent_emails, get_thread	Email/query, Email/get, Thread/get
Submission	list_identities, send_email, create_draft, edit_draft, send_draft, reply_email	Identity/get, Email/set, EmailSubmission/set
Mutations	mark_email_read, pin_email, delete_email, move_email, add_labels, remove_labels	Email/set
Bulk mutations	bulk_mark_read, bulk_pin, bulk_delete, bulk_move, bulk_add_labels, bulk_remove_labels	Email/set (batch)
Attachments & stats	get_email_attachments, download_attachment, get_mailbox_stats, get_account_summary	Email/get, Mailbox/get
Masked Email	list_masked_emails, create_masked_email, update_masked_email, destroy_masked_email	MaskedEmail/get, MaskedEmail/set
Vacation	get_vacation_response, set_vacation_response	VacationResponse/get, VacationResponse/set
Sieve Scripts	list_sieve_scripts, get_sieve_script, create_sieve_script, update_sieve_script, destroy_sieve_script, validate_sieve_script	SieveScript/get, SieveScript/set, SieveScript/validate

Setup

1. Create a Fastmail API token

1. Go to Fastmail → Settings → Privacy & Security → Integrations → API tokens (or see Fastmail developer docs).
2. Create a new API token with the scopes you need:

Scope	Required for
urn:ietf:params:jmap:core	All tools (session discovery)
urn:ietf:params:jmap:mail	Mailboxes, email read/query, mutations, threads, attachments, stats
urn:ietf:params:jmap:submission	Sending email, draft lifecycle, reply, identities (list_identities, send_email, send_draft, reply_email)
https://www.fastmail.com/dev/maskedemail	Masked email tools
urn:ietf:params:jmap:vacationresponse	Vacation response tools
urn:ietf:params:jmap:sieve	Sieve script tools (if available — see Filters & Rules note)

2. Environment variables

Copy .env.example to .env and fill in your token:

# Required
FASTMAIL_API_TOKEN=fmu1-...

# Optional — override the JMAP session URL (default: Fastmail production)
# FASTMAIL_JMAP_SESSION_URL=https://api.fastmail.com/jmap/session

# HTTP transport only — see "Deployment" section
# FASTMAIL_MCP_HTTP_ALLOW_ENV_API_KEY=false

Usage

Local (stdio) — Cursor, Claude Desktop, etc.

Install from the repo (or a built wheel):

uv pip install -e .

Run the MCP server over stdio:

fastmail-mcp

Cursor configuration

Add to your Cursor MCP settings (.cursor/mcp.json or global):

{
  "mcpServers": {
    "fastmail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fastmail-mcp", "fastmail-mcp"],
      "env": {
        "FASTMAIL_API_TOKEN": "fmu1-..."
      }
    }
  }
}

Claude Desktop configuration

{
  "mcpServers": {
    "fastmail": {
      "command": "/path/to/fastmail-mcp/.venv/bin/fastmail-mcp",
      "env": {
        "FASTMAIL_API_TOKEN": "fmu1-..."
      }
    }
  }
}

Remote (HTTP) — hosted server

Start the HTTP transport:

fastmail-mcp-http

Callers authenticate per-request via:

• Header (preferred): X-Fastmail-Api-Token: fmu1-...
• Query parameter: ?fastmail_api_token=fmu1-...

Connect from Cursor or Claude Desktop using mcp-remote:

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-host.example.com/mcp",
        "--header",
        "X-Fastmail-Api-Token: fmu1-..."
      ]
    }
  }
}

Sending email

The send_email, reply_email, and send_draft tools require a token with the urn:ietf:params:jmap:submission scope in addition to urn:ietf:params:jmap:mail.

Typical flow:

1. List identities — list_identities shows which "from" addresses are available.
2. Send directly — send_email composes and sends in one step (creates the email + submission as a single JMAP batch).
3. Draft workflow — create_draft → edit_draft (optional, can repeat) → send_draft.
4. Reply — reply_email automatically builds Re: subject, In-Reply-To, and References headers. Use reply_all=true to include all original recipients.

JMAP emails are immutable — edit_draft atomically creates a new draft and destroys the old one.

Deployment

• Never store a shared user token in server environment on a hosted deployment. Set FASTMAIL_MCP_HTTP_ALLOW_ENV_API_KEY=false (the default) so the server always requires callers to send their own token via header or query parameter.
• Never log tokens. The server uses SecretStr for the env token and never writes it to stdout/stderr.
• Never log message bodies or email addresses. Error messages from JMAP are surfaced but the server does not log email content.
• download_attachment returns a URL only — it does not write files to the server filesystem, making it safe for hosted deployments.
• For single-user local setups, FASTMAIL_API_TOKEN in the process env is fine — it's only read when running over stdio, or when FASTMAIL_MCP_HTTP_ALLOW_ENV_API_KEY=true.

Filters & Rules (web UI)

Fastmail's Settings → Filters & Rules (move-to-mailbox rules, snooze actions, blocked senders, etc.) are configured through the web UI. These rules are not part of the standard JMAP API exposed to API tokens.

• If the JMAP session advertises urn:ietf:params:jmap:sieve (RFC 9661), the Sieve script tools in this server can list, create, and manage server-side Sieve filter scripts.
• If the capability is absent, the Sieve tools will return a clear error message. In that case, manage your filters at https://app.fastmail.com/settings/rules.
• Snooze-specific actions and UI-only rule types are not available via any public API.

Development

# Clone and install
git clone https://github.com/your-user/fastmail-mcp.git
cd fastmail-mcp
uv sync

# Run locally
uv run fastmail-mcp

# Lint
uv run ruff check .
uv run basedpyright

Links

• Fastmail developer docs
• JMAP specification (RFC 8620)
• JMAP Mail (RFC 8621)
• JMAP for Sieve Scripts (RFC 9661)
• FastMCP
• Model Context Protocol