README.md•7.17 kB
# FastMail MCP Server
[](https://hub.docker.com/r/gr3enarr0w/fastmail-mcp-server)
[](https://github.com/gr3enarr0w/fastmail-mcp-server)
[](https://unraid.net/)
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
```bash
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
```yaml
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
```bash
FASTMAIL_API_TOKEN=your_fastmail_api_token
FASTMAIL_EMAIL=your_fastmail_email
```
### Optional Environment Variables
```bash
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`:
```json
{
"mcpServers": {
"fastmail-server": {
"command": "docker",
"args": ["exec", "-i", "fastmail-mcp-server", "node", "src/index.js"]
}
}
}
```
### Claude Desktop
Add to Claude Desktop config:
```json
{
"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](DOCKER.md)** - Complete Docker deployment instructions
- **[Claude Integration Guide](CLAUDE-SETUP.md)** - Setup for Claude Code & Desktop
- **[Unraid Installation](unraid-template.xml)** - 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](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>
