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

Related MCP server: Fastmail MCP Server

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:

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