{"id":47736806,"url":"https://github.com/madllama25/fastmail-mcp","last_synced_at":"2026-04-18T03:02:11.100Z","repository":{"id":299316623,"uuid":"1002639708","full_name":"MadLlama25/fastmail-mcp","owner":"MadLlama25","description":"A Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data. Includes a DXT (desktop extension) for Claude Desktop.","archived":false,"fork":false,"pushed_at":"2026-04-02T04:28:00.000Z","size":120,"stargazers_count":96,"open_issues_count":9,"forks_count":39,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-04-03T07:19:03.803Z","etag":null,"topics":["dxt","fastmail","fastmail-api","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MadLlama25.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"MadLlama25"}},"created_at":"2025-06-15T22:18:28.000Z","updated_at":"2026-04-02T04:27:37.000Z","dependencies_parsed_at":"2026-04-02T23:03:23.899Z","dependency_job_id":null,"html_url":"https://github.com/MadLlama25/fastmail-mcp","commit_stats":null,"previous_names":["madllama25/fastmail-mcp"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/MadLlama25/fastmail-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLlama25%2Ffastmail-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLlama25%2Ffastmail-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLlama25%2Ffastmail-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLlama25%2Ffastmail-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MadLlama25","download_url":"https://codeload.github.com/MadLlama25/fastmail-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLlama25%2Ffastmail-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dxt","fastmail","fastmail-api","mcp-server"],"created_at":"2026-04-02T22:48:40.872Z","updated_at":"2026-04-18T03:02:11.095Z","avatar_url":"https://github.com/MadLlama25.png","language":"TypeScript","funding_links":["https://github.com/sponsors/MadLlama25"],"categories":[],"sub_categories":[],"readme":"# Fastmail MCP Server\n\nA Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data.\n\n## Features\n\n### Core Email Operations\n- List mailboxes and get mailbox statistics\n- List, search, and filter emails with advanced criteria\n- Get specific emails by ID with full content\n- Send emails (text and HTML) with proper draft/sent handling\n- Reply to emails with proper threading (In-Reply-To, References headers)\n- Create and save email drafts (with or without threading)\n- Email management: mark read/unread, delete, move between folders\n\n### Advanced Email Features\n- **Attachment Handling**: List and download email attachments\n- **Threading Support**: Get complete conversation threads\n- **Advanced Search**: Multi-criteria filtering (sender, date range, attachments, read status)\n- **Bulk Operations**: Process multiple emails simultaneously\n- **Statistics \u0026 Analytics**: Account summaries and mailbox statistics\n\n### Contacts Operations\n- List all contacts with full contact information\n- Get specific contacts by ID\n- Search contacts by name or email\n\n### Calendar Operations\n- List all calendars and calendar events\n- Get specific calendar events by ID\n- Create new calendar events with participants and details\n\n### Label vs Move Operations\n- **move_email/bulk_move**: Replaces ALL mailboxes for an email (folder behavior)\n- **add_labels/remove_labels**: Adds/removes SPECIFIC mailboxes while preserving others (label behavior)\n\n### Identity \u0026 Account Management\n- List available sending identities\n- Account summary with comprehensive statistics\n\n## Setup\n\n### Prerequisites\n- Node.js 18+ \n- A Fastmail account with API access\n- Fastmail API token\n\n### Installation\n\n1. Clone or download this repository\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Build the project:\n   ```bash\n   npm run build\n   ```\n\n### Configuration\n\n1. Get your Fastmail API token:\n   - Log in to Fastmail web interface\n   - Go to Settings → Privacy \u0026 Security\n   - Find \"Connected apps \u0026 API tokens\" section\n   - Click \"Manage API tokens\"\n   - Click \"New API token\"\n   - Copy the generated token\n\n2. Set environment variables:\n   ```bash\n   export FASTMAIL_API_TOKEN=\"your_api_token_here\"\n   # Optional: customize base URL (defaults to https://api.fastmail.com)\n   export FASTMAIL_BASE_URL=\"https://api.fastmail.com\"\n   # Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/)\n   export FASTMAIL_DOWNLOAD_DIR=\"/path/to/your/downloads\"\n   ```\n\n### Running the Server\n\nStart the MCP server:\n```bash\nnpm start\n```\n\nFor development with auto-reload:\n```bash\nnpm run dev\n```\n\n### Run via npx (GitHub)\n\nDefault to `main` branch:\n\n```bash\nFASTMAIL_API_TOKEN=\"your_token\" FASTMAIL_BASE_URL=\"https://api.fastmail.com\" \\\n  npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp\n```\n\nWindows PowerShell:\n\n```powershell\n$env:FASTMAIL_API_TOKEN=\"your_token\"\n$env:FASTMAIL_BASE_URL=\"https://api.fastmail.com\"\nnpx --yes github:MadLlama25/fastmail-mcp fastmail-mcp\n```\n\nPin to a tagged release:\n\n```bash\nFASTMAIL_API_TOKEN=\"your_token\" \\\n  npx --yes github:MadLlama25/fastmail-mcp@v1.9.2 fastmail-mcp\n```\n\n## Install as a Claude Desktop Extension (DXT)\n\nYou can install this server as a Desktop Extension for Claude Desktop using the packaged `.dxt` file.\n\n1. Build and pack:\n   ```bash\n   npm run build\n   npx @anthropic-ai/dxt pack\n   ```\n   This produces `fastmail-mcp.dxt` in the project root.\n\n2. Install into Claude Desktop:\n   - Open the `.dxt` file, or drag it into Claude Desktop\n   - When prompted:\n     - Fastmail API Token: paste your token (stored encrypted by Claude)\n     - Fastmail Base URL: leave blank to use `https://api.fastmail.com` (default)\n\n3. Use any of the tools (e.g. `get_recent_emails`).\n\n## Available Tools (38 Total)\n\n**🎯 Most Popular Tools:**\n- **check_function_availability**: Check what's available and get setup guidance  \n- **test_bulk_operations**: Safely test bulk operations with dry-run mode\n- **send_email**: Full-featured email sending with proper draft/sent handling\n- **advanced_search**: Powerful multi-criteria email filtering\n- **get_recent_emails**: Quick access to recent emails from any mailbox\n\n### Email Tools\n\n- **list_mailboxes**: Get all mailboxes in your account\n- **list_emails**: List emails from a specific mailbox or all mailboxes\n  - Parameters: `mailboxId` (optional), `limit` (default: 20), `ascending` (optional, oldest first)\n- **get_email**: Get a specific email by ID\n  - Parameters: `emailId` (required)\n- **send_email**: Send an email (supports threading via optional `inReplyTo` and `references` headers)\n  - Parameters: `to` (required array), `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)\n- **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.\n  - 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)\n- **save_draft**: Save an email as a draft without sending (supports threading headers for reply drafts)\n  - Parameters: `to` (required array), `cc` (optional array), `bcc` (optional array), `from` (optional), `subject` (required), `textBody` (optional), `htmlBody` (optional), `inReplyTo` (optional array), `references` (optional array)\n- **create_draft**: Create a minimal email draft (at least one of to/subject/body required)\n  - Parameters: `to` (optional array), `cc` (optional array), `bcc` (optional array), `from` (optional), `mailboxId` (optional), `subject` (optional), `textBody` (optional), `htmlBody` (optional), `replyTo` (optional array)\n- **search_emails**: Search emails by content\n  - Parameters: `query` (required), `limit` (default: 20), `ascending` (optional, oldest first)\n- **get_recent_emails**: Get the most recent emails from a mailbox (inspired by JMAP-Samples top-ten)\n  - Parameters: `limit` (default: 10, max: 50), `mailboxName` (default: 'inbox'), `ascending` (optional, oldest first)\n- **mark_email_read**: Mark an email as read or unread\n  - Parameters: `emailId` (required), `read` (default: true)\n- **delete_email**: Delete an email (move to trash)\n  - Parameters: `emailId` (required)\n- **move_email**: Move an email to a different mailbox (replaces all mailboxes)\n  - Parameters: `emailId` (required), `targetMailboxId` (required)\n- **add_labels**: Add labels (mailboxes) to an email without removing existing ones\n  - Parameters: `emailId` (required), `mailboxIds` (required array)\n- **remove_labels**: Remove specific labels (mailboxes) from an email\n  - Parameters: `emailId` (required), `mailboxIds` (required array)\n\n### Advanced Email Features\n\n- **get_email_attachments**: Get list of attachments for an email\n  - Parameters: `emailId` (required)\n- **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.\n  - Parameters: `emailId` (required), `attachmentId` (required), `savePath` (optional)\n- **advanced_search**: Advanced email search with multiple criteria\n  - Parameters: `query` (optional), `from` (optional), `to` (optional), `subject` (optional), `hasAttachment` (optional), `isUnread` (optional), `mailboxId` (optional), `after` (optional), `before` (optional), `limit` (default: 50), `ascending` (optional, oldest first)\n- **get_thread**: Get all emails in a conversation thread\n  - Parameters: `threadId` (required)\n\n### Email Statistics \u0026 Analytics\n\n- **get_mailbox_stats**: Get statistics for a mailbox (unread count, total emails, etc.)\n  - Parameters: `mailboxId` (optional, defaults to all mailboxes)\n- **get_account_summary**: Get overall account summary with statistics\n\n### Bulk Operations\n\n- **bulk_mark_read**: Mark multiple emails as read/unread\n  - Parameters: `emailIds` (required array), `read` (default: true)\n- **bulk_move**: Move multiple emails to a mailbox\n  - Parameters: `emailIds` (required array), `targetMailboxId` (required)\n- **bulk_delete**: Delete multiple emails (move to trash)\n  - Parameters: `emailIds` (required array)\n- **bulk_add_labels**: Add labels to multiple emails simultaneously\n  - Parameters: `emailIds` (required array), `mailboxIds` (required array)\n- **bulk_remove_labels**: Remove labels from multiple emails simultaneously\n  - Parameters: `emailIds` (required array), `mailboxIds` (required array)\n\n### Contact Tools\n\n- **list_contacts**: List all contacts\n  - Parameters: `limit` (default: 50)\n- **get_contact**: Get a specific contact by ID\n  - Parameters: `contactId` (required)\n- **search_contacts**: Search contacts by name or email\n  - Parameters: `query` (required), `limit` (default: 20)\n\n### Calendar Tools\n\n- **list_calendars**: List all calendars\n- **list_calendar_events**: List calendar events\n  - Parameters: `calendarId` (optional), `limit` (default: 50)\n- **get_calendar_event**: Get a specific calendar event by ID\n  - Parameters: `eventId` (required)\n- **create_calendar_event**: Create a new calendar event\n  - Parameters: `calendarId` (required), `title` (required), `description` (optional), `start` (required, ISO 8601), `end` (required, ISO 8601), `location` (optional), `participants` (optional array)\n\n### Identity \u0026 Testing Tools\n\n- **list_identities**: List sending identities (email addresses that can be used for sending)\n- **check_function_availability**: Check which functions are available based on account permissions (includes setup guidance)\n- **test_bulk_operations**: Safely test bulk operations with dry-run mode\n  - Parameters: `dryRun` (default: true), `limit` (default: 3)\n\n## API Information\n\nThis server uses the JMAP (JSON Meta Application Protocol) API provided by Fastmail. JMAP is a modern, efficient alternative to IMAP for email access.\n\n### Inspired by Fastmail JMAP-Samples\n\nMany features in this MCP server are inspired by the official [Fastmail JMAP-Samples](https://github.com/fastmail/JMAP-Samples) repository, including:\n- Recent emails retrieval (based on top-ten example)\n- Email management operations\n- Efficient chained JMAP method calls\n\n### Authentication\nThe server uses bearer token authentication with Fastmail's API. API tokens provide secure access without exposing your main account password.\n\n### Rate Limits\nFastmail applies rate limits to API requests. The server handles standard rate limiting, but excessive requests may be throttled.\n\n## CalDAV Calendar Support\n\nFastmail 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.\n\nHowever, Fastmail fully supports **CalDAV** for calendar access via `caldav.fastmail.com`. This server automatically falls back to CalDAV when JMAP calendar access is unavailable.\n\n### Setup\n\n1. Create an app-specific password on Fastmail:\n   - Go to **Settings → Privacy \u0026 Security → Manage app passwords**\n   - Create a new app password (you can name it \"CalDAV MCP\" or similar)\n\n2. Set the following environment variables:\n   ```bash\n   export FASTMAIL_CALDAV_USERNAME=\"your-email@fastmail.com\"\n   export FASTMAIL_CALDAV_PASSWORD=\"your-app-specific-password\"\n   ```\n\nWhen these variables are set, the calendar tools (`list_calendars`, `list_calendar_events`, `get_calendar_event`, `create_calendar_event`) will automatically fall back to CalDAV if JMAP calendars are not available. When these variables are not set, the server behaves exactly as before (JMAP only).\n\n## Development\n\n### Project Structure\n```\nsrc/\n├── index.ts              # Main MCP server implementation\n├── auth.ts              # Authentication handling\n├── jmap-client.ts       # JMAP client wrapper\n├── contacts-calendar.ts # Contacts and calendar extensions\n└── caldav-client.ts     # CalDAV calendar client (fallback)\n```\n\n### Building\n```bash\nnpm run build\n```\n\n### Development Mode\n```bash\nnpm run dev\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please ensure that:\n1. Code follows the existing style\n2. All functions are properly typed\n3. Error handling is implemented\n4. Documentation is updated for new features\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Errors**: Ensure your API token is valid and has the necessary permissions\n2. **Missing Dependencies**: Run `npm install` to ensure all dependencies are installed  \n3. **Build Errors**: Check that TypeScript compilation completes without errors using `npm run build`\n4. **Calendar/Contacts \"Forbidden\" Errors**: Use `check_function_availability` to see setup guidance\n\n### Email Tools Failing with Serialization Errors?\n\nIf `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+. This was caused by incomplete JMAP response validation that surfaced after the MCP SDK v1.x upgrade added stricter result checking.\n\n### Calendar/Contacts Not Working?\n\nIf calendar and contacts functions return \"Forbidden\" errors, this is likely due to:\n\n1. **Account Plan**: Calendar/contacts API may require business/professional Fastmail plans\n2. **API Token Scope**: Your API token may need calendar/contacts permissions enabled\n3. **Feature Enablement**: These features may need explicit activation in your account\n\n**Solution**: Run `check_function_availability` for step-by-step setup guidance.\n\n### Testing Your Setup\n\nUse the built-in testing tools:\n- **check_function_availability**: See what's available and get setup help\n- **test_bulk_operations**: Safely test bulk operations without making changes\n\nFor more detailed error information, check the console output when running the server.\n\n## Privacy \u0026 Security\n\n- API tokens are stored encrypted by Claude Desktop when installed via the DXT and are never logged by this server.\n- The server avoids logging raw errors and sensitive data (tokens, email addresses, identities, attachment names/blobIds) in error messages.\n- 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.\n- If you encounter errors, messages are sanitized and summarized to prevent leaking personal information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadllama25%2Ffastmail-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadllama25%2Ffastmail-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadllama25%2Ffastmail-mcp/lists"}