Local Fastmail MCP Server

IMPORTANT: as of April 2026, Fastmail has their own official MCP server. See the announcement at https://www.fastmail.com/blog/an-mcp-server-for-fastmail/

I'm going to archive this repository and suggest you go with the official option. I'm leaving the code online as an example of best practices for using Zod data validation, and stdio MCP development in Typescript.

A locally-hosted Model Context Protocol server that connects your Fastmail account to any MCP-compatible AI assistant (such as Claude Desktop, Cursor, or similar tools).

This integration leverages Fastmail's native JMAP API and strictly typed TypeScript/Zod schemas to allow your AI assistant to read, manage, and interact with your inbox without relying on third-party webhook integrations or exposing credentials outward.

Capabilities

Once connected, your AI assistant can use the following tools:

`list_mailboxes`

Discover all labels, folders, and mailboxes in your account. Returns each mailbox's ID, name, role, unread/total counts, and permissions.

`list_emails`

Query emails by folder, keyword search, or read/unread status. Supports pagination for large result sets.

The response includes `emails`, `total`, `position`, and `hasMore`. To page through results, increment `position` by `limit` on each call until `hasMore` is `false`.

`read_email`

Fetch the full content of a specific email by its ID.

`send_email`

Draft and send a new email from your Fastmail account.

`mark_email_read`

Mark a specific email as read or unread.

`move_email`

Transfer an email to a different mailbox/folder.

`delete_email`

Move an email to the Trash mailbox.

Security Approach

This server uses `stdio` transport exclusively — it never exposes an external HTTP port. Credentials are stored locally in your `.env` file or passed via the MCP client's environment configuration. All communication is directly between your local machine and the official `api.fastmail.com/jmap` endpoints.

Installation & Setup

1. Requirements

Ensure you have installed Node.js (version 22+ recommended) and `npm` on your local machine.

2. Configure your Fastmail API Token

1. Log into your Fastmail Account.

2. Go to `Settings` -> `Privacy & Security` -> `Connected apps & API tokens`.

3. Click _New API Token_.

4. Name the token (e.g. "AI MCP Server")

5. Provide the token the following scopes:

6. Copy the generated API token securely.

3. Local Project Setup

Clone the repository and install the required dependencies:

npm install

Copy the example environment variables file:

cp .env.example .env

Open `.env` in your text editor and paste in your credentials:

FASTMAIL_EMAIL=your_email@fastmail.com
FASTMAIL_API_TOKEN=fmu1-your-secret-token-here

4. Build the Project

Compile the TypeScript framework down into native JavaScript execution logic:

npm run build

Connecting to an MCP Client

This server works with any MCP-compatible client. Below is an example using Claude Desktop.

Claude Desktop

1. Open Claude Desktop and choose Settings -> Developer -> Edit Config

Open claude_desktop_config.json

2. Add this to the mcpServers section, fixing the path to the compiled index.js file and adding your own credentials:

{
  "mcpServers": {
    "local-fastmail": {
      "command": "node",
      "args": ["/absolute/path/to/your/local-fastmail-mcp/dist/index.js"],
      "env": {
        "FASTMAIL_EMAIL": "your_email@fastmail.com",
        "FASTMAIL_API_TOKEN": "fmu1-your-secret-token-here"
      }
    }
  }
}

3. Restart Claude Desktop. The new tools will appear instantly and you can start typing "Summarize my 20 most recent unread emails."

For other MCP clients, consult their documentation on how to register a local `stdio` server pointing at `dist/index.js` with the required environment variables.

Development & Testing

This project is built using TypeScript, `@modelcontextprotocol/sdk`, and Zod parsing.

If you are developing new Tools or making adjustments to the Fastmail capabilities:

1. Compile: Always ensure you run `npm run build` after making modifications.

2. Testing: Run the native Vitest coverage harness by executing:

npm test

Pull requests are welcome! Please open an issue first to discuss what you'd like to change. I plan to be picky, though, so also feel free to fork and make your own version.