Skip to content
Back to search

fastmail-mcp

Unofficial MCP server for the Fastmail JMAP API — email, contacts, and calendar tools for AI assistants. Not affiliated with Fastmail. Includes a DXT for Claude Desktop.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/madllama25--fastmail-mcp/badge.svg)](/listings/madllama25--fastmail-mcp)

HTML

<a href="/listings/madllama25--fastmail-mcp"><img src="/api/listings/madllama25--fastmail-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 20+ - A Fastmail account with API access - Fastmail API token

Installation

1. Clone or download this repository 2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

1. Get your Fastmail API token: - Log in to Fastmail web interface - Go to Settings → Privacy & Security - Find "Connected apps & API tokens" section - Click "Manage API tokens" - Click "New API token" - Copy the generated token

2. Set environment variables:

   export FASTMAIL_API_TOKEN="your_api_token_here"
   # Optional: customize base URL (defaults to https://api.fastmail.com)
   # Only api.fastmail.com and www.fastmailusercontent.com are accepted by default,
   # each with an optional regional prefix (phl.api.fastmail.com,
   # phl-www.fastmailusercontent.com) as returned by JMAP session discovery.
   # For self-hosted JMAP servers, also set FASTMAIL_ALLOW_UNSAFE_BASE_URL=true.
   export FASTMAIL_BASE_URL="https://api.fastmail.com"
   # Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/).
   # download_attachment savePaths are confined to this directory; set it to the root
   # you want attachments saved under to write there directly in one step.
   export FASTMAIL_DOWNLOAD_DIR="/path/to/your/downloads"

Running the Server

Start the MCP server:

npm start

For development with auto-reload:

npm run dev

Run from a clone

git clone https://github.com/MadLlama25/fastmail-mcp && cd fastmail-mcp
npm install && npm run build
FASTMAIL_API_TOKEN="your_token" node dist/index.js

