n8n-mcp/docs/HTTP_DEPLOYMENT.md

# 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](./RAILWAY_DEPLOYMENT.md)


## 📋 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)
USE_FIXED_HTTP=true
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
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 USE_FIXED_HTTP=true  # Important: Use fixed implementation
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` |
| `USE_FIXED_HTTP` | **Important**: Set to `true` for stable implementation | `true` |
| `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

1. Log into your n8n instance
2. Go to **Settings** > **API**
3. Click **Create API Key**
4. 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:
1. **Explicit Configuration** (highest priority):
   ```bash
   BASE_URL=https://n8n-mcp.example.com  # Full public URL
   # or
   PUBLIC_URL=https://api.company.com:8443/mcp
   ```

2. **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
   ```

3. **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
      USE_FIXED_HTTP: true
      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="USE_FIXED_HTTP=true"
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 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":**
- Ensure `USE_FIXED_HTTP=true` is set
- Fixed in v2.3.2+

**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](./RAILWAY_DEPLOYMENT.md)

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

1. **Workflow Automation**: Claude can create, update, and manage workflows
2. **CI/CD Integration**: Deploy workflows from version control
3. **Workflow Templates**: Claude can apply templates to new workflows
4. **Monitoring**: Track execution status and debug failures
5. **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](https://github.com/czlonkowski/n8n-mcp)
- 🚂 [Railway Deployment Guide](./RAILWAY_DEPLOYMENT.md) - Easiest deployment option
- 🐛 [Report Issues](https://github.com/czlonkowski/n8n-mcp/issues)
- 💬 [Community Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)