FastMail MCP Server

Advanced FastMail email management server implementing the Model Context Protocol (MCP) with Docker support and Unraid compatibility.

✨ Features

🤖 AI-Powered Email Management

• Smart Email Analysis - Find genuine action items, filter auto-paid bills

• AI Reply Generation - Generate contextual replies matching your writing style

• Writing Style Learning - Analyze your communication patterns

• Intelligent Summarization - Comprehensive email summaries by category/timeframe

📧 Email Operations

• Advanced Search - Query emails with pagination support

• Automated Organization - Sort emails into hierarchical categories

• Inbox Zero - Aggressive cleanup to achieve true inbox zero

• Conversation Tracking - Thread-aware email handling

👥 Contacts & Calendar

• Smart Contact Management - Sync contacts based on email interactions

• Calendar Integration - Extract events from emails, conflict checking

• Relationship Detection - Identify work contacts vs personal

🏗️ Organization & Structure

• 13-Label System - Simple hierarchical email organization

• Migration Tools - Move from flat to hierarchical structures

• News Digest - Summarize news articles from WSJ and other sources

• Spam Intelligence - Multi-year threat detection (1990s-2024)

🚀 Quick Start

Docker Run

docker run -d \
  --name fastmail-mcp-server \
  --restart unless-stopped \
  -e FASTMAIL_API_TOKEN=your_token \
  -e FASTMAIL_EMAIL=your_email@fastmail.com \
  gr3enarr0w/fastmail-mcp-server:latest

Docker Compose

version: '3.8'
services:
  fastmail-mcp-server:
    image: gr3enarr0w/fastmail-mcp-server:latest
    container_name: fastmail-mcp-server
    restart: unless-stopped
    environment:
      - FASTMAIL_API_TOKEN=your_token
      - FASTMAIL_EMAIL=your_email@fastmail.com

Unraid Installation

1. Go to Community Applications

2. Search for "FastMail MCP"

3. Click Install

4. Configure your FastMail API credentials

🔧 Configuration

Required Environment Variables

FASTMAIL_API_TOKEN=your_fastmail_api_token
FASTMAIL_EMAIL=your_fastmail_email

Optional Environment Variables

FASTMAIL_SEND_AS=your_sending_email@domain.com
FASTMAIL_ALIAS_DOMAIN=yourdomain.com
FASTMAIL_JMAP_URL=https://jmap.fastmail.com/jmap/session

🧠 Claude Integration

Claude Code (CLI)

Add to ~/.mcp.json:

{
  "mcpServers": {
    "fastmail-server": {
      "command": "docker",
      "args": ["exec", "-i", "fastmail-mcp-server", "node", "src/index.js"]
    }
  }
}

Claude Desktop

Add to Claude Desktop config:

{
  "mcpServers": {
    "fastmail-server": {
      "command": "/path/to/mcp-bridge.sh",
      "args": []
    }
  }
}

🛠️ Available MCP Tools

• list_mailboxes - List all mailboxes in the account

• list_emails - List emails with pagination support

• get_email - Get full details of a specific email

• search_emails - Search emails using text queries

• send_email - Send new emails via FastMail

• reply_to_email - Reply to specific emails by ID

• smart_email_analysis - Find actionable emails, filter completed tasks

• generate_ai_reply - AI-powered contextual reply generation

• analyze_writing_style - Learn user communication patterns

• adaptive_user_learning - Automatically adapt to user preferences

• optimize_ai_prompts - Generate optimized prompts for different models

• organize_emails - Auto-organize into appropriate folders

• achieve_inbox_zero - Aggressive inbox cleanup

• setup_simple_labels - Create 13-label hierarchical structure

• categorize_with_simple_labels - Auto-categorize with labels

• migrate_to_hierarchy - Migrate from flat to hierarchical structure

• review_archived_emails - Review archived items for missed replies

• analyze_hierarchical_structure - Analyze and suggest improvements

• manage_contacts - Intelligent contact management

• list_contacts - List existing FastMail contacts

• manage_calendar - Calendar event management and extraction

• comprehensive_email_summary - Generate detailed email summaries

• summarize_news - News digest from email sources

• universal_setup_wizard - Automated onboarding wizard

📁 Project Structure

fastmail-mcp-server/
├── src/                     # Core MCP server code
│   ├── index.js            # Main MCP server entry point
│   ├── fastmail-client.js  # FastMail JMAP API client
│   └── *.js               # Feature implementations
├── scripts/                # Email organization scripts
├── analysis/               # Email analysis utilities  
├── Dockerfile             # Container definition
├── docker-compose.yml     # Docker Compose config
├── unraid-template.xml     # Unraid Community Apps template
└── docs/                  # Documentation

🔒 Security Features

• Non-root execution - Container runs as unprivileged user

• Read-only filesystem - Prevents tampering

• Resource limits - CPU and memory constraints

• Network isolation - No exposed ports (stdio transport)

• Credential isolation - API tokens via environment variables

📖 Documentation

• Docker Setup Guide - Complete Docker deployment instructions

• Claude Integration Guide - Setup for Claude Code & Desktop

• Unraid Installation - Community Applications template

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMail for their excellent JMAP API

• Anthropic for the Model Context Protocol specification

• Unraid Community for the Community Applications platform