fastmail-mcp-server

MCP server for Fastmail. Read, search, organize, and send emails through Claude Desktop.

Features

• Full read/write - list, search, send, reply, forward, move, mark as spam
• Safe sending - preview→confirm flow prevents accidental sends
• Masked emails - create/manage disposable email addresses
• Advanced search - filter by date, sender, attachments, unread, flagged status
• Thread support - get_email returns full conversation context
• Attachment text extraction - PDFs, Word docs, Excel, PowerPoint extracted as readable text
• Legacy .doc support - uses macOS textutil for old Word formats
• Image attachments - auto-resized to fit model limits, returned for Claude's built-in vision/OCR
• CC/BCC support - full addressing on send, reply, and forward

Comparison

Prerequisites

Requires Bun runtime:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Or via mise
mise use -g bun

Quick Start

1. Generate Fastmail API Token

1. Open Fastmail Settings → Privacy & Security → Integrations
2. Scroll to API tokens and click Manage
3. Click New API token
4. Name it something like "Claude MCP"
5. Under Access, enable:
   • Mail - required (read and write)
6. Click Generate
7. Copy the token immediately - you won't see it again

Token format: fmu1-xxxxxxxx-xxxxxxxxxxxx...

2. Configure Claude Desktop

Install the server globally:

# Via mise (recommended)
mise use -g npm:fastmail-mcp-server

# Or via npm
npm install -g fastmail-mcp-server

Open the Claude Desktop config file:

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or create it if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the fastmail server config:

{
  "mcpServers": {
    "fastmail": {
      "command": "fastmail-mcp-server",
      "env": {
        "FASTMAIL_API_TOKEN": "fmu1-your-token-here"
      }
    }
  }
}

Note: If Claude Desktop can't find the command, use the full path from which fastmail-mcp-server

3. Restart Claude Desktop

Quit Claude Desktop completely (Cmd+Q) and reopen it. The Fastmail tools should now appear.

Security

Token storage: The token lives in claude_desktop_config.json in your user directory. This file is only readable by your user account. For additional security:

• Don't commit the config file to version control
• Rotate tokens periodically via Fastmail settings
• Use minimal scopes - only enable Mail access unless you need more
• Revoke immediately if compromised via Fastmail settings

Send protection: All email-sending operations require explicit two-step confirmation:

1. action: "preview" - shows exactly what will be sent
2. action: "confirm" - actually sends

No emails can be sent accidentally.

Available Tools

Read Operations (no confirmation needed)

Attachment Handling

get_attachment automatically extracts readable content from attachments:

Claude receives actual text content, not binary blobs - just like when you drag-and-drop files into Claude Desktop.

Write Operations

Masked Email Operations

Example Prompts

"What's in my inbox?"

"Check the met-police folder - anything urgent?"

"Search for emails from john@example.com"

"Find unread emails from last week with attachments"

"Show me flagged emails from December"

"What would be a good response to the latest email from the solicitor?"

"Draft a reply to that insurance email explaining the situation"

"Forward that receipt to my accountant"

"Move all the newsletters to Archive"

"Mark that spam email as junk"

"Create a masked email for signing up to this sketchy website"

"List my masked emails and disable the one for that service I cancelled"

Troubleshooting

"FASTMAIL_API_TOKEN environment variable is required"

• Check your Claude Desktop config has the token in the env section
• Make sure the JSON is valid (no trailing commas)
• Restart Claude Desktop completely (Cmd+Q)

"Failed to get JMAP session: 401"

• Token is invalid or expired
• Generate a new token in Fastmail settings
• Make sure you copied the full token

"Mailbox not found"

• Run list_mailboxes first to see exact folder names
• Names are case-sensitive

Tools not appearing in Claude

• Check logs: ~/Library/Logs/Claude/mcp*.log
• Make sure bun is installed: bun --version
• Try running directly: bunx fastmail-mcp-server

How It Works

Uses JMAP (JSON Meta Application Protocol) - a modern, stateless replacement for IMAP. The server implements Model Context Protocol for Claude integration.

Development

git clone https://github.com/radiosilence/fastmail-mcp-server
cd fastmail-mcp-server
bun install

# Test with your token
FASTMAIL_API_TOKEN=fmu1-... bun run test

# Run server directly
FASTMAIL_API_TOKEN=fmu1-... bun run start

# Format & lint
bun run format
bun run lint

License

MIT