HTTP Deployment Guide for n8n-MCP

Deploy n8n-MCP as a remote HTTP server to provide n8n knowledge to compatible MCP Client from anywhere.

🎯 Overview

n8n-MCP HTTP mode enables:

☁️ Cloud deployment (VPS, Docker, Kubernetes)
🌐 Remote access from any Claude Desktop /Windsurf / other MCP Client
🔒 Token-based authentication
⚡ Production-ready performance (~12ms response time)
🚀 Optional n8n management tools (16 additional tools when configured)
❌ Does not work with n8n MCP Tool

📐 Deployment Scenarios

1. Local Development (Simplest)

Use stdio mode - Claude Desktop connects directly to the Node.js process:

Claude Desktop → n8n-mcp (stdio mode)

✅ No HTTP server needed
✅ No authentication required
✅ Fastest performance
❌ Only works locally

2. Local HTTP Server

Run HTTP server locally for testing remote features:

Claude Desktop → http-bridge.js → localhost:3000

✅ Test HTTP features locally
✅ Multiple Claude instances can connect
✅ Good for development
❌ Still only local access

3. Remote Server

Deploy to cloud for access from anywhere:

Claude Desktop → mcp-remote → https://your-server.com

✅ Access from anywhere
✅ Team collaboration
✅ Production-ready
❌ Requires server setup
Deploy to your VPS - if you just want remote acces, consider deploying to Railway -> Railway Deployment Guide

📋 Prerequisites

Server Requirements:

Node.js 16+ or Docker
512MB RAM minimum
Public IP or domain name
(Recommended) SSL certificate for HTTPS

Client Requirements:

Claude Desktop
Node.js 18+ (for mcp-remote)
Or Claude Pro/Team (for native remote MCP)

🚀 Quick Start

Option 1: Docker Deployment (Recommended for Production)

bash

# 1. Create environment file
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
MCP_MODE=http
PORT=3000
# Optional: Enable n8n management tools
# N8N_API_URL=https://your-n8n-instance.com
# N8N_API_KEY=your-api-key-here
# Security Configuration (v2.16.3+)
# Rate limiting (default: 20 attempts per 15 minutes)
AUTH_RATE_LIMIT_WINDOW=900000
AUTH_RATE_LIMIT_MAX=20
# SSRF protection mode (default: strict)
# Use 'moderate' for local n8n, 'strict' for production
WEBHOOK_SECURITY_MODE=strict
EOF

# 2. Deploy with Docker
docker run -d \
  --name n8n-mcp \
  --restart unless-stopped \
  --env-file .env \
  -p 3000:3000 \
  ghcr.io/czlonkowski/n8n-mcp:latest

# 3. Verify deployment
curl http://localhost:3000/health

Option 2: Local Development (Without Docker)

bash

# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2. Configure environment
export MCP_MODE=http
export AUTH_TOKEN=$(openssl rand -base64 32)
export PORT=3000

# 3. Start server
npm run start:http

Option 3: Direct stdio Mode (Simplest for Local)

Skip HTTP entirely and use stdio mode directly:

json

