playbooks

home / mcp / fastmail mcp server

FastMail MCP Server

Provides an MCP interface to read, search, and send emails via FastMail's JMAP API.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "jmhron-fastmailmcp": {
      "command": "python",
      "args": [
        "fastmail_mcp_server.py"
      ],
      "env": {
        "MCP_DEBUG": "1"
      }
    }
  }
}

This MCP server lets you integrate with FastMail using the JMAP API to read, search, organize, and send emails. It provides practical, scriptable access to your FastMail account from MCP clients, enabling you to list mailboxes, fetch emails with previews, perform advanced searches, and send messages programmatically.

How to use

You use this server by connecting an MCP client to it. After you configure your FastMail credentials, you can list all mailboxes, read emails from a chosen folder, perform targeted searches with multiple filters, retrieve full email bodies, and send messages with optional CC and BCC recipients. Each action maps to a specific MCP command that you issue through your client, and responses come back in the MCP protocol format.

How to install

Prerequisites: you need Python 3.8 or later and a FastMail account with API access. You also need an API token from FastMail (Settings ā†’ Privacy & Security ā†’ Integrations).

Step-by-step commands to get started:

git clone <your-repo-url>
cd fastmail_mcp_server

pip install -r requirements.txt

# Obtain your FastMail API token as described in the prerequisites
# Then configure the server with your token as needed by the setup tooling

python fastmail_mcp_server.py

Configuration and usage notes

Configure your FastMail credentials before starting the server. Provide the API token you generated from FastMail so the MCP server can authenticate requests.

You can start the server with the runtime command shown above. It will listen for MCP commands via standard input/output.

Debug and troubleshooting: you can enable debug logging by setting the MCP_DEBUG environment variable before running the server, which helps diagnose connectivity or authentication issues.

Security and notes

Keep your API token secure. Do not commit tokens to version control. The token has access to your FastMail account and should be kept private. All communications with FastMail use HTTPS.

Troubleshooting

Common problems include authentication errors due to an invalid or expired API token, connection failures caused by network issues, or missing emails if you are querying the wrong mailbox or filters. Enable debug logging to get more insight into the issue by setting MCP_DEBUG to a non-empty value before starting the server.

Contributing and license

Contributions are encouraged. Follow standard contribution practices: fork, create a feature branch, implement changes, add tests if applicable, and open a pull request.

Available tools

configure_fastmail

Set up your FastMail API credentials by providing the apiToken through the configuration tool.

list_mailboxes

List all mailboxes with their names, roles, and email counts.

find_mailbox

Find a specific mailbox by name or role with optional partial matching.

get_emails

Fetch emails from a specific mailbox with options to limit results and include the body.

search_emails

Perform advanced searches across emails with filters like keyword, sender, subject, mailbox, attachments, and date range.

get_email_body

Retrieve the full body content of a specific email in text, html, or both formats.

send_email

Send an email through FastMail with optional CC and BCC fields and HTML support.