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

# 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

# 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

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

Required .env variables:

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:

# Generate 3 random API keys for clients
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32

4. Install Systemd Service

# 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

# 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

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

# Certbot auto-configures nginx and auto-renews

7. Test Deployment

# 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:

{
  "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:

{
  "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

# 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

sudo journalctl -u mcp-imap -n 50

SSL errors

sudo certbot renew --dry-run

Connection refused

# Check if service is running
sudo systemctl status mcp-imap

# Check port binding
sudo netstat -tlnp | grep 8000

Maintenance

Update code

cd /opt/mcp-imap-agent/backend
git pull
sudo systemctl restart mcp-imap

Rotate API keys

nano .env  # Update MCP_API_KEYS
sudo systemctl restart mcp-imap

Backup

# 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