{
  "mcpServers": {
    "n8n-local": {
      "command": "node",
      "args": [
        "/path/to/n8n-mcp/dist/mcp/index.js"
      ],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 Save your AUTH_TOKEN - clients will need it to connect!

⚙️ Configuration

Required Environment Variables

Variable	Description	Example
`MCP_MODE`	Must be set to `http`	`http`
`AUTH_TOKEN` or `AUTH_TOKEN_FILE`	Authentication method	See security section

Optional Settings

Variable	Description	Default	Since
`PORT`	Server port	`3000`	v1.0
`HOST`	Bind address	`0.0.0.0`	v1.0
`LOG_LEVEL`	Log verbosity (error/warn/info/debug)	`info`	v1.0
`NODE_ENV`	Environment	`production`	v1.0
`TRUST_PROXY`	Trust proxy headers (0=off, 1+=hops)	`0`	v2.7.6
`BASE_URL`	Explicit public URL	Auto-detected	v2.7.14
`PUBLIC_URL`	Alternative to BASE_URL	Auto-detected	v2.7.14
`CORS_ORIGIN`	CORS allowed origins	`*`	v2.7.8
`AUTH_TOKEN_FILE`	Path to token file	-	v2.7.10

n8n Management Tools (Optional)

Enable 16 additional tools for managing n8n workflows by configuring API access:

⚠️ Requires v2.7.1+ - Earlier versions had an issue with tool registration in Docker environments.

Variable	Description	Example
`N8N_API_URL`	Your n8n instance URL	`https://your-n8n.com`
`N8N_API_KEY`	n8n API key (from Settings > API)	`n8n_api_key_xxx`
`N8N_API_TIMEOUT`	Request timeout (ms)	`30000`
`N8N_API_MAX_RETRIES`	Max retry attempts	`3`

What This Enables

When configured, you get 16 additional tools (total: 39 tools):

Workflow Management (11 tools):

n8n_create_workflow - Create new workflows
n8n_get_workflow - Get workflow by ID
n8n_update_full_workflow - Update entire workflow
n8n_update_partial_workflow - Update using diff operations (v2.7.0+)
n8n_delete_workflow - Delete workflows
n8n_list_workflows - List all workflows
And more workflow detail/structure tools

Execution Management (4 tools):

n8n_trigger_webhook_workflow - Execute via webhooks
n8n_get_execution - Get execution details
n8n_list_executions - List workflow runs
n8n_delete_execution - Delete execution records

System Tools:

n8n_health_check - Check n8n connectivity
n8n_diagnostic - System diagnostics
n8n_validate_workflow - Validate from n8n instance

Getting Your n8n API Key

Log into your n8n instance
Go to Settings > API
Click Create API Key
Copy the generated key

⚠️ Security Note: Store API keys securely and never commit them to version control.

🏗️ Architecture

How HTTP Mode Works

┌─────────────────┐        ┌─────────────┐        ┌──────────────┐
│ Claude Desktop  │ stdio  │ mcp-remote  │  HTTP  │  n8n-MCP     │
│ (stdio only)    ├───────►│ (bridge)    ├───────►│  HTTP Server │
└─────────────────┘        └─────────────┘        └──────────────┘
                                                           │
                                                           ▼
                                                   ┌──────────────┐
                                                   │ Your n8n     │
                                                   │ Instance     │
                                                   └──────────────┘

Key Points:

Claude Desktop only supports stdio communication
mcp-remote acts as a bridge, converting stdio ↔ HTTP
n8n-MCP server connects to one n8n instance (configured server-side)
All clients share the same n8n instance (single-tenant design)

🌐 Reverse Proxy Configuration

URL Configuration (v2.7.14+)

n8n-MCP intelligently detects your public URL:

Priority Order:

Explicit Configuration (highest priority):

bash

BASE_URL=https://n8n-mcp.example.com  # Full public URL
# or
PUBLIC_URL=https://api.company.com:8443/mcp

Auto-Detection (when TRUST_PROXY is enabled):

bash

TRUST_PROXY=1  # Required for proxy header detection
# Server reads X-Forwarded-Proto and X-Forwarded-Host

Fallback (local binding):

bash

# No configuration needed
# Shows: http://localhost:3000 (or configured HOST:PORT)

What You'll See in Logs:

[INFO] Starting n8n-MCP HTTP Server v2.7.17...
[INFO] Server running at https://n8n-mcp.example.com
[INFO] Endpoints:
[INFO]   Health: https://n8n-mcp.example.com/health
[INFO]   MCP:    https://n8n-mcp.example.com/mcp

Trust Proxy for Correct IP Logging

When running n8n-MCP behind a reverse proxy (Nginx, Traefik, etc.), enable trust proxy to log real client IPs instead of proxy IPs:

bash

# Enable trust proxy in your environment
TRUST_PROXY=1  # Trust 1 proxy hop (standard setup)
# or
TRUST_PROXY=2  # Trust 2 proxy hops (CDN → Load Balancer → n8n-mcp)

Without TRUST_PROXY:

[INFO] GET /health { ip: '172.19.0.2' }  # Docker internal IP

With TRUST_PROXY=1:

[INFO] GET /health { ip: '203.0.113.1' }  # Real client IP

This is especially important when:

Running in Docker/Kubernetes
Using load balancers
Debugging client issues
Implementing rate limiting

🔐 Security Setup

Authentication

All requests require Bearer token authentication:

bash

# Test authentication
curl -H "Authorization: Bearer $AUTH_TOKEN" \
     https://your-server.com/health

SSL/HTTPS (Strongly Recommended)

Use a reverse proxy for SSL termination:

Nginx example:

nginx

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mcp {
        proxy_pass http://localhost:3000;
        proxy_set_header Authorization $http_authorization;
        # Important: Forward client IP headers
        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;
    }
}

Caddy example (automatic HTTPS):

caddy

your-domain.com {
    reverse_proxy /mcp localhost:3000
}

💻 Client Configuration

⚠️ Requirements: Node.js 18+ must be installed on the client machine for mcp-remote

Method 1: Using mcp-remote (Recommended)

json

{
  "mcpServers": {
    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-server.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_AUTH_TOKEN_HERE"
      ]
    }
  }
}

