Fastmail for Developers

Build against Fastmail APIs with a type-safe SDK, or plug Fastmail into AI clients through MCP.

Jump to: Use the SDK • Run the MCP server • Contribute

Why this repo exists

Fastmail exposes multiple protocols across product areas. This monorepo gives you two focused ways to build:

Package	Best for	What it gives you
fastmail-sdk	App and backend developers	Typed API for mail, calendar, files, and contacts with one SDK surface
fastmail-mcp	MCP clients and AI tooling users	Local MCP server that exposes Fastmail tools to compatible clients

Architecture at a glance

flowchart LR
  appDev["AppDeveloper"] --> sdk["fastmail_sdk"]
  aiClient["MCPClient"] --> mcp["fastmail_mcp"]
  mcp --> sdk

  sdk --> jmap["JMAP(Mail_Contacts)"]
  sdk --> caldav["CalDAV(Calendar)"]
  sdk --> webdav["WebDAV(Files)"]

Loading

Package comparison

Category	fastmail-sdk	fastmail-mcp
Primary audience	Developers building Fastmail-powered apps	Users connecting Fastmail to MCP-compatible clients
Install	bun add fastmail-sdk	bunx fastmail-mcp
Runtime	bun >= 1.3.0	bun >= 1.3.0
Core capability	Programmatic SDK clients (Mail, Calendar, Files, Contacts)	MCP tools backed by fastmail-sdk
Protocol coverage	JMAP, CalDAV, WebDAV	JMAP, CalDAV, WebDAV
Read-only mode	Implement in your app logic	Built-in --readonly flag
Tool scoping	Choose SDK clients in code	--toolsets=mail,calendar,files,contacts

Quick start (SDK-first)

1) Install dependencies

bun install

If you are using only the published SDK in another project:

bun add fastmail-sdk

2) Set credentials

Variable	Needed for	Notes
FASTMAIL_API_TOKEN	Mail + Contacts (JMAP)	Required for JMAP operations
FASTMAIL_DAV_LOGIN	Calendar + Files (DAV)	Usually your Fastmail email
FASTMAIL_DAV_PASSWORD	Calendar + Files (DAV)	Fastmail app password

3) Use the unified SDK

import { Fastmail } from "fastmail-sdk";

const fm = new Fastmail({
	apiToken: process.env.FASTMAIL_API_TOKEN,
	davLogin: process.env.FASTMAIL_DAV_LOGIN,
	davPassword: process.env.FASTMAIL_DAV_PASSWORD,
});

const [mailboxes, calendars, files, addressBooks] = await Promise.all([
	fm.mail.listMailboxes(),
	fm.calendar.listCalendars(),
	fm.files.listFiles(""),
	fm.contacts.listAddressBooks(),
]);

console.log({
	mailboxes: mailboxes.length,
	calendars: calendars.length,
	files: files.length,
	addressBooks: addressBooks.length,
});

Quick start (MCP)

One-click installs:

Canonical MCP config used by one-click installs:

{
  "fastmail": {
    "command": "npx",
    "args": ["-y", "fastmail-mcp"],
    "env": {
      "FASTMAIL_API_TOKEN": "<your_api_token>",
      "FASTMAIL_DAV_LOGIN": "<your_fastmail_email>",
      "FASTMAIL_DAV_PASSWORD": "<your_fastmail_app_password>"
    }
  }
}

Claude Desktop MCPB install steps:

1. Click the Claude button to download fastmail-mcp-latest.mcpb.
2. Open the file (or drag it into Claude Desktop) and complete install/config prompts.

Run the MCP server with all env-qualified toolsets:

bunx fastmail-mcp

Scope to selected toolsets:

bunx fastmail-mcp --toolsets=mail,calendar

Enable read-only tools only:

bunx fastmail-mcp --readonly

Development workflow

Command	What it does
bun install	Installs workspace dependencies
bun run build	Builds both packages
bun run test	Runs tests in both packages
bun run lint	Lints both packages
bun run typecheck	Type-checks both packages
bun run check	Full quality gate (lint + typecheck + test + build)
bun run dev	Builds MCP package and launches inspector workflow

Contributing

Contributions are welcome, including bug fixes, test improvements, examples, and docs polish.

Before you open a PR

Step	Command / Action
1	Create a focused branch
2	Add or update tests for behavior changes
3	Run bun run check
4	Update docs when user-facing behavior changes
5	Open PR with a clear description and validation notes

Good first contribution ideas

• Add targeted SDK examples for common Fastmail workflows
• Improve error messages and edge-case test coverage
• Expand MCP usage docs for specific client setups
• Tighten docs consistency across package READMEs

Release and quality guarantees

Guardrail	How it is enforced
Pinned runtime versions in release CI	GitHub Actions pin Bun (1.3.0) and Node (24.11.0)
Single release workflow	Publishing is handled only by .github/workflows/release.yml (Changesets flow)
Release PR safety	Changesets opens a version PR before publish so version/changelog updates are reviewed
Quality checks before publish	Each package must pass bun run check
Deterministic MCP dependency	MCP publish flow rewrites fastmail-sdk dependency to explicit repo version
OIDC-ready npm auth	Release workflow grants id-token: write for trusted publishing

Changesets release flow

1. In feature PRs, add a changeset:

bun run changeset

2. Merge changeset PRs to main.
3. GitHub Actions opens/updates a "chore: version packages" PR with version + changelog updates.
4. Merge that release PR to publish to npm automatically.
5. Manual publish workflow is retired; do not use .github/workflows/publish.yml.

Useful links

• Fastmail developer docs
• SDK package README
• MCP package README
• Cursor config source
• Claude MCPB manifest template
• SDK on npm
• MCP on npm

License

Licensed under the MIT License.