fastmail-mcp-server by gr3enarr0w - MCP Server

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

Go to Community Applications
Search for "FastMail MCP"
Click Install
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

Email Management (6 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

AI-Powered Features (5 tools)

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

Organization & Automation (7 tools)

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

Contacts & Calendar (3 tools)

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

Advanced Features (3 tools)

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

- Complete Docker deployment instructions
- Setup for Claude Code & Desktop
- Community Applications template

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgments

FastMail for their excellent JMAP API
Anthropic for the Model Context Protocol specification
Unraid Community for the Community Applications platform

🤖 Generated with Claude Code