Fastmail MCP Server
A Model Context Protocol (MCP) server that provides access to the Fastmail API, enabling AI assistants to interact with email, contacts, and calendar data.
Features
Core Email Operations
- List mailboxes and get mailbox statistics
- List, search, and filter emails with advanced criteria
- Get specific emails by ID with full content
- Send emails (text and HTML) with proper draft/sent handling
- Email management: mark read/unread, delete, move between folders
Advanced Email Features
- Attachment Handling: List and download email attachments
- Threading Support: Get complete conversation threads
- Advanced Search: Multi-criteria filtering (sender, date range, attachments, read status)
- Bulk Operations: Process multiple emails simultaneously
- Statistics & Analytics: Account summaries and mailbox statistics
Contacts Operations
- List all contacts with full contact information
- Get specific contacts by ID
- Search contacts by name or email
Calendar Operations
- List all calendars and calendar events
- Get specific calendar events by ID
- Create new calendar events with participants and details
Identity & Account Management
- List available sending identities
- Account summary with comprehensive statistics
Setup
Prerequisites
- Node.js 18+
- A Fastmail account with API access
- Fastmail API token
Installation
-
Clone or download this repository
-
Install dependencies:
npm install -
Build the project:
npm run build
Configuration
-
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
-
Set environment variables:
export FASTMAIL_API_TOKEN="your_api_token_here" # Optional: customize base URL (defaults to https://api.fastmail.com) export FASTMAIL_BASE_URL="https://api.fastmail.com"
Running the Server
Start the MCP server:
npm start
For development with auto-reload:
npm run dev
Run via npx (GitHub)
Default to main branch:
FASTMAIL_API_TOKEN="your_token" FASTMAIL_BASE_URL="https://api.fastmail.com" \
npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp
Windows PowerShell:
$env:FASTMAIL_API_TOKEN="your_token"
$env:FASTMAIL_BASE_URL="https://api.fastmail.com"
npx --yes github:MadLlama25/fastmail-mcp fastmail-mcp
Pin to a tagged release:
FASTMAIL_API_TOKEN="your_token" \
npx --yes github:MadLlama25/fastmail-mcp@v1.6.1 fastmail-mcp
Install as a Claude Desktop Extension (DXT)
You can install this server as a Desktop Extension for Claude Desktop using the packaged .dxt file.
-
Build and pack:
npm run build npx dxt packThis produces
fastmail-mcp.dxtin the project root. -
Install into Claude Desktop:
- Open the
.dxtfile, or drag it into Claude Desktop - When prompted:
- Fastmail API Token: paste your token (stored encrypted by Claude)
- Fastmail Base URL: leave blank to use
https://api.fastmail.com(default)
- Open the
-
Use any of the tools (e.g.
get_recent_emails).
Available Tools (31 Total)
🎯 Most Popular Tools:
- check_function_availability: Check what's available and get setup guidance
- test_bulk_operations: Safely test bulk operations with dry-run mode
- send_email: Full-featured email sending with proper draft/sent handling
- advanced_search: Powerful multi-criteria email filtering
- get_recent_emails: Quick access to recent emails from any mailbox
Email Tools
- list_mailboxes: Get all mailboxes in your account
- list_emails: List emails from a specific mailbox or all mailboxes
- Parameters:
mailboxId(optional),limit(default: 20)
- Parameters:
- get_email: Get a specific email by ID
- Parameters:
emailId(required)
- Parameters:
- send_email: Send an email
- Parameters:
to(required array),cc(optional array),bcc(optional array),from(optional),mailboxId(optional),subject(required),textBody(optional),htmlBody(optional)
- Parameters:
- search_emails: Search emails by content
- Parameters:
query(required),limit(default: 20)
- Parameters:
- get_recent_emails: Get the most recent emails from a mailbox (inspired by JMAP-Samples top-ten)
- Parameters:
limit(default: 10, max: 50),mailboxName(default: 'inbox')
- Parameters:
- mark_email_read: Mark an email as read or unread
- Parameters:
emailId(required),read(default: true)
- Parameters:
- delete_email: Delete an email (move to trash)
- Parameters:
emailId(required)
- Parameters:
- move_email: Move an email to a different mailbox
- Parameters:
emailId(required),targetMailboxId(required)
- Parameters:
Advanced Email Features
- get_email_attachments: Get list of attachments for an email
- Parameters:
emailId(required)
- Parameters:
- download_attachment: Get download URL for an email attachment
- Parameters:
emailId(required),attachmentId(required)
- Parameters:
- advanced_search: Advanced email search with multiple criteria
- Parameters:
query(optional),from(optional),to(optional),subject(optional),hasAttachment(optional),isUnread(optional),mailboxId(optional),after(optional),before(optional),limit(default: 50)
- Parameters:
- get_thread: Get all emails in a conversation thread
- Parameters:
threadId(required)
- Parameters:
Email Statistics & Analytics
- get_mailbox_stats: Get statistics for a mailbox (unread count, total emails, etc.)
- Parameters:
mailboxId(optional, defaults to all mailboxes)
- Parameters:
- get_account_summary: Get overall account summary with statistics
Bulk Operations
- bulk_mark_read: Mark multiple emails as read/unread
- Parameters:
emailIds(required array),read(default: true)
- Parameters:
- bulk_move: Move multiple emails to a mailbox
- Parameters:
emailIds(required array),targetMailboxId(required)
- Parameters:
- bulk_delete: Delete multiple emails (move to trash)
- Parameters:
emailIds(required array)
- Parameters:
Contact Tools
- list_contacts: List all contacts
- Parameters:
limit(default: 50)
- Parameters:
- get_contact: Get a specific contact by ID
- Parameters:
contactId(required)
- Parameters:
- search_contacts: Search contacts by name or email
- Parameters:
query(required),limit(default: 20)
- Parameters:
Calendar Tools
- list_calendars: List all calendars
- list_calendar_events: List calendar events
- Parameters:
calendarId(optional),limit(default: 50)
- Parameters:
- get_calendar_event: Get a specific calendar event by ID
- Parameters:
eventId(required)
- Parameters:
- create_calendar_event: Create a new calendar event
- Parameters:
calendarId(required),title(required),description(optional),start(required, ISO 8601),end(required, ISO 8601),location(optional),participants(optional array)
- Parameters:
Identity & Testing Tools
- list_identities: List sending identities (email addresses that can be used for sending)
- check_function_availability: Check which functions are available based on account permissions (includes setup guidance)
- test_bulk_operations: Safely test bulk operations with dry-run mode
- Parameters:
dryRun(default: true),limit(default: 3)
- Parameters:
API Information
This server uses the JMAP (JSON Meta Application Protocol) API provided by Fastmail. JMAP is a modern, efficient alternative to IMAP for email access.
Inspired by Fastmail JMAP-Samples
Many features in this MCP server are inspired by the official Fastmail JMAP-Samples repository, including:
- Recent emails retrieval (based on top-ten example)
- Email management operations
- Efficient chained JMAP method calls
Authentication
The server uses bearer token authentication with Fastmail's API. API tokens provide secure access without exposing your main account password.
Rate Limits
Fastmail applies rate limits to API requests. The server handles standard rate limiting, but excessive requests may be throttled.
Development
Project Structure
src/
├── index.ts # Main MCP server implementation
├── auth.ts # Authentication handling
├── jmap-client.ts # JMAP client wrapper
└── contacts-calendar.ts # Contacts and calendar extensions
Building
npm run build
Development Mode
npm run dev
License
MIT
Contributing
Contributions are welcome! Please ensure that:
- Code follows the existing style
- All functions are properly typed
- Error handling is implemented
- Documentation is updated for new features
Troubleshooting
Common Issues
- Authentication Errors: Ensure your API token is valid and has the necessary permissions
- Missing Dependencies: Run
npm installto ensure all dependencies are installed - Build Errors: Check that TypeScript compilation completes without errors using
npm run build - Calendar/Contacts "Forbidden" Errors: Use
check_function_availabilityto see setup guidance
Calendar/Contacts Not Working?
If calendar and contacts functions return "Forbidden" errors, this is likely due to:
- Account Plan: Calendar/contacts API may require business/professional Fastmail plans
- API Token Scope: Your API token may need calendar/contacts permissions enabled
- Feature Enablement: These features may need explicit activation in your account
Solution: Run check_function_availability for step-by-step setup guidance.
Testing Your Setup
Use the built-in testing tools:
- check_function_availability: See what's available and get setup help
- test_bulk_operations: Safely test bulk operations without making changes
For more detailed error information, check the console output when running the server.
Privacy & Security
- API tokens are stored encrypted by Claude Desktop when installed via the DXT and are never logged by this server.
- The server avoids logging raw errors and sensitive data (tokens, email addresses, identities, attachment names/blobIds) in error messages.
- 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.
- If you encounter errors, messages are sanitized and summarized to prevent leaking personal information.