Note: Replace YOUR_AUTH_TOKEN_HERE with your actual token. Do NOT use ${AUTH_TOKEN} syntax - Claude Desktop doesn't support environment variable substitution in args.

Method 2: Using Custom Bridge Script

For local testing or when mcp-remote isn't available:

json

{
  "mcpServers": {
    "n8n-local-http": {
      "command": "node",
      "args": [
        "/path/to/n8n-mcp/scripts/http-bridge.js"
      ],
      "env": {
        "MCP_URL": "http://localhost:3000/mcp",
        "AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Local Development with Docker

When testing locally with Docker:

json

{
  "mcpServers": {
    "n8n-docker-http": {
      "command": "node",
      "args": [
        "/path/to/n8n-mcp/scripts/http-bridge.js"
      ],
      "env": {
        "MCP_URL": "http://localhost:3001/mcp",
        "AUTH_TOKEN": "docker-test-token"
      }
    }
  }
}

🌐 Production Deployment

Docker Compose (Complete Example)

yaml

version: '3.8'

services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    container_name: n8n-mcp
    restart: unless-stopped
    environment:
      # Core configuration
      MCP_MODE: http
      NODE_ENV: production
      
      # Security - Using file-based secret
      AUTH_TOKEN_FILE: /run/secrets/auth_token
      
      # Networking
      HOST: 0.0.0.0
      PORT: 3000
      TRUST_PROXY: 1  # Behind Nginx/Traefik
      CORS_ORIGIN: https://app.example.com  # Restrict in production
      
      # URL Configuration
      BASE_URL: https://n8n-mcp.example.com
      
      # Logging
      LOG_LEVEL: info
      
      # Optional: n8n API Integration
      N8N_API_URL: ${N8N_API_URL}
      N8N_API_KEY_FILE: /run/secrets/n8n_api_key
      
    secrets:
      - auth_token
      - n8n_api_key
      
    ports:
      - "127.0.0.1:3000:3000"  # Only expose to localhost
      
    volumes:
      - n8n-mcp-data:/app/data:ro  # Read-only database
      
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
      
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 128M
          cpus: '0.1'
    
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

secrets:
  auth_token:
    file: ./secrets/auth_token.txt
  n8n_api_key:
    file: ./secrets/n8n_api_key.txt

volumes:
  n8n-mcp-data:

Systemd Service (Production Linux)

ini

# /etc/systemd/system/n8n-mcp.service
[Unit]
Description=n8n-MCP HTTP Server
Documentation=https://github.com/czlonkowski/n8n-mcp
After=network.target
Requires=network.target

[Service]
Type=simple
User=n8n-mcp
Group=n8n-mcp
WorkingDirectory=/opt/n8n-mcp

# Use file-based secret
Environment="AUTH_TOKEN_FILE=/etc/n8n-mcp/auth_token"
Environment="MCP_MODE=http"
Environment="NODE_ENV=production"
Environment="TRUST_PROXY=1"
Environment="BASE_URL=https://n8n-mcp.example.com"

# Additional config from file
EnvironmentFile=-/etc/n8n-mcp/config.env

ExecStartPre=/usr/bin/test -f /etc/n8n-mcp/auth_token
ExecStart=/usr/bin/node dist/mcp/index.js --http

# Restart configuration
Restart=always
RestartSec=10
StartLimitBurst=5
StartLimitInterval=60s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/n8n-mcp/data
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictSUIDSGID=true
LockPersonality=true

# Resource limits
LimitNOFILE=65536
MemoryLimit=512M
CPUQuota=50%

[Install]
WantedBy=multi-user.target

Setup:

bash

# Create user and directories
sudo useradd -r -s /bin/false n8n-mcp
sudo mkdir -p /opt/n8n-mcp /etc/n8n-mcp
sudo chown n8n-mcp:n8n-mcp /opt/n8n-mcp

# Create secure token
sudo sh -c 'openssl rand -base64 32 > /etc/n8n-mcp/auth_token'
sudo chmod 600 /etc/n8n-mcp/auth_token
sudo chown n8n-mcp:n8n-mcp /etc/n8n-mcp/auth_token

# Deploy application
sudo -u n8n-mcp git clone https://github.com/czlonkowski/n8n-mcp.git /opt/n8n-mcp
cd /opt/n8n-mcp
sudo -u n8n-mcp npm install --production
sudo -u n8n-mcp npm run build
sudo -u n8n-mcp npm run rebuild

# Start service
sudo systemctl daemon-reload
sudo systemctl enable n8n-mcp
sudo systemctl start n8n-mcp

Enable:

bash

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

📡 Monitoring & Maintenance

Health Endpoint Details

bash

# Basic health check
curl -H "Authorization: Bearer $AUTH_TOKEN" \
     https://your-server.com/health

# Response:
{
  "status": "ok",
  "mode": "http-fixed",
  "version": "2.7.17",
  "uptime": 3600,
  "memory": {
    "used": 95,
    "total": 512,
    "percentage": 18.5
  },
  "node": {
    "version": "v20.11.0",
    "platform": "linux"
  },
  "features": {
    "n8nApi": true,  // If N8N_API_URL configured
    "authFile": true  // If using AUTH_TOKEN_FILE
  }
}

🔒 Security Features (v2.16.3+)

Rate Limiting

Built-in rate limiting protects authentication endpoints from brute force attacks:

Configuration:

bash

# Defaults (15 minutes window, 20 attempts per IP)
AUTH_RATE_LIMIT_WINDOW=900000  # milliseconds
AUTH_RATE_LIMIT_MAX=20

Features:

Per-IP rate limiting with configurable window and max attempts
Standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
JSON-RPC formatted error responses
Automatic IP tracking behind reverse proxies (requires TRUST_PROXY=1)

Behavior:

First 20 attempts: Return 401 Unauthorized for invalid credentials
Attempts 21+: Return 429 Too Many Requests with Retry-After header
Counter resets after 15 minutes (configurable)

SSRF Protection

Prevents Server-Side Request Forgery attacks. The same gate applies to webhook trigger URLs (chat, form, generic webhook), the n8n API client base URL (N8N_API_URL), and per-request URLs supplied via the x-n8n-url header in multi-tenant mode.

Three Security Modes:

Strict Mode (default) - Production deployments
bash
```
WEBHOOK_SECURITY_MODE=strict
```
- ✅ Block localhost (127.0.0.1, ::1)
- ✅ Block private IPs (10.x, 192.168.x, 172.16-31.x)
- ✅ Block cloud metadata (169.254.169.254, metadata.google.internal)
- ✅ DNS rebinding prevention
- 🎯 Use for: Cloud deployments, production environments
Moderate Mode - Local development with local n8n
bash
```
WEBHOOK_SECURITY_MODE=moderate
```
- ✅ Allow localhost (for local n8n instances)
- ✅ Block private IPs
- ✅ Block cloud metadata
- ✅ DNS rebinding prevention
- 🎯 Use for: Development with n8n on localhost:5678
Permissive Mode - Internal networks only
bash
```
WEBHOOK_SECURITY_MODE=permissive
```
- ✅ Allow localhost and private IPs
- ✅ Block cloud metadata (always blocked)
- ✅ DNS rebinding prevention
- 🎯 Use for: Internal testing (NOT for production)

Important: Cloud metadata endpoints are ALWAYS blocked in all modes for security.

🔒 Security Best Practices

1. Token Management

DO:

✅ Use tokens with 32+ characters
✅ Store tokens in secure files or secrets management
✅ Rotate tokens regularly (monthly minimum)
✅ Use different tokens for each environment
✅ Monitor logs for authentication failures

DON'T:

❌ Use default or example tokens
❌ Commit tokens to version control
❌ Share tokens between environments
❌ Log tokens in plain text

bash

# Generate strong token
openssl rand -base64 32

# Secure storage options:
# 1. Docker secrets (recommended)
echo $(openssl rand -base64 32) | docker secret create auth_token -

# 2. Kubernetes secrets
kubectl create secret generic n8n-mcp-auth \
  --from-literal=token=$(openssl rand -base64 32)

# 3. HashiCorp Vault
vault kv put secret/n8n-mcp token=$(openssl rand -base64 32)

2. Network Security

✅ Always use HTTPS in production
✅ Firewall rules to limit access
✅ VPN for internal deployments
✅ Rate limiting at proxy level

3. Container Security

bash

# Run as non-root user (already configured)
# Read-only filesystem
docker run --read-only \
  --tmpfs /tmp \
  -v n8n-mcp-data:/app/data \
  n8n-mcp

# Security scanning
docker scan ghcr.io/czlonkowski/n8n-mcp:latest

🔍 Troubleshooting

Common Issues & Solutions

Authentication Issues

"Unauthorized" error:

bash

# Check token is set correctly
docker exec n8n-mcp env | grep AUTH

# Test with curl
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-server.com/health

# Common causes:
# - Extra spaces in token
# - Missing "Bearer " prefix
# - Token file has newline at end
# - Wrong quotes in JSON config

Default token warning:

⚠️ SECURITY WARNING: Using default AUTH_TOKEN

Change token immediately via environment variable
Server shows this warning every 5 minutes

Connection Issues

"TransformStream is not defined":

bash

# Check Node.js version on CLIENT machine
node --version  # Must be 18+

# Update Node.js
# macOS: brew upgrade node
# Linux: Use NodeSource repository
# Windows: Download from nodejs.org

"Cannot connect to server":

bash

# 1. Check server is running
docker ps | grep n8n-mcp

# 2. Check logs for errors
docker logs n8n-mcp --tail 50

# 3. Test locally first
curl http://localhost:3000/health

# 4. Check firewall
sudo ufw status  # Linux

"Stream is not readable":

This issue was fixed in v2.3.2+ with the SingleSessionHTTPServer
No additional configuration needed

Bridge script not working:

bash

# Test the bridge manually
export MCP_URL=http://localhost:3000/mcp
export AUTH_TOKEN=your-token
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node /path/to/http-bridge.js

Connection refused:

bash

# Check server is running
curl http://localhost:3000/health

# Check Docker status
docker ps
docker logs n8n-mcp

# Check firewall
sudo ufw status

Authentication failed:

Verify AUTH_TOKEN matches exactly
Check for extra spaces or quotes
Test with curl first

Bridge Configuration Issues

"Why use 'node' instead of 'docker' in Claude config?"

Claude Desktop only supports stdio. The architecture is:

Claude → stdio → mcp-remote → HTTP → Docker container

The node command runs mcp-remote (the bridge), not the server directly.

"Command not found: npx":

bash

# Install Node.js 18+ which includes npx
# Or use full path:
which npx  # Find npx location
# Use that path in Claude config

Debug Mode

bash

# 1. Enable debug logging
docker run -e LOG_LEVEL=debug ...

# 2. Test MCP endpoint
curl -X POST https://your-server.com/mcp \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

# 3. Test with mcp-remote directly
MCP_URL=https://your-server.com/mcp \
AUTH_TOKEN=your-token \
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  npx mcp-remote $MCP_URL --header "Authorization: Bearer $AUTH_TOKEN"

Cloud Platform Deployments

Railway: See our Railway Deployment Guide

🔧 Using n8n Management Tools

When n8n API is configured, Claude can manage workflows directly:

Example: Create a Workflow via Claude

bash

# Test n8n connectivity first
curl -X POST https://your-server.com/mcp \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "n8n_health_check",
    "params": {},
    "id": 1
  }'

Common Use Cases

Workflow Automation: Claude can create, update, and manage workflows
CI/CD Integration: Deploy workflows from version control
Workflow Templates: Claude can apply templates to new workflows
Monitoring: Track execution status and debug failures
Incremental Updates: Use diff-based updates for efficient changes

Security Best Practices for n8n API

🔐 Use separate API keys for different environments
🔄 Rotate API keys regularly
📝 Audit workflow changes via n8n's audit log
🚫 Never expose n8n API directly to the internet
✅ Use MCP server as a security layer

📦 Updates & Maintenance

Version Updates

bash

# Check current version
docker exec n8n-mcp node -e "console.log(require('./package.json').version)"

# Update to latest
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
docker stop n8n-mcp
docker rm n8n-mcp
# Re-run with same environment

# Update to specific version
docker pull ghcr.io/czlonkowski/n8n-mcp:v2.7.17

Database Management

bash

# The database is read-only and pre-built
# No backups needed for the node database
# Updates include new database versions

# Check database stats
curl -X POST https://your-server.com/mcp \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "get_database_statistics",
    "id": 1
  }'

🆘 Getting Help

📚 Full Documentation
🚂 Railway Deployment Guide - Easiest deployment option
🐛 Report Issues
💬 Community Discussions