MCP-IMAP-Agent/backend/deployment/DEPLOY.md

# MCP IMAP Agent - Hetzner Deployment Guide

Deploy production-ready MCP IMAP server for N8N automation.

## Prerequisites

- Hetzner VPS (Ubuntu/Arch Linux)
- Domain: `imap.maxtheweb.ai` pointing to server IP
- Root or sudo access

## Installation Steps

### 1. System Setup

```bash
# Update system (Arch Linux)
sudo pacman -Syu

# Install dependencies
sudo pacman -S python python-pip nginx certbot certbot-nginx git

# Create app directory
sudo mkdir -p /opt/mcp-imap-agent
sudo chown $USER:$USER /opt/mcp-imap-agent
```

### 2. Deploy Application

```bash
# Clone repository
cd /opt/mcp-imap-agent
git clone <your-repo> .

# Create virtual environment
cd backend
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Configure Environment

```bash
# Create production .env
cp .env.example .env
nano .env
```

**Required .env variables:**
```bash
MCP_PORT=8000
MCP_API_KEYS=generate_random_key_1,generate_random_key_2
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=INFO
```

**Generate secure API keys:**
```bash
# Generate 3 random API keys for clients
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
```

### 4. Install Systemd Service

```bash
# Copy service file
sudo cp deployment/mcp-imap.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start
sudo systemctl enable mcp-imap

# Start service
sudo systemctl start mcp-imap

# Check status
sudo systemctl status mcp-imap
```

### 5. Configure Nginx

```bash
# Copy nginx config
sudo cp deployment/nginx-mcp-imap.conf /etc/nginx/sites-available/mcp-imap

# Enable site
sudo ln -s /etc/nginx/sites-available/mcp-imap /etc/nginx/sites-enabled/

# Test config
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx
```

### 6. Setup SSL with Certbot

```bash
# Get SSL certificate
sudo certbot --nginx -d imap.maxtheweb.ai

# Certbot auto-configures nginx and auto-renews
```

### 7. Test Deployment

```bash
# Health check (no auth)
curl https://imap.maxtheweb.ai/health

# MCP endpoint (needs API key)
curl -H "Authorization: Bearer YOUR_API_KEY" https://imap.maxtheweb.ai/mcp
```

## N8N Configuration

### Add MCP Server to N8N

N8N uses **MCP over SSE** (Server-Sent Events) protocol.

**Connection Settings:**
- **SSE URL**: `https://imap.maxtheweb.ai/mcp/sse`
- **Messages URL**: `https://imap.maxtheweb.ai/mcp/messages`
- **Authentication**: `Authorization: Bearer YOUR_API_KEY`

**In N8N:**
1. Add "HTTP Request" node or MCP-specific node
2. Configure SSE connection with API key in headers
3. MCP tools are called via JSON-RPC 2.0 protocol

### Example N8N MCP Tool Call

**Search emails:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_emails",
    "arguments": {
      "username": "user@gmail.com",
      "password": "app_password",
      "host": "imap.gmail.com",
      "folder": "INBOX",
      "limit": 10
    }
  },
  "id": 1
}
```

**Send email:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "send_email",
    "arguments": {
      "username": "user@gmail.com",
      "password": "app_password",
      "smtp_host": "smtp.gmail.com",
      "to": "recipient@example.com",
      "subject": "Automated email",
      "body": "This is sent via N8N + MCP"
    }
  },
  "id": 2
}
```

### Available MCP Tools
1. **list_folders** - List IMAP folders
2. **search_emails** - Search with filters (sender, subject, date)
3. **get_email** - Fetch full email content
4. **send_email** - Send email via SMTP
5. **health_check** - Server health status

## Monitoring

```bash
# View logs
sudo journalctl -u mcp-imap -f

# Check nginx logs
sudo tail -f /var/log/nginx/mcp-imap-access.log
sudo tail -f /var/log/nginx/mcp-imap-error.log

# Check resource usage
htop
```

## Security Checklist

- [ ] Firewall configured (only 80, 443, 22 open)
- [ ] SSL certificate installed and auto-renewing
- [ ] Strong API keys generated (32+ chars)
- [ ] Rate limiting enabled (10 req/s)
- [ ] Logs monitored for unauthorized access
- [ ] Regular updates: `sudo pacman -Syu`

## Troubleshooting

### Service won't start
```bash
sudo journalctl -u mcp-imap -n 50
```

### SSL errors
```bash
sudo certbot renew --dry-run
```

### Connection refused
```bash
# Check if service is running
sudo systemctl status mcp-imap

# Check port binding
sudo netstat -tlnp | grep 8000
```

## Maintenance

### Update code
```bash
cd /opt/mcp-imap-agent/backend
git pull
sudo systemctl restart mcp-imap
```

### Rotate API keys
```bash
nano .env  # Update MCP_API_KEYS
sudo systemctl restart mcp-imap
```

### Backup
```bash
# Backup .env (contains API keys)
sudo cp /opt/mcp-imap-agent/backend/.env ~/mcp-backup.env.$(date +%Y%m%d)
```

## Support

Issues: https://github.com/yourusername/mcp-imap-agent/issues
Docs: https://modelcontextprotocol.io