FastMail MCP Server

A Model Context Protocol (MCP) server for integrating with FastMail's JMAP API. This server provides tools for reading emails, searching, managing folders, and sending emails through FastMail.

🚀 Features

📁 Mailbox Management: List and find mailboxes/folders
📧 Email Reading: Get emails from specific folders with previews
🔍 Advanced Search: Search by keyword, sender, subject, date range, attachments
📤 Email Sending: Send emails with CC/BCC support
🎯 Folder Targeting: Search within specific folders
⚡ Fast Performance: Uses FastMail's modern JMAP protocol

📋 Prerequisites

Python 3.8+
FastMail account with API access
API token from FastMail (Settings → Privacy & Security → Integrations)

🛠 Installation

Clone the repository:

git clone <your-repo-url>
cd fastmail-mcp-server

Install dependencies:
```
pip install -r requirements.txt
```
Get your FastMail API token:
- Log into FastMail
- Go to Settings → Privacy & Security → Integrations
- Create a new API token
- Copy the token (starts with fmu1-)

🚀 Usage

Running the Server

python fastmail_mcp_server.py

The server will start and listen for MCP commands via stdio.

Configuration

First, configure your FastMail credentials:

{
  "tool": "configure_fastmail",
  "arguments": {
    "apiToken": "fmu1-your-token-here"
  }
}

Available Tools

📁 configure_fastmail

Set up your FastMail API credentials.

📁 list_mailboxes

List all mailboxes with their names, roles, and email counts.

{
  "tool": "list_mailboxes",
  "arguments": {
    "role": "inbox"  // Optional: filter by role
  }
}

🔍 find_mailbox

Find a specific mailbox by name or role.

{
  "tool": "find_mailbox", 
  "arguments": {
    "name": "Work",     // Partial matching supported
    "role": "sent"      // Or search by role
  }
}

📧 get_emails

Get emails from a specific mailbox.

{
  "tool": "get_emails",
  "arguments": {
    "mailboxId": "mailbox-id-here",  // From list_mailboxes
    "mailboxName": "Inbox",          // Alternative to mailboxId
    "limit": 20,                     // Max emails to fetch
    "includeBody": false             // Include full email body
  }
}

🔍 search_emails

Search emails with advanced filtering.

{
  "tool": "search_emails",
  "arguments": {
    "keyword": "project update",     // Text search
    "from_email": "boss@company.com", // From specific sender
    "subject": "meeting",            // Subject contains
    "mailboxId": "inbox-id",         // Search within folder
    "hasAttachment": true,           // Has attachments
    "after": "2024-01-01",          // Date range
    "before": "2024-12-31",
    "limit": 50,
    "includeBody": false
  }
}

📖 get_email_body

Get the full body content of a specific email.

{
  "tool": "get_email_body",
  "arguments": {
    "emailId": "email-id-here",
    "format": "text"  // "text", "html", or "both"
  }
}

📤 send_email

Send an email through FastMail.

{
  "tool": "send_email",
  "arguments": {
    "to": ["recipient@example.com"],
    "cc": ["cc@example.com"],        // Optional
    "bcc": ["bcc@example.com"],      // Optional  
    "subject": "Hello from MCP!",
    "body": "This is the email body.",
    "isHtml": false                  // Set to true for HTML emails
  }
}

🔧 Integration with MCP Clients

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/path/to/fastmail_mcp_server.py"]
    }
  }
}

Other MCP Clients

This server follows the standard MCP protocol and should work with any MCP-compatible client.

🏗 Project Structure

fastmail-mcp-server/
├── fastmail_mcp_server.py    # Main server implementation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Package configuration
├── README.md                # This file
└── examples/                # Example usage scripts
    └── test_server.py       # Test script

🔒 Security Notes

API Token Security: Never commit your API token to version control
Permissions: The API token has access to your entire FastMail account
Network: All communication uses HTTPS with FastMail's secure APIs

🐛 Troubleshooting

Common Issues

Authentication Error: Verify your API token is correct and has proper permissions
Connection Error: Check your internet connection and FastMail service status
Missing Emails: Ensure you're searching in the correct mailbox

Debug Mode

Enable debug logging by setting environment variable:

export MCP_DEBUG=1
python fastmail_mcp_server.py

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

FastMail for their excellent JMAP API
Model Context Protocol by Anthropic
JMAP Specification by the IETF

📚 Additional Resources