FastMail MCP Server

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

1. Clone the repository:

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

2. Install dependencies:

   pip install -r requirements.txt
   

3. 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

1. Authentication Error: Verify your API token is correct and has proper permissions
2. Connection Error: Check your internet connection and FastMail service status
3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tes