Fastmail MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with secure access to your Fastmail emails via the JMAP API.

Features

🔍 Search Emails: Search your emails by text query and filter by mailbox
📧 Get Email Details: Retrieve full email content including body and attachments
📁 List Mailboxes: View all your mailboxes with email counts
🔒 Secure: Uses Fastmail API tokens with proper authentication

Prerequisites

Python 3.12+
A Fastmail account
Fastmail API token (instructions below)

Getting Your Fastmail API Token

Log into your Fastmail account
Go to Settings → Privacy & Security → Integrations → API Tokens
- Or visit: https://app.fastmail.com/settings/security/tokens/new
Create a new API token with the following scopes:
- urn:ietf:params:jmap:core (Required)
- urn:ietf:params:jmap:mail (Required for email access)
Copy the generated token - you'll need it for setup

Installation

Clone or download this repository
Install dependencies:

pip install -r requirements.txt

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your Fastmail API token:

FASTMAIL_API_TOKEN=your_actual_token_here

Configuration for AI Clients

Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/absolute/path/to/fastmail_mcp.py"],
      "env": {
        "FASTMAIL_API_TOKEN": "your_fastmail_api_token_here"
      }
    }
  }
}

Replace /absolute/path/to/ with the actual path to this project.

Other MCP Clients

For other MCP-compatible clients (VS Code, Cursor, etc.), configure them to run:

python /path/to/fastmail_mcp.py

Make sure to set the FASTMAIL_API_TOKEN environment variable.

Smithery Deployment

This server is configured for deployment on Smithery, a platform for hosting and sharing MCP servers. When deployed to Smithery, users provide their Fastmail API token through Smithery's configuration flow - no token is required at build time.

Deploy to Smithery:

Push this repository to GitHub
Go to the Smithery dashboard and click "Deploy"
Select "From GitHub" and connect your repository
Smithery will build and host your server automatically

When users install your server from Smithery, they'll be prompted to enter their Fastmail API token through Smithery's secure configuration interface.

Use via Smithery CLI:

# Install Smithery CLI
npm install -g @smithery/cli

# Run the server (you'll be prompted for your API token)
smithery run @your-username/fastmail-mcp --config '{"FASTMAIL_API_TOKEN":"your_token"}'

Add to Claude Desktop via Smithery:

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@your-username/fastmail-mcp",
        "--config",
        "{\"FASTMAIL_API_TOKEN\":\"your_token_here\"}"
      ]
    }
  }
}

HTTP Mode (for Smithery/remote deployment):

The server supports both stdio (local) and HTTP (remote) transports:

# Run in HTTP mode on port 8000
python fastmail_mcp.py --http

# Run in stdio mode (default, for local use)
python fastmail_mcp.py

Available Tools

1. search_emails

Search emails in your Fastmail account.

Parameters:

query (string, optional): Search text (searches subject, body, from, to)
limit (number, optional): Max emails to return (default: 10, max: 50)
mailbox (string, optional): Filter by mailbox (e.g., "inbox", "sent", "archive")

Example usage in Claude:

"Search my emails for messages about 'project deadline'" "Show me the last 5 emails in my inbox" "Find emails from john@example.com"

2. get_email

Get the full content of a specific email.

Parameters:

email_id (string, required): The email ID from search results

Example usage in Claude:

"Show me the full content of email ID abc123" "Get the email body for that message"

3. list_mailboxes

List all mailboxes with their email counts.

Example usage in Claude:

"What mailboxes do I have?" "Show me my folders and how many emails are in each"

Testing

You can test the MCP server using the MCP Inspector:

npx @modelcontextprotocol/inspector python fastmail_mcp.py

This opens a web UI where you can manually test the tools.

Security Notes

Your API token grants full access to your Fastmail account - keep it secure
Never commit your .env file or expose your API token
The MCP server only has read access (no sending or deleting emails)
Consider creating a dedicated API token just for this MCP server

Troubleshooting

"FASTMAIL_API_TOKEN environment variable must be set"

Make sure your .env file exists and contains your API token
For Claude Desktop, ensure the token is in the config file

"401 Unauthorized"

Check that your API token is correct and hasn't been revoked
Ensure the token has the required scopes

No emails returned

Try broadening your search query
Check that the mailbox name is correct (use list_mailboxes to see available mailboxes)

API Rate Limits

