Skip to main content

​
Overview

Environment variables control n8n-MCP’s behavior, from server modes to database configuration. This guide covers all available options.

​
Common Configuration

​
Database Settings

​
NODE_DB_PATH
string
default:"./data/nodes.db"
Path to the SQLite database file. Must end with .db.Examples:
  • Local: ./data/nodes.db
  • Docker: /app/data/nodes.db
  • Custom: /var/lib/n8n-mcp/nodes.db
​
REBUILD_ON_START
boolean
default:"false"
Rebuild the database on server startup.Use cases:
  • Development: Test database changes
  • Production: Update after n8n version upgrades
  • CI/CD: Ensure fresh database
REBUILD_ON_START=false

​
Logging Configuration

​
MCP_LOG_LEVEL
string
default:"info"
Logging verbosity level.Options:
  • debug - Detailed logs for troubleshooting
  • info - Normal operational logs
  • warn - Warnings and errors only
  • error - Errors only
MCP_LOG_LEVEL=info
​
LOG_LEVEL
string
default:"info"
Alternative logging level variable (used in some contexts).
LOG_LEVEL=error
​
DISABLE_CONSOLE_OUTPUT
boolean
default:"false"
Disable console output to prevent interference with stdio mode.Required for Claude Desktop - Set to true to prevent JSON parsing errors.
DISABLE_CONSOLE_OUTPUT=true

​
Node Environment

​
NODE_ENV
string
default:"development"
Node.js environment mode.Options:
  • development - Development mode with detailed errors
  • production - Production mode with optimizations
NODE_ENV=production

​
Server Mode Configuration

​
MCP Mode

​
MCP_MODE
string
default:"stdio"
Server communication mode.Options:
  • stdio - Standard input/output (for Claude Desktop)
  • http - HTTP server (for remote connections, n8n integration)
# For Claude Desktop
MCP_MODE=stdio

# For remote/n8n
MCP_MODE=http
Claude Desktop requires MCP_MODE=stdio. Using http mode will cause connection failures.

​
HTTP Server Settings

​
PORT
number
default:"3000"
HTTP server port (only used when MCP_MODE=http).
PORT=3000
​
HOST
string
default:"0.0.0.0"
HTTP server host binding.
HOST=0.0.0.0
​
BASE_URL
string
Base URL for the server when running behind a proxy.Examples:
BASE_URL=https://n8n-mcp.example.com
BASE_URL=https://your-domain.com:8443
​
PUBLIC_URL
string
Alternative to BASE_URL for public-facing URL.
PUBLIC_URL=https://n8n-mcp.mydomain.com

​
Authentication

​
AUTH_TOKEN
string
required
Authentication token for HTTP mode (minimum 32 characters).Generate secure token:
openssl rand -base64 32
Usage:
AUTH_TOKEN=your-secure-token-here
​
MCP_AUTH_TOKEN
string
Alternative authentication token variable. If set, must match AUTH_TOKEN.
MCP_AUTH_TOKEN=your-secure-token-here
Both AUTH_TOKEN and MCP_AUTH_TOKEN must have the same value if both are set.

​
CORS Configuration

​
CORS_ORIGIN
string
default:"*"
CORS origin for HTTP mode.Examples:
# Allow all (development)
CORS_ORIGIN=*

# Specific domain (production)
CORS_ORIGIN=https://your-client-domain.com
​
TRUST_PROXY
number
default:"0"
Trust proxy configuration for correct IP logging.Options:
  • 0 - Disabled (direct connection)
  • 1 - Trust first proxy (Nginx, Caddy, Traefik)
  • 2+ - Number of proxy hops
# Behind reverse proxy
TRUST_PROXY=1

​
Security Configuration

​
Rate Limiting

​
AUTH_RATE_LIMIT_WINDOW
number
default:"900000"
Rate limit window in milliseconds (default: 15 minutes).
AUTH_RATE_LIMIT_WINDOW=900000
​
AUTH_RATE_LIMIT_MAX
number
default:"20"
Maximum authentication attempts per IP within window.
AUTH_RATE_LIMIT_MAX=20

​
SSRF Protection

​
WEBHOOK_SECURITY_MODE
string
default:"strict"
SSRF protection mode for webhooks.Modes:
  • strict - Block localhost + private IPs + cloud metadata (production)
  • moderate - Allow localhost, block private IPs + cloud metadata (local dev)
  • permissive - Allow localhost + private IPs, block cloud metadata (internal)
# Production (default)
WEBHOOK_SECURITY_MODE=strict

# Local development with local n8n
WEBHOOK_SECURITY_MODE=moderate
Use moderate mode when connecting to n8n running on localhost or host.docker.internal.

​
Disabled Tools

