Deploy with Docker

Overview

Docker provides an isolated, reproducible environment for n8n-MCP. The official image is 82% smaller than typical n8n images (~280MB) because it contains NO n8n dependencies—just the runtime MCP server with a pre-built database.

Prerequisites

macOS
Linux
Windows

# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

# Using winget
winget install Docker.DockerDesktop

# Or download from https://www.docker.com/products/docker-desktop/

Verify installation:

docker --version

Quick Start with Docker

Pull and run the pre-built image:

# Pull the Docker image (~280MB)
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

Claude Desktop Configuration

Basic Configuration (Documentation Tools Only)

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

The -i flag is required for MCP stdio communication.

Full Configuration (With n8n Management Tools)

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Local n8n Instance Configuration

If running n8n locally on the same machine:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "-e", "WEBHOOK_SECURITY_MODE=moderate",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Set WEBHOOK_SECURITY_MODE=moderate to allow webhooks to your local n8n instance. This is safe for local development while still blocking private networks and cloud metadata.

Docker Compose Deployment

Setup

Create a docker-compose.yml file:

version: '3.8'

services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    container_name: n8n-mcp
    restart: unless-stopped
    
    environment:
      MCP_MODE: ${MCP_MODE:-http}
      AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required for HTTP mode}
      NODE_ENV: ${NODE_ENV:-production}
      LOG_LEVEL: ${LOG_LEVEL:-info}
      PORT: ${PORT:-3000}
      NODE_DB_PATH: ${NODE_DB_PATH:-/app/data/nodes.db}
      REBUILD_ON_START: ${REBUILD_ON_START:-false}
      
      # Telemetry (optional - disabled by default in this example)
      # N8N_MCP_TELEMETRY_DISABLED: ${N8N_MCP_TELEMETRY_DISABLED:-true}
      
      # Optional: n8n API configuration
      # N8N_API_URL: ${N8N_API_URL}
      # N8N_API_KEY: ${N8N_API_KEY}
    
    volumes:
      - n8n-mcp-data:/app/data
    
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
    
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://127.0.0.1:$${PORT:-3000}/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  n8n-mcp-data:
    driver: local

Create a .env file:

AUTH_TOKEN=$(openssl rand -base64 32)
MCP_MODE=http
PORT=3000
LOG_LEVEL=info

Start the Service

# Start in detached mode
docker compose up -d

# Check logs
docker compose logs -f

# Test health endpoint
curl http://localhost:3000/health

Environment Variables

Variable	Description	Default
`MCP_MODE`	Server mode: `stdio` or `http`	`stdio`
`AUTH_TOKEN`	Bearer token for HTTP authentication	Required for HTTP
`PORT`	HTTP server port	`3000`
`LOG_LEVEL`	Logging level	`info`
`NODE_DB_PATH`	Custom database path	`/app/data/nodes.db`
`N8N_API_URL`	n8n instance URL for workflow management	Optional
`N8N_API_KEY`	API key from n8n Settings → API	Optional
`N8N_MCP_TELEMETRY_DISABLED`	Disable anonymous usage statistics	`false`
`WEBHOOK_SECURITY_MODE`	SSRF protection: `strict`/`moderate`/`permissive`	`strict`
`SQLJS_SAVE_INTERVAL_MS`	Save interval for sql.js fallback	`5000`

Database Adapters

n8n-MCP uses SQLite with two available adapters:

better-sqlite3 (Default in Docker)
- Native C++ bindings for best performance
- Direct disk writes (no memory overhead)
- Memory usage: ~100-120 MB stable
sql.js (Fallback)
- Pure JavaScript implementation
- In-memory database with periodic saves
- Memory usage: ~150-200 MB stable

Image Details

Base: node:22-alpine
Size: ~280MB compressed
Database: Complete SQLite with 1,084 nodes (537 core + 547 community)
Architectures: linux/amd64, linux/arm64
Registry: ghcr.io/czlonkowski/n8n-mcp

Docker Commands

# Pull latest image
docker compose pull

# View logs
docker compose logs -f n8n-mcp

# Stop service
docker compose stop

# Start service
docker compose start

# Restart service
docker compose restart

# Remove container and volumes
docker compose down -v

# Execute command in container
docker compose exec n8n-mcp npm run validate

# Access container shell
docker compose exec n8n-mcp sh

Disabling Telemetry

Add to your docker-compose.yml:

environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"

Or in docker run command:

-e "N8N_MCP_TELEMETRY_DISABLED=true"

Troubleshooting

Container Exits Immediately

Check logs:

docker compose logs n8n-mcp

Common causes:

Missing AUTH_TOKEN in HTTP mode
Port already in use
Database initialization failure

Permission Errors

docker compose exec n8n-mcp chown -R nodejs:nodejs /app/data

Debug Mode

Enable debug logging:

docker compose exec n8n-mcp sh -c 'LOG_LEVEL=debug node dist/mcp/index.js'

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

Deploy with Docker

Overview

Prerequisites

Quick Start with Docker

Claude Desktop Configuration

Basic Configuration (Documentation Tools Only)

Full Configuration (With n8n Management Tools)

Local n8n Instance Configuration

Docker Compose Deployment

Setup

Start the Service

Environment Variables

Database Adapters

Image Details

Docker Commands

Disabling Telemetry

Troubleshooting

Container Exits Immediately

Permission Errors

Debug Mode

Next Steps

Railway Deployment

Local Development

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

​Overview

​Prerequisites

​Quick Start with Docker

​Claude Desktop Configuration

​Basic Configuration (Documentation Tools Only)

​Full Configuration (With n8n Management Tools)

​Local n8n Instance Configuration

​Docker Compose Deployment

​Setup

​Start the Service

​Environment Variables

​Database Adapters

​Image Details

​Docker Commands

​Disabling Telemetry

​Troubleshooting

​Container Exits Immediately

​Permission Errors

​Debug Mode

​Next Steps

Railway Deployment

Local Development

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Start with Docker

Claude Desktop Configuration

Basic Configuration (Documentation Tools Only)

Full Configuration (With n8n Management Tools)

Local n8n Instance Configuration

Docker Compose Deployment

Setup

Start the Service

Environment Variables

Database Adapters

Image Details

Docker Commands

Disabling Telemetry

Troubleshooting

Container Exits Immediately

Permission Errors

Debug Mode

Next Steps