Fastmail has rate limits on API requests. The MCP server handles this gracefully, but avoid making excessive requests in short periods.

License

MIT License - feel free to modify and use as needed.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

Resources

Fastmail MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with secure access to your Fastmail emails via the JMAP API.

Features

🔍 Search Emails: Search your emails by text query and filter by mailbox
📧 Get Email Details: Retrieve full email content including body and attachments
📁 List Mailboxes: View all your mailboxes with email counts
🔒 Secure: Uses Fastmail API tokens with proper authentication

Prerequisites

Python 3.12+
A Fastmail account
Fastmail API token (instructions below)

Getting Your Fastmail API Token

Log into your Fastmail account
Go to Settings → Privacy & Security → Integrations → API Tokens
- Or visit: https://app.fastmail.com/settings/security/tokens/new
Create a new API token with the following scopes:
- urn:ietf:params:jmap:core (Required)
- urn:ietf:params:jmap:mail (Required for email access)
Copy the generated token - you'll need it for setup

Installation

Clone or download this repository
Install dependencies:

pip install -r requirements.txt

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your Fastmail API token:

FASTMAIL_API_TOKEN=your_actual_token_here

Configuration for AI Clients

Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/absolute/path/to/fastmail_mcp.py"],
      "env": {
        "FASTMAIL_API_TOKEN": "your_fastmail_api_token_here"
      }
    }
  }
}

Replace /absolute/path/to/ with the actual path to this project.

Other MCP Clients

For other MCP-compatible clients (VS Code, Cursor, etc.), configure them to run:

python /path/to/fastmail_mcp.py

Make sure to set the FASTMAIL_API_TOKEN environment variable.

Smithery Deployment

Deploy to Smithery:

Push this repository to GitHub
Go to the Smithery dashboard and click "Deploy"
Select "From GitHub" and connect your repository
Smithery will build and host your server automatically

When users install your server from Smithery, they'll be prompted to enter their Fastmail API token through Smithery's secure configuration interface.

Use via Smithery CLI:

# Install Smithery CLI
npm install -g @smithery/cli

# Run the server (you'll be prompted for your API token)
smithery run @your-username/fastmail-mcp --config '{"FASTMAIL_API_TOKEN":"your_token"}'

Add to Claude Desktop via Smithery:

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@your-username/fastmail-mcp",
        "--config",
        "{\"FASTMAIL_API_TOKEN\":\"your_token_here\"}"
      ]
    }
  }
}

HTTP Mode (for Smithery/remote deployment):

The server supports both stdio (local) and HTTP (remote) transports:

# Run in HTTP mode on port 8000
python fastmail_mcp.py --http

# Run in stdio mode (default, for local use)
python fastmail_mcp.py

Available Tools

1. search_emails

Search emails in your Fastmail account.

Parameters:

query (string, optional): Search text (searches subject, body, from, to)
limit (number, optional): Max emails to return (default: 10, max: 50)
mailbox (string, optional): Filter by mailbox (e.g., "inbox", "sent", "archive")

Example usage in Claude:

"Search my emails for messages about 'project deadline'" "Show me the last 5 emails in my inbox" "Find emails from john@example.com"

2. get_email

Get the full content of a specific email.

Parameters:

email_id (string, required): The email ID from search results

Example usage in Claude:

"Show me the full content of email ID abc123" "Get the email body for that message"

3. list_mailboxes

List all mailboxes with their email counts.

Example usage in Claude:

"What mailboxes do I have?" "Show me my folders and how many emails are in each"

Testing

You can test the MCP server using the MCP Inspector:

npx @modelcontextprotocol/inspector python fastmail_mcp.py

This opens a web UI where you can manually test the tools.

Security Notes

Your API token grants full access to your Fastmail account - keep it secure
Never commit your .env file or expose your API token
The MCP server only has read access (no sending or deleting emails)
Consider creating a dedicated API token just for this MCP server

Troubleshooting

"FASTMAIL_API_TOKEN environment variable must be set"

Make sure your .env file exists and contains your API token
For Claude Desktop, ensure the token is in the config file

"401 Unauthorized"

Check that your API token is correct and hasn't been revoked
Ensure the token has the required scopes

No emails returned

Try broadening your search query
Check that the mailbox name is correct (use list_mailboxes to see available mailboxes)

API Rate Limits

Fastmail has rate limits on API requests. The MCP server handles this gracefully, but avoid making excessive requests in short periods.