n8n-mcp/docs/HTTP_DEPLOYMENT.md

HTTP Deployment Guide

This guide explains how to deploy n8n-MCP as a private HTTP server for remote access.

Overview

The HTTP mode allows you to run n8n-MCP on a remote server and connect to it from Claude Desktop using the mcp-remote adapter. This is designed for single-user private deployments.

Requirements

• Node.js v16+ on the server
• A server with a public IP or domain
• HTTPS proxy (nginx/caddy) for secure connections
• mcp-remote installed on the client

Server Setup

1. Clone and Build

git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

2. Configure Environment

cp .env.example .env

Edit .env:

# HTTP mode configuration
MCP_MODE=http
PORT=3000
HOST=0.0.0.0

# Generate secure token
AUTH_TOKEN=your-secure-token-here

# Other settings
NODE_DB_PATH=./data/nodes.db
MCP_LOG_LEVEL=info
NODE_ENV=production

Generate a secure token:

openssl rand -base64 32

3. Start the Server

# Using the deployment script
./scripts/deploy-http.sh

# Or manually
MCP_MODE=http npm start

The server will start on http://0.0.0.0:3000

4. Setup HTTPS Proxy (Recommended)

Using nginx:

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    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_cache_bypass $http_upgrade;
    }
}

Using Caddy:

your-domain.com {
    reverse_proxy localhost:3000
}

Client Setup

1. Install mcp-remote

npm install -g mcp-remote

2. Configure Claude Desktop

Edit Claude Desktop config:

Option 1: Using global mcp-remote installation

{
  "mcpServers": {
    "n8n-remote": {
      "command": "mcp-remote",
      "args": [
        "connect",
        "https://your-domain.com/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-secure-token-here"
      }
    }
  }
}

Option 2: Using npx (no installation required)

{
  "mcpServers": {
    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect",
        "https://your-domain.com/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-secure-token-here"
      }
    }
  }
}

Option 3: Using custom headers (if needed)

{
  "mcpServers": {
    "n8n-remote": {
      "command": "mcp-remote",
      "args": [
        "connect",
        "https://your-domain.com/mcp",
        "--header",
        "Authorization: Bearer your-secure-token-here"
      ]
    }
  }
}

3. Test Connection

1. Restart Claude Desktop
2. The MCP tools should be available
3. Test with: "List all n8n nodes"

Security Considerations

1. Always use HTTPS in production
2. Keep AUTH_TOKEN secret - treat it like a password
3. Firewall rules - Only expose necessary ports
4. Regular updates - Keep dependencies updated
5. Monitor logs - Check for unauthorized access attempts

Health Monitoring

Check server health:

curl https://your-domain.com/health

Expected response:

{
  "status": "ok",
  "mode": "http",
  "version": "2.3.0"
}

Testing

Use the included test script to verify your HTTP server:

# Test local server
./scripts/test-http.sh

# Test remote server
./scripts/test-http.sh https://your-domain.com

# Test with custom token
AUTH_TOKEN=your-token ./scripts/test-http.sh

# Verbose output
VERBOSE=1 ./scripts/test-http.sh

The test script checks:

• Health endpoint
• CORS preflight
• Authentication
• Valid MCP requests
• Error handling
• Request size limits

Troubleshooting

Connection Refused

• Check firewall rules
• Verify server is running
• Check nginx/proxy configuration
• Run the test script to diagnose

Authentication Failed

• Verify AUTH_TOKEN matches in both server and client
• Check Authorization header format
• Token should be at least 32 characters

MCP Tools Not Available

• Restart Claude Desktop
• Check mcp-remote installation
• Verify server logs for errors
• Ensure CORS headers are working

Performance Tips

1. Use a VPS with good network connectivity
2. Enable gzip compression in your proxy
3. Consider using PM2 for process management:

   pm2 start npm --name "n8n-mcp" -- run start:http
   

Example Systemd Service

Create /etc/systemd/system/n8n-mcp.service:

[Unit]
Description=n8n MCP HTTP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/n8n-mcp
ExecStart=/usr/bin/npm run start:http
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable n8n-mcp
sudo systemctl start n8n-mcp

Limitations

• Single-user design (no multi-tenancy)
• Stateless (no session persistence)
• No built-in rate limiting
• Basic token authentication only

For multi-user deployments, consider implementing a proper API gateway with user management.