{"id":"bef0881a-6b2a-44d3-b5de-fff5f4b8fbb8","slug":"mcp-fastmail","kind":"mcp","name":"mcp-fastmail","summary":"Fastmail MCP server with a safety net: 91 tools over JMAP, CalDAV and WebDAV. Dry run, confirm threshold, undo for bulk work, an agent skill. Fork of MadLlama25/fastmail-mcp.","owner":"Fundryi","repoUrl":"https://github.com/Fundryi/mcp-fastmail","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-24T06:56:35.000Z","addedAt":"2026-10-21T05:01:57.254Z","logoUrl":"https://avatars.githubusercontent.com/u/19733372?u=38c83554e97c8c15ada82143d644fb366fb6018c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","productivity","memory-knowledge"],"tags":["ai-agents","caldav","claude","email","fastmail","jmap","typescript"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T11:04:25.904Z","sample":false,"url":"https://conduits.dev/tools/mcp-fastmail","language":"TypeScript","transports":["stdio"],"install":{"npm":"fastmail-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Fastmail MCP\n\nAn unofficial [MCP](https://modelcontextprotocol.io) server for Fastmail. It gives an AI assistant your mail, folders, contacts, calendars and files over JMAP, CalDAV and WebDAV, with a safety net under every write.\n\nBuilt on [MadLlama25/fastmail-mcp](https://github.com/MadLlama25/fastmail-mcp) by Jeremy Gill, MIT. Upstream's 52 tools are all here; 15 of them are re-implemented under the same names with more arguments and a safety net, and 39 are new. On top: an agent skill, and instructions the server sends to every client on connect. Upstream's original README is kept in full at [docs/UPSTREAM-README.md](docs/UPSTREAM-README.md).\n\n> Not affiliated with, endorsed by, or supported by Fastmail. \"Fastmail\" is a trademark of Fastmail Pty Ltd, used here only to describe compatibility with their public APIs. Use at your own risk under the MIT license.\n\n## Why this one\n\nThree servers can put Fastmail in front of an AI. Each is a step up from the last.\n\n| | Fastmail's own MCP | Upstream fork | This fork |\n|---|:---:|:---:|:---:|\n| Tools | 30 | 52 | 91 |\n| Read, search, send mail | Yes | Yes | Yes |\n| Gmail-style search string | No | No | Yes |\n| Folders: create, rename, move | No | Create only | Yes, plus merge, delete with contents moved, subtree patch |\n| Bulk move, delete, label | No | Yes | Yes |\n| Dry run before every bulk write | No | Test tool only | Yes, on every bulk tool |\n| Confirm gate above a threshold | No | No | Yes |\n| Undo a bulk operation | No | No | Yes, last 50 |\n| Audit log of bulk writes | No | No | Yes, optional file |\n| Read-only mode | No | No | Yes |\n| Reply from the alias that received the mail | No | No | Yes, catch-all included |\n| Scheduled send, list, cancel | No | No | Yes |\n| Snooze, forward, unsubscribe, report spam | No | No | Yes |\n| One-time codes, duplicates, per-sender summary, unread across a tree | No | No | Yes |\n| Identities, masked email, aliases with usage, quota, change tracking | No | Identities only | Yes |\n| Contacts | Directory search | Yes | Yes |\n| Calendar | Yes | Yes, over CalDAV | Yes, over CalDAV or passthrough |\n| Notes, email memos, company directory, RSVP | Yes | No | Yes, via passthrough to Fastmail's MCP |\n| Server instructions sent on connect | No | No | Yes |\n| Agent skill included | No | No | Yes |\n| Structured errors an agent can branch on | No | Partly | Yes |\n| Permanent delete by default | Yes, confirm widget | Trash | Trash; destroy needs confirm |\n| Runs where | Fastmail's cloud, HTTP | Your machine | Your machine, optional cloud passthrough |\n| Token type | MCP | JMAP API token | JMAP API token, optional MCP token |\n\nFastmail's own MCP is the only one that reaches Notes and the company directory. This fork wraps it, so you lose nothing by starting here.\n\n## Contents\n\n- [Why this one](#why-this-one)\n- [What you get](#what-you-get)\n- [Quick start](#quick-start)\n- [Configuration](#configuration)\n- [Safety model](#safety-model)\n- [Tools at a glance](#tools-at-a-glance)\n- [For AI agents](#for-ai-agents)\n- [What Fastmail does not allow](#what-fastmail-does-not-allow)\n- [Development](#development)\n- [Staying current with upstream](#staying-current-with-upstream)\n- [Credits and license](#credits-and-license)\n\n## What you get\n\n| Area | Highlights |\n|---|---|\n| Mail | List, search with Gmail-style queries, read threads with bodies, one-time codes, duplicates, attachments, unread counts across a folder tree, per-sender summaries |\n| Folders | Create, rename, move, subscribe, merge, delete with contents moved first, one patch across a whole subtree |\n| Bulk | Move, delete, label, read, pin. Every call has a dry run, a confirm threshold, an operation log and undo |\n| Sending | Send and reply from the right alias, catch-all identities included. Schedule, list scheduled, cancel, forward, snooze |\n| Account | Identities, masked email, aliases with usage, quota, session capabilities, change tracking |\n| Contacts, calendar, files | Upstream's JMAP contacts, CalDAV calendars and WebDAV file save, untouched |\n| Optional | A passthrough to Fastmail's own MCP server for Notes, email memos, the company directory and calendar RSVP |\n\n## Quick start\n\nNeeds Node.js 20 or newer and a Fastmail API token. Create the token at Fastmail, Settings, Privacy & Security, Integrations, API tokens. Give it the scopes you plan to use: Email, Email submission, Contacts, Masked Email.\n\n```bash\ngit clone https://github.com/Fundryi/mcp-fastmail.git && cd mcp-fastmail\nnpm ci\nnpm run build\ncp .env.example .env    # then put your token in FASTMAIL_API_TOKEN\nnode dist/index.js\n```\n\nRegister the server in your MCP client as a stdio command, `node /path/to/fastmail-mcp/dist/index.js`, with the variables from `.env` in its environment. The client's own tool prefix goes in front of every tool name.\n\nThe server speaks MCP 2026-07-28, the stateless revision, and every older revision from 2024-10-07 to 2025-11-25. The same command serves both; the client's first message picks the revision. It is built on the MCP TypeScript SDK v2 (`@modelcontextprotocol/server`).\n\nFor Claude Desktop, `npx @anthropic-ai/dxt pack` after the build produces a `.dxt` file you can drag into the app. It asks for the token and the optional CalDAV and WebDAV settings.\n\n### Running it on another machine\n\nInstalled locally, attachments take `localPath` and nothing else is needed. Behind MCPHub or any other remote host, the server cannot see the caller's disk, and MCP has no file upload yet. Attachments then take base64 `content`, `download_attachment` takes `base64: true`, and large files go through a one-file helper that keeps them out of the model's context. See [docs/REMOTE-FILES.md](docs/REMOTE-FILES.md). A `localPath` the server cannot find fails with a pointer to that guide.\n\n## Configuration\n\nEvery variable is documented in [.env.example](.env.example). The short version:\n\n| Variable | Needed for |\n|---|---|\n| `FASTMAIL_API_TOKEN` | Everything. Required |\n| `FASTMAIL_CALDAV_USERNAME`, `FASTMAIL_CALDAV_PASSWORD` | Calendar tools. An app password, not the API token |\n| `FASTMAIL_WEBDAV_URL`, `FASTMAIL_WEBDAV_USERNAME`, `FASTMAIL_WEBDAV_PASSWORD` | `save_attachment_to_webdav` |\n| `FASTMAIL_DOWNLOAD_DIR` | Where attachments may be written. Default `~/Downloads/fastmail-mcp/` |\n| `FASTMAIL_READ_ONLY=1` | Refuse every tool that writes. Good for a check-only session |\n| `FASTMAIL_BULK_CONFIRM_THRESHOLD` | Bulk calls above this many mails need `confirm: true`. Default 100 |\n| `FASTMAIL_AUDIT_LOG` | Append one JSON line per bulk operation to this file |\n| `FASTMAIL_MCP_TOKEN` | A second token of type MCP. Turns on the `official_*` passthrough |\n\n## Safety model\n\nA tool never changes more than the caller asked for, and never hides how much it destroys.\n\n- **Dry run, then confirm.** Every bulk tool takes `dryRun: true` and answers with the count and a sample of ids. Above the confirm threshold the real run needs `confirm: true`.\n- **Undo.** Every bulk call returns an `operationId`. `undo_operation` puts the previous folders and keywords back. `list_operations` shows the last 50 of the process.\n- **Echo what was stored.** Writes re-fetch and return the object as the server has it, not as it was sent.\n- **Trash, not destroy.** `delete_email` and `bulk_delete` move to Trash. The only permanent destroys are `empty_mailbox` (Trash or Junk only) and `delete_mailbox`, and both need `confirm: true` and say so.\n- **Structured refusals.** A refused or failed call comes back as a tool result with `isError: true` and a JSON body: the JMAP error type, or `needsConfirm`, `count` and `threshold`, `readOnly`, or the missing `capability`. The model sees it and can fix its call. Only an unknown tool name is a protocol error. Nothing is swallowed, and tokens are redacted.\n- **Read-only labels.** Every tool carries the `readOnlyHint` annotation, from the same flag that `FASTMAIL_READ_ONLY` uses. A host can ask before each write and let reads through.\n\n## Tools at a glance\n\n91 tools. The full reference with every parameter is generated from the server itself: [docs/TOOLS.md](docs/TOOLS.md).\n\n| Group | Tools |\n|---|---|\n| Find mail | `search_emails` (Gmail-style string), `advanced_search`, `list_emails`, `get_recent_emails`, `list_unread_across`, `summarize_mailbox`, `find_duplicates`, `extract_codes`, `list_attachments` |\n| Read mail | `get_email`, `get_thread`, `get_email_metadata`, `get_email_attachments`, `download_attachment` |\n| Change mail | `move_email`, `mark_email_read`, `archive_email`, `pin_email`, `add_labels`, `remove_labels`, `report_spam`, `report_not_spam`, `unsubscribe`, `snooze_email`, `import_email` |\n| Bulk | `bulk_move`, `bulk_delete`, `bulk_mark_read`, `bulk_pin`, `bulk_add_labels`, `bulk_remove_labels`, `list_operations`, `undo_operation`, `export_operation_log` |\n| Folders | `list_mailboxes`, `get_mailbox`, `get_mailbox_by_name`, `create_mailbox`, `update_mailbox`, `bulk_update_mailboxes`, `merge_mailbox`, `delete_mailbox`, `empty_mailbox` |\n| Send | `send_email`, `reply_email`, `forward_email`, `create_draft`, `edit_draft`, `send_draft`, `list_scheduled`, `cancel_send` |\n| Account | `get_session`, `get_account_summary`, `list_identities`, `create_identity`, `update_identity`, `list_aliases_with_usage`, masked email, vacation responder, sieve, `get_quota`, `get_changes` |\n| Contacts and calendar | `list_contacts`, `search_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact`, `list_address_books`, `list_calendars`, `list_calendar_events`, `create_calendar_event`, `update_calendar_event`, `delete_calendar_event` |\n| Official passthrough | `official_create_note`, `official_search_notes`, `official_set_memo`, `official_search_org_contacts`, `official_rsvp_event` and friends. Only with `FASTMAIL_MCP_TOKEN` |\n\nSieve, quota and the vacation responder exist as tools, but a plain API token has no capability for them. They refuse and name the missing capability. See [What Fastmail does not allow](#what-fastmail-does-not-allow).\n\n## For AI agents\n\nThree things teach an agent to use this server well. Each works alone; together they are best.\n\n1. **Server instructions.** The server sends a short guide on connect: which tool fits which task, how to keep results small, the dry run then confirm flow. Every MCP client that honours `instructions` gets it for free. Source: [src/fork/instructions.ts](src/fork/instructions.ts).\n2. **The skill.** [skills/fastmail-mcp/SKILL.md](skills/fastmail-mcp/SKILL.md) is the long form with recipes and a checklist for folder work. Copy the folder into your agent's skills directory. It names tools by their bare name and does not depend on any one client.\n3. **[llms.txt](llms.txt).** An index of the files an agent should read when it works on this repo rather than through it.\n\nEach tool also says whether it writes (`readOnlyHint`), and [docs/TOOLS.md](docs/TOOLS.md) marks every entry *Read-only.* or *Writes.*\n\n## What Fastmail does not allow\n\nChecked live against a real account. These are limits of the API token, not of this server.\n\n| Want | Reality | Instead |\n|---|---|---|\n| Folder colour | Not in JMAP. The server rejects the property | Web app |\n| Identity link, auto purge, spam learning on a folder | Read-only over JMAP. `get_mailbox` shows them | Web app, folder settings |\n| Sieve rules, quota, vacation responder | No such scope on an API token | Web app |\n| DKIM and MX status | No API | A DNS lookup on the domain |\n| Notes, email memos, company directory, RSVP | Not in JMAP token scopes | The `official_*` passthrough with a token of type MCP |\n| Snooze before the Snoozed folder exists | Fastmail creates it on first use | Snooze one mail in the web app once |\n| Push on new mail | MCP has no long-running process | A cron job calling `get_changes` |\n\n## Development\n\nTypeScript, npm, Node 20 or newer.\n\n```bash\nnpm ci\nnpm run build          # tsc to dist/\nnpm test               # node test runner over src/*.test.ts and src/fork/*.test.ts\nnpm run scan:secrets   # upstream's secret and PII scanner, run before every push\nnpm run docs:tools     # regenerate docs/TOOLS.md from the built server\n```\n\nTests mock the transport. They prove the shape of a call, not that Fastmail accepts it. Anything that touches the network gets a live run before it is called done. On Windows, three upstream symlink tests fail without Developer Mode; everything else must be green.\n\nLayout:\n\n```\nsrc/index.ts          upstream's server, plus a few hook lines for the fork\nsrc/fork/             every fork tool, one file per group, and the registry\nsrc/fork/instructions.ts   the text sent to clients on connect\nskills/fastmail-mcp/  the agent skill\ndocs/TOOLS.md         generated tool reference\ndocs/UPSTREAM-README.md    upstream's README, verbatim\nscripts/check-upstream.mjs new upstream commits and files we both touched\n```\n\nWorking rules for this repo are in [AGENTS.md](AGENTS.md). Upstream's own guide, including CalDAV and WebDAV setup, attachments on send, contacts scope, and troubleshooting, is [docs/UPSTREAM-README.md](docs/UPSTREAM-README.md).\n\n## Staying current with upstream\n\nThis is not a GitHub fork. It is an independent repo with upstream's history underneath, so it can stay private and still merge upstream cleanly. Changes to upstream files stay additive, and new behaviour lives in new files.\n\n```bash\nnpm run check:upstream    # fetches upstream, writes UPSTREAM-UPDATE.md when there is news\ngit merge upstream/main\nnpm ci && npm run build && npm test && npm run scan:secrets && npm run docs:tools\n```\n\nVS Code runs the check on folder open. `FORK_TOUCHED` in `scripts/check-upstream.mjs` lists the upstream files we edited, so the check flags them before a merge.\n\n## Credits and license\n\n- [MadLlama25/fastmail-mcp](https://github.com/MadLlama25/fastmail-mcp) by Jeremy Gill is the base of everything here. Thank you.\n- Upstream credits the [Fastmail JMAP-Samples](https://github.com/fastmail/JMAP-Samples) for several patterns.\n- MIT, same as upstream. See [LICENSE](LICENSE).\n"}