n8n-mcp/docs/REMOTE_DEPLOYMENT.md

Remote Deployment Guide

This guide explains how to deploy the n8n Documentation MCP Server to a remote VM (such as Hetzner) and connect to it from Claude Desktop.

Quick Start: For a streamlined deployment to n8ndocumentation.aiservices.pl, see DEPLOYMENT_QUICKSTART.md.

Overview

The n8n Documentation MCP Server can be deployed as a remote HTTP service, allowing Claude Desktop to access n8n node documentation over the internet. This is useful for:

• Centralized documentation serving for teams
• Accessing documentation without local n8n installation
• Cloud-based AI development workflows

Architecture

Claude Desktop → Internet → MCP Server (HTTPS) → SQLite Database
                                ↓
                         n8n Documentation

Prerequisites

• A VM with Ubuntu 20.04+ or similar Linux distribution
• Node.js 18+ installed
• A domain name (e.g., n8ndocumentation.aiservices.pl)
• SSL certificate (Let's Encrypt recommended)
• Basic knowledge of Linux server administration

Deployment Steps

1. Server Setup

SSH into your VM and prepare the environment:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Node.js 18+ (if not already installed)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Install git and build essentials
sudo apt install -y git build-essential

# Install PM2 for process management
sudo npm install -g pm2

# Create application directory
sudo mkdir -p /opt/n8n-mcp
sudo chown $USER:$USER /opt/n8n-mcp

2. Clone and Build

cd /opt
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Initialize database
npm run db:rebuild:v2

3. Configure Environment

Create the production environment file:

cp .env.example .env
nano .env

Configure with your domain and security settings:

# Remote Server Configuration
MCP_PORT=3000
MCP_HOST=0.0.0.0
MCP_DOMAIN=n8ndocumentation.aiservices.pl

# Authentication - REQUIRED for production
# Generate secure token: openssl rand -hex 32
MCP_AUTH_TOKEN=your-generated-secure-token-here

# Enable CORS for browser access
MCP_CORS=true

# Database path
NODE_DB_PATH=/opt/n8n-mcp/data/nodes-v2.db

# Production environment
NODE_ENV=production
MCP_LOG_LEVEL=info

4. Setup SSL with Nginx

Install and configure Nginx as a reverse proxy with SSL:

# Install Nginx and Certbot
sudo apt install -y nginx certbot python3-certbot-nginx

# Create Nginx configuration
sudo nano /etc/nginx/sites-available/n8n-mcp

Add the following configuration:

server {
    listen 80;
    server_name n8ndocumentation.aiservices.pl;

    location / {
        return 301 https://$server_name$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name n8ndocumentation.aiservices.pl;

    # SSL will be configured by Certbot
    
    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";
    
    # Proxy settings
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # Increase timeouts for MCP operations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

Enable the site and obtain SSL certificate:

# Enable the site
sudo ln -s /etc/nginx/sites-available/n8n-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Obtain SSL certificate
sudo certbot --nginx -d n8ndocumentation.aiservices.pl

5. Start with PM2

Create PM2 ecosystem file:

nano /opt/n8n-mcp/ecosystem.config.js

module.exports = {
  apps: [{
    name: 'n8n-mcp',
    script: './dist/index-http.js',
    cwd: '/opt/n8n-mcp',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production'
    },
    error_file: '/opt/n8n-mcp/logs/error.log',
    out_file: '/opt/n8n-mcp/logs/out.log',
    log_file: '/opt/n8n-mcp/logs/combined.log',
    time: true
  }]
};

Start the application:

# Create logs directory
mkdir -p /opt/n8n-mcp/logs

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

6. Configure Firewall

# Allow SSH, HTTP, and HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Claude Desktop Configuration

1. Get your auth token

From your server, get the configured auth token:

grep MCP_AUTH_TOKEN /opt/n8n-mcp/.env

2. Configure Claude Desktop

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Add the remote MCP server:

{
  "mcpServers": {
    "n8n-nodes-remote": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-http",
        "https://n8ndocumentation.aiservices.pl/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

3. Restart Claude Desktop

Quit and restart Claude Desktop to load the new configuration.

Server Management

Viewing Logs

# View real-time logs
pm2 logs n8n-mcp

# View error logs
tail -f /opt/n8n-mcp/logs/error.log

# View Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

Rebuilding Database

To update the node documentation database:

cd /opt/n8n-mcp

# Stop the server
pm2 stop n8n-mcp

# Rebuild database
npm run db:rebuild:v2

# Restart server
pm2 restart n8n-mcp

Updating the Server

cd /opt/n8n-mcp

# Pull latest changes
git pull

# Install dependencies
npm install

# Build
npm run build

# Restart
pm2 restart n8n-mcp

Security Considerations

1. Authentication Token: Always use a strong, randomly generated token

   openssl rand -hex 32
   

2. HTTPS: Always use HTTPS in production. The setup above includes automatic SSL with Let's Encrypt.

3. Firewall: Only open necessary ports (22, 80, 443)

4. Updates: Keep the system and Node.js updated regularly

5. Monitoring: Set up monitoring for the service:

   # PM2 monitoring
   pm2 install pm2-logrotate
   pm2 set pm2-logrotate:max_size 10M
   pm2 set pm2-logrotate:retain 7
   

API Endpoints

Once deployed, your server provides:

• GET https://n8ndocumentation.aiservices.pl/ - Server information
• GET https://n8ndocumentation.aiservices.pl/health - Health check
• GET https://n8ndocumentation.aiservices.pl/stats - Database statistics
• POST https://n8ndocumentation.aiservices.pl/mcp - MCP protocol endpoint
• POST https://n8ndocumentation.aiservices.pl/rebuild - Rebuild database (requires auth)

Troubleshooting

Connection Issues

1. Check if the server is running:

   pm2 status
   curl https://n8ndocumentation.aiservices.pl/health
   

2. Verify Nginx is working:

   sudo nginx -t
   sudo systemctl status nginx
   

3. Check firewall:

   sudo ufw status
   

Authentication Failures

1. Verify the token matches in both .env and Claude config
2. Check server logs for auth errors:

   pm2 logs n8n-mcp --lines 100
   

Database Issues

1. Check database exists:

   ls -la /opt/n8n-mcp/data/nodes-v2.db
   

2. Rebuild if necessary:

   cd /opt/n8n-mcp
   npm run db:rebuild:v2
   

Monitoring and Maintenance

Health Monitoring

Set up external monitoring (e.g., UptimeRobot) to check:

• https://n8ndocumentation.aiservices.pl/health

Backup

Regular backups of the database:

# Create backup script
cat > /opt/n8n-mcp/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/opt/n8n-mcp/backups"
mkdir -p $BACKUP_DIR
cp /opt/n8n-mcp/data/nodes-v2.db "$BACKUP_DIR/nodes-v2-$(date +%Y%m%d-%H%M%S).db"
# Keep only last 7 backups
find $BACKUP_DIR -name "nodes-v2-*.db" -mtime +7 -delete
EOF

chmod +x /opt/n8n-mcp/backup.sh

# Add to crontab (daily at 2 AM)
(crontab -l 2>/dev/null; echo "0 2 * * * /opt/n8n-mcp/backup.sh") | crontab -

Cost Optimization

For a small Hetzner VM (CX11 - 1 vCPU, 2GB RAM):

• Monthly cost: ~€4-5
• Sufficient for serving documentation to multiple Claude instances
• Can handle hundreds of concurrent connections

Support

For issues specific to remote deployment:

1. Check server logs first
2. Verify network connectivity
3. Ensure all dependencies are installed
4. Check GitHub issues for similar problems