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

<details> <summary><strong>Email Management (6 tools)</strong></summary>

• 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

</details>

<details> <summary><strong>AI-Powered Features (5 tools)</strong></summary>

• 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

</details>

<details> <summary><strong>Organization & Automation (7 tools)</strong></summary>

• 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

</details>

<details> <summary><strong>Contacts & Calendar (3 tools)</strong></summary>

• manage_contacts - Intelligent contact management
• list_contacts - List existing FastMail contacts
• manage_calendar - Calendar event management and extraction

</details>

<details> <summary><strong>Advanced Features (3 tools)</strong></summary>

• comprehensive_email_summary - Generate detailed email summaries
• summarize_news - News digest from email sources
• universal_setup_wizard - Automated onboarding wizard

</details>

📁 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

---

<p align="center"> <strong>🤖 Generated with <a href="https://claude.ai/code">Claude Code</a></strong> </p>