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 accountlist_emails- List emails with pagination supportget_email- Get full details of a specific emailsearch_emails- Search emails using text queriessend_email- Send new emails via FastMailreply_to_email- Reply to specific emails by ID
AI-Powered Features (5 tools)
smart_email_analysis- Find actionable emails, filter completed tasksgenerate_ai_reply- AI-powered contextual reply generationanalyze_writing_style- Learn user communication patternsadaptive_user_learning- Automatically adapt to user preferencesoptimize_ai_prompts- Generate optimized prompts for different models
Organization & Automation (7 tools)
organize_emails- Auto-organize into appropriate foldersachieve_inbox_zero- Aggressive inbox cleanupsetup_simple_labels- Create 13-label hierarchical structurecategorize_with_simple_labels- Auto-categorize with labelsmigrate_to_hierarchy- Migrate from flat to hierarchical structurereview_archived_emails- Review archived items for missed repliesanalyze_hierarchical_structure- Analyze and suggest improvements
Contacts & Calendar (3 tools)
manage_contacts- Intelligent contact managementlist_contacts- List existing FastMail contactsmanage_calendar- Calendar event management and extraction
Advanced Features (3 tools)
comprehensive_email_summary- Generate detailed email summariessummarize_news- News digest from email sourcesuniversal_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
- 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 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
🤖 Generated with Claude Code