​
DISABLED_TOOLS
string
Comma-separated list of tool names to disable at startup.Use cases:
  • Multi-tenant deployments
  • Security hardening
  • Feature flags
Example:
DISABLED_TOOLS=n8n_diagnostic,n8n_health_check,custom_tool

​
Multi-Tenant Configuration

​
ENABLE_MULTI_TENANT
boolean
default:"false"
Enable multi-tenant mode for dynamic instance support.When enabled:
  • n8n API tools available for all sessions
  • Instance configuration from HTTP headers
ENABLE_MULTI_TENANT=false
​
MULTI_TENANT_SESSION_STRATEGY
string
default:"instance"
Session isolation strategy for multi-tenant mode.Options:
  • instance - Separate sessions per instance ID (recommended)
  • shared - Share sessions but switch contexts (advanced)
MULTI_TENANT_SESSION_STRATEGY=instance

​
Database Adapter Configuration

​
SQLite Adapter Selection

​
USE_BETTER_SQLITE
boolean
default:"auto"
Force use of better-sqlite3 adapter.Note: Automatically selected based on availability. Manual override rarely needed.
USE_BETTER_SQLITE=true

​
sql.js Configuration

​
SQLJS_SAVE_INTERVAL_MS
number
default:"5000"
Save interval for sql.js adapter (milliseconds).Range: 100-60000msTradeoffs:
  • Lower values = more frequent saves = higher memory churn
  • Higher values = less frequent saves = lower memory usage
# Default (recommended)
SQLJS_SAVE_INTERVAL_MS=5000

# Lower memory usage (production)
SQLJS_SAVE_INTERVAL_MS=10000

​
Cache Configuration

​
INSTANCE_CACHE_MAX
number
default:"100"
Maximum number of cached instances.Range: 1-10000
INSTANCE_CACHE_MAX=100
​
INSTANCE_CACHE_TTL_MINUTES
number
default:"30"
Cache TTL in minutes.Range: 1-1440 (24 hours)
INSTANCE_CACHE_TTL_MINUTES=30

​
OpenAI Integration

​
OPENAI_API_KEY
string
OpenAI API key for AI-powered template metadata generation.Get from: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-...
​
OPENAI_MODEL
string
default:"gpt-4o-mini"
OpenAI model for metadata generation.
OPENAI_MODEL=gpt-4o-mini
​
OPENAI_BATCH_SIZE
number
default:"100"
Batch size for metadata generation.
OPENAI_BATCH_SIZE=100
​
METADATA_GENERATION_ENABLED
boolean
default:"false"
Enable metadata generation during template fetch.
METADATA_GENERATION_ENABLED=false

​
Privacy Configuration

​
N8N_MCP_TELEMETRY_DISABLED
boolean
default:"false"
Disable anonymous telemetry collection.
N8N_MCP_TELEMETRY_DISABLED=true

​
Testing Configuration

​
N8N_TEST_CLEANUP_ENABLED
boolean
default:"true"
Enable automatic cleanup of test workflows.
N8N_TEST_CLEANUP_ENABLED=true
​
N8N_TEST_TAG
string
default:"mcp-integration-test"
Tag applied to all test workflows.
N8N_TEST_TAG=mcp-integration-test
​
N8N_TEST_NAME_PREFIX
string
default:"[MCP-TEST]"
Name prefix for test workflows.
N8N_TEST_NAME_PREFIX=[MCP-TEST]

​
Configuration Examples

​
Claude Desktop (stdio mode)

MCP_MODE=stdio
LOG_LEVEL=error
DISABLE_CONSOLE_OUTPUT=true

​
Remote HTTP Server

MCP_MODE=http
PORT=3000
HOST=0.0.0.0
AUTH_TOKEN=$(openssl rand -base64 32)
CORS_ORIGIN=https://your-domain.com
TRUST_PROXY=1

​
Local Development with n8n

MCP_MODE=http
PORT=3000
N8N_API_URL=http://localhost:5678
N8N_API_KEY=your-api-key
AUTH_TOKEN=test-token-minimum-32-chars-long
WEBHOOK_SECURITY_MODE=moderate
LOG_LEVEL=debug

​
Production Docker Deployment

MCP_MODE=http
NODE_ENV=production
PORT=3000
HOST=0.0.0.0
N8N_API_URL=https://n8n.example.com
N8N_API_KEY=${N8N_API_KEY}
AUTH_TOKEN=${AUTH_TOKEN}
TRUST_PROXY=1
LOG_LEVEL=info
WEBHOOK_SECURITY_MODE=strict
REBUILD_ON_START=false

​
Next Steps

Claude Desktop

Configure for Claude Desktop

n8n Integration

Connect to n8n instances

Database

Database configuration and optimization

Deployment

Deployment guides

Build docs developers (and LLMs) love

Get started for freeTalk to us