fastmail-mcp

JMAP/DAV SDK

TypeScript SDK for mail (JMAP), calendar (CalDAV), and contacts (CardDAV). Provider-generic; Fastmail works out of the box. The examples below use fastmail as the import alias — any name works.

Import:

import * as fastmail from './jmap-dav-mcp/src/sdk.js';

Required env vars:

• Fastmail: FASTMAIL_USERNAME + FASTMAIL_APP_PASSWORD (or FASTMAIL_API_TOKEN alone for mail). Server URLs are implied.
• Other providers: JMAP_BASE_URL + JMAP_API_TOKEN (or JMAP_USERNAME/JMAP_PASSWORD) for mail; CALDAV_URL/CARDDAV_URL + DAV_USERNAME/DAV_PASSWORD for calendar/contacts.
• Calendar event creation also needs DAV_ORGANIZER_EMAIL (falls back to DAV_USERNAME/FASTMAIL_USERNAME).

---

Pagination

MCP tools and this SDK share the same service implementation. For complete scans use listEmailsPage, searchEmailsPage, listCalendarEventsPage, listContactsPage, or searchContactsPage. They accept the same filters as the corresponding array methods, plus position.

Pages return { items, position, total, nextPosition }. Start at position zero, keep filters unchanged, and continue until nextPosition is null. Mail allows 1 to 200 records per page and defaults to 20. DAV allows 1 to 500 and defaults to 50. Positions must be non-negative safe integers.

let position = 0;
do {
  const page = await fastmail.searchEmailsPage({ query: 'invoice', limit: 100, position });
  console.log(page.items.map(email => ({ id: email.id, subject: email.subject })));
  if (page.nextPosition === null) break;
  position = page.nextPosition;
} while (true);

Calendar and contact page methods omit raw data unless includeRaw: true. Get individual records with getCalendarEvent or getContact for full data. Existing array methods retain raw iCal and vCards by default and accept the same pagination options. Array methods return only one page, so they are unsuitable for a complete export without an explicit loop.