> Note: `npx github:MadLlama25/fastmail-mcp` does **not** work on npm 10 (a known npm > `GitFetcher` bug). Use the clone above, or install the packaged > [Desktop Extension](#install-as-a-claude-desktop-extension-dxt).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Fastmail MCP Server (Unofficial)
  2. An **unofficial** Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data.
  3. > **Disclaimer:** This is a community project. It is **not affiliated with, endorsed by, or supported by Fastmail**. "Fastmail" is a trademark of Fastmail Pty Ltd; it is used here only to describe compatibility with their public JMAP/CalDAV/WebDAV APIs. Use at your own risk under the terms of the project license.
  4. ## Features
  5. ### Core Email Operations
  6. - List mailboxes and get mailbox statistics
  7. - List, search, and filter emails with advanced criteria
  8. - Get specific emails by ID with full content
  9. - Send emails (text and HTML) with proper draft/sent handling
  10. - Reply to emails with proper threading (In-Reply-To, References headers)
  11. - Create, edit, and send email drafts (with or without threading)
  12. - Email management: mark read/unread, delete, move between folders
  13. ### Advanced Email Features
  14. - **Attachment Handling**: List, download, and send attachments; save attachments straight to WebDAV cloud storage
  15. - **Privacy-lean metadata tools**: Metadata-only variants of list/search/thread tools (no body content)
  16. - **Threading Support**: Get complete conversation threads
  17. - **Advanced Search**: Multi-criteria filtering (sender, date range, attachments, read status)
  18. - **Bulk Operations**: Process multiple emails simultaneously
  19. - **Statistics & Analytics**: Account summaries and mailbox statistics
  20. ### Contacts Operations
  21. - List all contacts with full contact information
  22. - Get specific contacts by ID
  23. - Search contacts by name or email
  24. - Create, update, and delete contacts (JMAP ContactCard/set; requires an API token with read-write contacts scope)
  25. ### Calendar Operations
  26. - List, get, create, update, and delete calendar events (via CalDAV)
  27. - All-day and timed events, participants, recurrence-aware updates
  28. ### Label vs Move Operations
  29. - **move_email/bulk_move**: Replaces ALL mailboxes for an email (folder behavior)
  30. - **add_labels/remove_labels**: Adds/removes SPECIFIC mailboxes while preserving others (label behavior)
  31. ### Identity & Account Management
  32. - List available sending identities
  33. - Account summary with comprehensive statistics
  34. ## Setup
  35. ### Prerequisites
  36. - Node.js 20+
  37. - A Fastmail account with API access
  38. - Fastmail API token
  39. ### Installation
  40. 1. Clone or download this repository
  41. 2. Install dependencies:
  42. ```bash
  43. npm install
  44. ```
  45. 3. Build the project:
  46. ```bash
  47. npm run build
  48. ```
  49. ### Configuration
  50. 1. Get your Fastmail API token:
  51. - Log in to Fastmail web interface
  52. - Go to Settings → Privacy & Security
  53. - Find "Connected apps & API tokens" section
  54. - Click "Manage API tokens"
  55. - Click "New API token"
  56. - Copy the generated token
  57. 2. Set environment variables:
  58. ```bash
  59. export FASTMAIL_API_TOKEN="your_api_token_here"
  60. # Optional: customize base URL (defaults to https://api.fastmail.com)
  61. # Only api.fastmail.com and www.fastmailusercontent.com are accepted by default,
  62. # each with an optional regional prefix (phl.api.fastmail.com,
  63. # phl-www.fastmailusercontent.com) as returned by JMAP session discovery.
  64. # For self-hosted JMAP servers, also set FASTMAIL_ALLOW_UNSAFE_BASE_URL=true.
  65. export FASTMAIL_BASE_URL="https://api.fastmail.com"
  66. # Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/).
  67. # download_attachment savePaths are confined to this directory; set it to the root
  68. # you want attachments saved under to write there directly in one step.
  69. export FASTMAIL_DOWNLOAD_DIR="/path/to/your/downloads"
  70. ```
  71. ### Running the Server
  72. Start the MCP server:
  73. ```bash
  74. npm start
  75. ```
  76. For development with auto-reload:
  77. ```bash
  78. npm run dev
  79. ```
  80. ### Run from a clone
  81. ```bash
  82. git clone https://github.com/MadLlama25/fastmail-mcp && cd fastmail-mcp
  83. npm install && npm run build
  84. FASTMAIL_API_TOKEN="your_token" node dist/index.js
  85. ```
  86. > Note: `npx github:MadLlama25/fastmail-mcp` does **not** work on npm 10 (a known npm
  87. > `GitFetcher` bug). Use the clone above, or install the packaged
  88. > [Desktop Extension](#install-as-a-claude-desktop-extension-dxt).
  89. ## Install as a Claude Desktop Extension (DXT)
  90. You can install this server as a Desktop Extension for Claude Desktop using the packaged `.dxt` file.
  91. 1. Build and pack:
  92. ```bash
  93. npm run build
  94. npx @anthropic-ai/dxt pack
  95. ```
  96. This produces `fastmail-mcp.dxt` in the project root.
  97. 2. Install into Claude Desktop:
  98. - Open the `.dxt` file, or drag it into Claude Desktop
  99. - When prompted:
  100. - Fastmail API Token: paste your token (stored encrypted by Claude) — required
  101. - Fastmail Base URL: leave blank to use `https://api.fastmail.com` (default)
  102. - Download Directory: leave blank for `~/Downloads/fastmail-mcp/`
  103. - CalDAV Username / Password / Display Name: optional — required for calendar tools (use an app-specific password; see [CalDAV Calendar Support](#caldav-calendar-support))
  104. - WebDAV URL / Username / Password: optional — required for `save_attachment_to_webdav` (see [WebDAV file storage](#webdav-file-storage-optional))
  105. 3. Use any of the tools (e.g. `get_recent_emails`).
  106. ## Available Tools (52 Total)
  107. **Response shape for list/search tools:** the query tools (`list_emails`, `list_emails_metadata`, `search_emails`, `search_emails_metadata`, `get_recent_emails`, `advanced_search`, `advanced_search_metadata`, `list_contacts`, `search_contacts`) return a `{"total", "items"}` JSON envelope — `total` is the server-reported match count, `items` the returned page. When the server reports no total, a bare array is returned.
  108. **🎯 Most Popular Tools:**
  109. - **check_function_availability**: Check what's available and get setup guidance
  110. - **test_bulk_operations**: Safely test bulk operations with dry-run mode
  111. - **send_email**: Full-featured email sending with proper draft/sent handling
  112. - **advanced_search**: Powerful multi-criteria email filtering
  113. - **get_recent_emails**: Quick access to recent emails from any mailbox
  114. ### Email Tools
  115. - **list_mailboxes**: Get all mailboxes in your account. On accounts with many mailboxes the full output can be large — pass `properties` for a slim view.
  116. - Parameters: `properties` (optional array of fields to return), `parentId` (optional; only children of this mailbox, `null` for top level)
  117. - **get_mailbox_by_name**: Look up a mailbox by its full path from the root (e.g. `Inbox/Receipts`)
  118. - Parameters: `path` (required)
  119. - **create_mailbox**: Create a new mailbox (folder/label)
  120. - Parameters: `name` (required), `parentId` (optional, omit or null for top level)
  121. - **list_emails**: List emails from a specific mailbox or all mailboxes
  122. - Parameters: `mailboxId` (optional), `limit` (default: 20, max: 100), `ascending` (optional, oldest first)
  123. - **list_emails_metadata**: List emails from a mailbox, metadata only (headers, no body content)
  124. - Parameters: `mailboxId` (optional), `limit` (default: 20, max: 100), `ascending` (optional, oldest first)
  125. - **get_email**: Get a specific email by ID
  126. - Parameters: `emailId` (required)
  127. - **get_email_metadata**: Get a specific email's metadata only (allowlisted headers, no body)
  128. - Parameters: `emailId` (required)
  129. - **send_email**: Send an email (supports threading via optional `inReplyTo` and `references` headers)
  130. - Parameters: `to` (required — array or comma-separated string), `cc` (optional array), `bcc` (optional array), `from` (optional), `mailboxId` (optional), `subject` (required), `textBody` (optional), `htmlBody` (optional), `inReplyTo` (optional array), `references` (optional array), `replyTo` (optional array), `attachments` (optional array — see [Email attachments on send](#email-attachments-on-send))
  131. - **reply_email**: Reply to an existing email with proper threading headers (automatically builds In-Reply-To and References). Set `send=false` to save as draft instead of sending.
  132. - Parameters: `originalEmailId` (required), `to` (optional array, defaults to original sender), `cc` (optional array), `bcc` (optional array), `from` (optional), `textBody` (optional), `htmlBody` (optional), `send` (optional boolean, default: true), `replyTo` (optional array), `attachments` (optional array — see [Email attachments on send](#email-attachments-on-send))
  133. - **create_draft**: Create an email draft (at least one of to/subject/body/attachments required; supports threading headers for reply drafts)
  134. - Parameters: `to` (optional array), `cc` (optional array), `bcc` (optional array), `from` (optional), `mailboxId` (optional), `subject` (optional), `textBody` (optional), `htmlBody` (optional), `replyTo` (optional array), `inReplyTo` (optional array), `references` (optional array), `attachments` (optional array — see [Email attachments on send](#email-attachments-on-send))
  135. - **edit_draft**: Edit an existing draft in place — only provided fields change; existing attachments are preserved
  136. - Parameters: `emailId` (required), `to`, `cc`, `bcc`, `from`, `subject`, `textBody`, `htmlBody`, `replyTo`, `attachments` (all optional)
  137. - **send_draft**: Send an existing draft
  138. - Parameters: `emailId` (required)
  139. - **search_emails**: Search emails by content
  140. - Parameters: `query` (required), `limit` (default: 20, max: 100), `ascending` (optional, oldest first), `excludeDrafts` (optional, omit draft messages)
  141. - Drafts are **included by default**. Set `excludeDrafts: true` to filter them out server-side.
  142. - Searches **all mailboxes including Trash and Spam**. For cleanup/verification flows, exclude the Trash mailbox explicitly (e.g. `advanced_search` with `excludeMailboxIds`) rather than trusting a bare search count.
  143. - **get_recent_emails**: Get the most recent emails (inspired by JMAP-Samples top-ten)
  144. - Parameters: `limit` (default: 10, max: 50), `mailboxName` (optional), `ascending` (optional, oldest first)
  145. - When `mailboxName` is omitted, all mailboxes are searched **except Trash and Spam**. Pass a mailbox name (e.g. `'inbox'`, `'sent'`) to scope to one folder.
  146. - **search_emails_metadata**: Search emails by content, returning metadata only
  147. - Parameters: `query` (required), `limit` (default: 20, max: 100), `ascending` (optional, oldest first)
  148. - **mark_email_read**: Mark an email as read or unread
  149. - Parameters: `emailId` (required), `read` (default: true)
  150. - **pin_email**: Pin or unpin an email
  151. - Parameters: `emailId` (required), `pinned` (default: true)
  152. - **archive_email**: Archive an email — moves it and marks it read in one atomic step
  153. - Parameters: `emailId` (required), `targetMailboxId` (required)
  154. - **delete_email**: Delete an email (move to trash)
  155. - Parameters: `emailId` (required)
  156. - **move_email**: Move an email to a different mailbox (replaces all mailboxes)
  157. - Parameters: `emailId` (required), `targetMailboxId` (required)
  158. - **add_labels**: Add labels (mailboxes) to an email without removing existing ones
  159. - Parameters: `emailId` (required), `mailboxIds` (required array)
  160. - **remove_labels**: Remove specific labels (mailboxes) from an email
  161. - Parameters: `emailId` (required), `mailboxIds` (required array)
  162. ### Advanced Email Features
  163. - **get_email_attachments**: Get list of attachments for an email
  164. - Parameters: `emailId` (required)
  165. - **download_attachment**: Download an email attachment. If savePath is provided, saves the file to disk and returns the file path and size. Otherwise returns a download URL.
  166. - Parameters: `emailId` (required), `attachmentId` (required), `savePath` (optional)
  167. - `savePath` may be absolute or relative. Relative paths (including a bare filename) resolve against the download directory, so an attachment lands there in one step. Absolute paths must fall within that directory; traversal or symlink escape outside it is rejected. To save directly into your own location, set `FASTMAIL_DOWNLOAD_DIR` to that root — confinement stays on, scoped to the directory you choose.
  168. - **save_attachment_to_webdav**: Save an attachment directly to WebDAV cloud storage (Fastmail Files, Nextcloud, ...) without touching local disk
  169. - Parameters: `emailId` (required), `attachmentId` (required), `remotePath` (required, relative), `overwrite` (default false), `createParents` (default true)
  170. - The storage server and credentials come from `FASTMAIL_WEBDAV_*` env config; the tool only chooses the relative path beneath that base. Existing files are never replaced unless `overwrite: true`.
  171. - **advanced_search**: Advanced email search with multiple criteria
  172. - Parameters: `query` (optional), `from` (optional), `to` (optional), `subject` (optional), `hasAttachment` (optional), `isUnread` (optional), `isPinned` (optional), `mailboxId` (optional), `requiredMailboxIds` (optional array — email must be in ALL of these), `excludeMailboxIds` (optional array — exclude emails in any of these), `after` (optional), `before` (optional), `limit` (default: 50, max: 100), `ascending` (optional, oldest first)
  173. - Like `search_emails`, searches **all mailboxes including Trash and Spam** — scope with `mailboxId`/`excludeMailboxIds` when that matters. (`get_recent_emails` is the one that excludes Trash/Spam by default.)
  174. - **advanced_search_metadata**: Same filters as `advanced_search`, metadata-only results (no body content)
  175. - **get_thread**: Get all emails in a conversation thread
  176. - Parameters: `threadId` (required), `includeDrafts` (optional, include in-progress drafts)
  177. - Draft messages are **excluded by default** (an in-progress reply is noise when reading a conversation). Set `includeDrafts: true` to include them. Drafts are identified by the `$draft` keyword, so the asymmetry with `search_emails` (which includes drafts by default) is deliberate: a search should still find everything you've written.
  178. - **get_thread_metadata**: Get all emails in a thread, metadata only. Also accepts an email ID and resolves its parent thread.
  179. - Parameters: `threadId` (required), `includeDrafts` (optional)
  180. ### Email Statistics & Analytics
  181. - **get_mailbox_stats**: Get statistics for a mailbox (unread count, total emails, etc.)
  182. - Parameters: `mailboxId` (optional, defaults to all mailboxes)
  183. - **get_account_summary**: Get overall account summary with statistics
  184. ### Bulk Operations
  185. - **bulk_mark_read**: Mark multiple emails as read/unread
  186. - Parameters: `emailIds` (required array), `read` (default: true)
  187. - **bulk_pin**: Pin or unpin multiple emails
  188. - Parameters: `emailIds` (required array), `pinned` (default: true)
  189. - **bulk_move**: Move multiple emails to a mailbox
  190. - Parameters: `emailIds` (required array), `targetMailboxId` (required)
  191. - **bulk_delete**: Delete multiple emails (move to trash)
  192. - Parameters: `emailIds` (required array)
  193. - **bulk_add_labels**: Add labels to multiple emails simultaneously
  194. - Parameters: `emailIds` (required array), `mailboxIds` (required array)
  195. - **bulk_remove_labels**: Remove labels from multiple emails simultaneously
  196. - Parameters: `emailIds` (required array), `mailboxIds` (required array)
  197. ### Contact Tools
  198. - **list_contacts**: List all contacts
  199. - Parameters: `limit` (default: 50, max: 200)
  200. - **get_contact**: Get a specific contact by ID
  201. - Parameters: `contactId` (required)
  202. - **search_contacts**: Search contacts by name or email
  203. - Parameters: `query` (required), `limit` (default: 20, max: 100)
  204. - **create_contact**: Create a new contact (requires read-write contacts scope on the API token)
  205. - Parameters: `name` `{given, surname, full}`, `emails` `[{address, label}]`, `phones` `[{number, label}]`, `addresses` `[{full, label}]`, `notes`, `addressBookId` (all optional, but a name or one email is required)
  206. - **update_contact**: Update an existing contact — each provided field **wholly replaces** the stored value (`emails: []` removes all emails); unspecified fields are untouched
  207. - Parameters: `contactId` (required), same fields as create, `expectState` (optional JMAP state precondition)
  208. - **delete_contact**: Permanently delete a contact (cannot be undone)
  209. - Parameters: `contactId` (required), `expectState` (optional)
  210. ### Calendar Tools
  211. - **list_calendars**: List all calendars
  212. - **list_calendar_events**: List calendar events (core fields only — no participants for token efficiency)
  213. - Parameters: `calendarId` (optional), `startDate` (optional, ISO 8601), `endDate` (optional, ISO 8601), `limit` (default: 50, max: 500)
  214. - **get_calendar_event**: Get a specific calendar event by ID. Returns organizer and participants when available.
  215. - Parameters: `eventId` (required)
  216. - **create_calendar_event**: Create a new calendar event. Supports date-only (e.g. `2026-04-01`) for all-day events. DTEND is exclusive per RFC 5545 — a one-day event on April 1 needs `end: "2026-04-02"`.
  217. - Parameters: `calendarId` (required), `title` (required), `description` (optional), `start` (required, ISO 8601 or date-only), `end` (required, ISO 8601 or date-only), `location` (optional), `participants` (optional array of `{email, name?}`)
  218. - **update_calendar_event**: Patch an existing calendar event. Preserves all existing data (attendees, reminders, recurrence rules, etc.) not being changed. Omit a field to leave it unchanged; passing an empty or whitespace-only string for `title`, `description`, or `location` is rejected (it won't silently blank the property). To delete `description` or `location`, list them in `clearFields`. Floating times (no Z/offset) preserve the original timezone. WARNING: providing `participants` replaces ALL existing attendee data; `participants: []` removes all attendees (and the now-orphaned ORGANIZER).
  219. - Parameters: `eventId` (required), `title`, `description`, `start`, `end`, `location`, `participants` (array of `{email, name?}`), `clearFields` (array of `"description"`/`"location"` to delete), `confirmRecurring` (boolean)
  220. - **delete_calendar_event**: Delete a calendar event
  221. - Parameters: `eventId` (required)
  222. #### Calendar known limitations
  223. - **Recurring events**: Only "all events" modification is supported (master VEVENT). "This event only" or "this and future events" are not supported. Changing start/end on recurring events with exception overrides requires `confirmRecurring: true` — orphaned exceptions are pruned to prevent server errors.
  224. - **Attendee parameters**: RSVP, ROLE, CUTYPE and other attendee parameters are parsed on read but not settable on create/update — only `email` and `name` are accepted.
  225. ### Identity & Testing Tools
  226. - **list_identities**: List sending identities (email addresses that can be used for sending)
  227. - **check_function_availability**: Check which functions are available based on account permissions (includes setup guidance). Calendar tools run over CalDAV, so calendar is reported available when CalDAV credentials are configured, regardless of the JMAP calendar capability.
  228. - **test_bulk_operations**: Safely test bulk operations with dry-run mode
  229. - Parameters: `dryRun` (default: true), `limit` (default: 3)
  230. ## API Information
  231. This server uses the JMAP (JSON Meta Application Protocol) API provided by Fastmail. JMAP is a modern, efficient alternative to IMAP for email access.
  232. ### Inspired by Fastmail JMAP-Samples
  233. Many features in this MCP server are inspired by the official [Fastmail JMAP-Samples](https://github.com/fastmail/JMAP-Samples) repository, including:
  234. - Recent emails retrieval (based on top-ten example)
  235. - Email management operations
  236. - Efficient chained JMAP method calls
  237. ### Authentication
  238. The server uses bearer token authentication with Fastmail's API. API tokens provide secure access without exposing your main account password.
  239. ### Rate Limits
  240. Fastmail applies rate limits to API requests. The server handles standard rate limiting, but excessive requests may be throttled.
  241. ## CalDAV Calendar Support
  242. Fastmail does not currently expose calendar access via JMAP API tokens — the `urn:ietf:params:jmap:calendars` scope is not available because the JMAP Calendars specification is still an IETF Internet-Draft ([draft-ietf-jmap-calendars](https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/)). Fastmail has stated they will add JMAP calendar support once the spec becomes an RFC, but there is no public timeline.
  243. However, Fastmail fully supports **CalDAV** for calendar access via `caldav.fastmail.com`. All calendar tools use CalDAV directly.
  244. ### Setup
  245. 1. Create an app-specific password on Fastmail:
  246. - Go to **Settings → Privacy & Security → Manage app passwords**
  247. - Create a new app password (you can name it "CalDAV MCP" or similar)
  248. 2. Set the following environment variables:
  249. ```bash
  250. export FASTMAIL_CALDAV_USERNAME="your-email@fastmail.com"
  251. export FASTMAIL_CALDAV_PASSWORD="your-app-specific-password"
  252. # Optional: display name for ORGANIZER when creating events with participants
  253. export FASTMAIL_CALDAV_DISPLAY_NAME="Your Name"
  254. ```
  255. When these variables are set, all calendar tools are available. When they are not set, calendar tools will return an error with setup instructions.
  256. ### WebDAV file storage (optional)
  257. `save_attachment_to_webdav` saves attachments straight to cloud storage. Configure the target (never supplied by tools at runtime — this is deliberate, so a misbehaving caller cannot redirect uploads):
  258. ```bash
  259. # Fastmail Files:
  260. export FASTMAIL_WEBDAV_URL="https://myfiles.fastmail.com/"
  261. export FASTMAIL_WEBDAV_USERNAME="your-email@fastmail.com"
  262. export FASTMAIL_WEBDAV_PASSWORD="app-password-with-files-scope"
  263. # ...or any WebDAV server, e.g. Nextcloud:
  264. # export FASTMAIL_WEBDAV_URL="https://cloud.example.com/remote.php/dav/files/USERNAME/"
  265. ```
  266. The URL must be HTTPS. Note: Fastmail Files ignores the WebDAV `If-None-Match` precondition, so the tool performs an explicit existence check before non-overwrite uploads.
  267. ### Email attachments on send
  268. `send_email`, `create_draft`, `edit_draft`, and `reply_email` accept an `attachments` array. Each entry uses exactly one source:
  269. - `{ "localPath": "report.pdf" }` — a file inside `FASTMAIL_DOWNLOAD_DIR` (same confinement as downloads)
  270. - `{ "emailId": "...", "attachmentId": "..." }` — re-attach from an existing email (zero-copy: no bytes are transferred)
  271. - `{ "blobId": "...", "name": "...", "type": "..." }` — an already-uploaded JMAP blob
  272. Uploads respect the server's `maxSizeUpload` (~50 MB on Fastmail). Editing a draft preserves its existing attachments.
  273. ### Contacts write scope
  274. `create_contact` / `update_contact` / `delete_contact` need the API token to have **read-write** contacts scope (Settings → Privacy & Security → API tokens). Read-only tokens keep the three read tools working and fail writes with a `forbidden` error.
  275. ## Development
  276. ### Project Structure
  277. ```
  278. src/
  279. ├── index.ts # Main MCP server implementation
  280. ├── auth.ts # Authentication handling
  281. ├── jmap-client.ts # JMAP client wrapper
  282. ├── contacts-calendar.ts # Contacts extensions (JMAP)
  283. ├── caldav-client.ts # CalDAV calendar client (the calendar path — JMAP calendars are not available)
  284. ├── webdav-files-client.ts # WebDAV file storage client (save_attachment_to_webdav)
  285. ├── url-validation.ts # Base-URL allowlist / HTTPS validation
  286. ├── coerce.ts # Input coercion helpers
  287. └── *.test.ts # Unit tests (colocated)
  288. ```
  289. ### Building
  290. ```bash
  291. npm run build
  292. ```
  293. ### Development Mode
  294. ```bash
  295. npm run dev
  296. ```
  297. ## License
  298. MIT
  299. ## Contributing
  300. Contributions are welcome! Please ensure that:
  301. 1. Code follows the existing style
  302. 2. All functions are properly typed
  303. 3. Error handling is implemented
  304. 4. Documentation is updated for new features
  305. ## Troubleshooting
  306. ### Common Issues
  307. 1. **Authentication Errors**: Ensure your API token is valid and has the necessary permissions
  308. 2. **Missing Dependencies**: Run `npm install` to ensure all dependencies are installed
  309. 3. **Build Errors**: Check that TypeScript compilation completes without errors using `npm run build`
  310. 4. **Calendar/Contacts "Forbidden" Errors**: Use `check_function_availability` to see setup guidance
  311. ### Email Tools Failing with Serialization Errors?
  312. If `get_email`, `list_emails`, `search_emails`, or `advanced_search` fail with "content serialization" or "Cannot read properties of undefined" errors, upgrade to v1.7.1 or later (any current release includes the fix). This was caused by incomplete JMAP response validation that surfaced after the MCP SDK v1.x upgrade added stricter result checking.
  313. ### Calendar Not Working?
  314. Calendar tools run over CalDAV, not JMAP. If they return "CalDAV not configured", set `FASTMAIL_CALDAV_USERNAME` and `FASTMAIL_CALDAV_PASSWORD` (see [CalDAV Calendar Support](#caldav-calendar-support)).
  315. ### Contacts Not Working?
  316. If contacts functions return "Forbidden" errors:
  317. 1. **API Token Scope**: writes (`create_contact`/`update_contact`/`delete_contact`) need read-write contacts scope (see [Contacts write scope](#contacts-write-scope))
  318. 2. **Account Plan**: the contacts API may require certain Fastmail plans
  319. `Contact not found` / `Calendar event not found` errors mean the ID is stale — re-list and retry.
  320. **Solution**: Run `check_function_availability` for step-by-step setup guidance.
  321. ### Testing Your Setup
  322. Use the built-in testing tools:
  323. - **check_function_availability**: See what's available and get setup help
  324. - **test_bulk_operations**: Safely test bulk operations without making changes
  325. For more detailed error information, check the console output when running the server.
  326. ## Privacy & Security
  327. - API tokens are stored encrypted by Claude Desktop when installed via the DXT and are never logged by this server.
  328. - The server avoids logging raw errors and sensitive data (tokens, email addresses, identities, attachment names/blobIds) in error messages.
  329. - Tool responses may include your email metadata/content by design (e.g., listing emails) but internal identifiers and credentials are not disclosed beyond what Fastmail returns for the requested data.
  330. - If you encounter errors, messages are sanitized and summarized to prevent leaking personal information.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.