# FastMail MCP Server

[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/gr3enarr0w/fastmail-mcp-server)
[![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/gr3enarr0w/fastmail-mcp-server)
[![Unraid](https://img.shields.io/badge/unraid-%23F15A2C.svg?style=for-the-badge&logo=unraid&logoColor=white)](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>