Installation

This guide covers all installation methods for n8n-MCP, from quick local setup to production deployments. Choose the method that best fits your needs.

Installation methods

Hosted service

Easiest - no setup required, 100 free calls/day

npx (local)

Quick local setup, runs in minutes

Docker

Isolated and reproducible, best for production

npm install

For development and customization

Railway

One-click cloud deployment

Hosted service

The fastest way to try n8n-MCP with zero setup.

Features

Free tier: 100 tool calls per day
Instant access: Start building workflows immediately
Always up-to-date: Latest n8n nodes and templates
No infrastructure: We handle everything

Setup

Sign up at dashboard.n8n-mcp.com
Get your API key from the dashboard
Add to your MCP client configuration

For Claude Desktop, use this configuration:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["@n8n-mcp/client"],
      "env": {
        "N8N_MCP_API_KEY": "your-api-key-here",
        "MCP_MODE": "stdio"
      }
    }
  }
}

npx (Quick local setup)

Run n8n-MCP locally without installation. Best for getting started quickly.

Prerequisites

Node.js (any version)

No installation needed! Just add to your Claude Desktop configuration:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

Configuration file locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating the configuration file for changes to take effect.

Environment variables

Variable	Required	Description
`MCP_MODE`	Yes	Must be `"stdio"` for Claude Desktop
`LOG_LEVEL`	No	Logging level: `"error"`, `"warn"`, `"info"`, `"debug"`
`DISABLE_CONSOLE_OUTPUT`	Yes	Set to `"true"` to prevent protocol corruption
`N8N_API_URL`	No	Your n8n instance URL for workflow management
`N8N_API_KEY`	No	Your n8n API key for workflow management

Docker

Isolated deployment with reproducible environments. Best for production use.

Prerequisites

Docker installed and running

Install Docker

# Using Homebrew
brew install --cask docker

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

Verify installation:

docker --version

Pull the Docker image

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

Ultra-optimized image: Our Docker image is 82% smaller than typical n8n images (280MB vs 1.5GB) because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database.

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "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"
      ]
    }
  }
}

Important Docker flags:

-i: Required for MCP stdio communication
--rm: Automatically removes container when it stops
--init: Proper signal handling for graceful shutdown

Restart Claude Desktop

Close and reopen Claude Desktop for the configuration to take effect.

Local n8n instance configuration

If you’re running n8n locally (e.g., http://localhost:5678 or Docker), you need to:

Use the Docker host address: http://host.docker.internal:5678 instead of localhost
Set webhook security mode: Add WEBHOOK_SECURITY_MODE=moderate to allow local webhooks

"-e", "N8N_API_URL=http://host.docker.internal:5678",
"-e", "WEBHOOK_SECURITY_MODE=moderate"

WEBHOOK_SECURITY_MODE=moderate allows webhooks to your local n8n instance while still blocking private networks and cloud metadata endpoints. Safe for local development.

Docker environment variables

Variable	Required	Description
`MCP_MODE`	Yes	Must be `"stdio"` for Claude Desktop
`LOG_LEVEL`	No	`"error"`, `"warn"`, `"info"`, `"debug"` (default: `"error"`)
`DISABLE_CONSOLE_OUTPUT`	Yes	Set to `"true"` to prevent protocol corruption
`N8N_API_URL`	No	Your n8n instance URL
`N8N_API_KEY`	No	Your n8n API key
`WEBHOOK_SECURITY_MODE`	No	`"moderate"` for local n8n (allows localhost webhooks)
`N8N_MCP_TELEMETRY_DISABLED`	No	Set to `"true"` to disable telemetry

Local installation

For development, contributions, or custom modifications.

Prerequisites

Node.js (any version)
npm or yarn
Git

Installation steps

Clone the repository

git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

Install dependencies

npm install

Build the project

npm run build

Initialize the database

npm run rebuild

This extracts node information from n8n packages and builds the SQLite database. Takes 2-3 minutes.

Test the installation

npm start

You should see the MCP server start in stdio mode. Press Ctrl+C to stop.

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

Use absolute paths - Replace /absolute/path/to/n8n-mcp with the actual path on your system.

Development commands

# Build TypeScript
npm run build

# Rebuild node database
npm run rebuild

# Validate node data
npm run validate

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Start server (stdio mode)
npm start

# Start server (HTTP mode)
npm run start:http

# Development mode (auto-reload)
npm run dev

# Update n8n dependencies
npm run update:n8n:check  # Check for updates
npm run update:n8n        # Apply updates

Railway cloud deployment

One-click deployment to Railway’s cloud platform.

Prerequisites

Railway account (free tier available)

Setup

Deploy to Railway

Click the “Deploy on Railway” button:

Configure deployment

Sign in to Railway (or create a free account)
Configure your project name and region
Click “Deploy”
Wait 2-3 minutes for the build to complete

Get your deployment URL

After deployment:

Open your Railway project dashboard
Copy the deployment URL (e.g., https://n8n-mcp-production.up.railway.app)
Copy your auth token from the environment variables

Configure Claude Desktop

Add to your claude_desktop_config.json with the HTTPS URL:

{
  "mcpServers": {
    "n8n-mcp": {
      "url": "https://your-deployment.up.railway.app",
      "headers": {
        "Authorization": "Bearer your-auth-token"
      }
    }
  }
}

Railway benefits

Instant cloud hosting - No server setup required
Secure by default - HTTPS included, auth token warnings
Global access - Connect from any Claude Desktop
Auto-scaling - Railway handles the infrastructure
Built-in monitoring - Logs and metrics included

For detailed Railway deployment instructions, troubleshooting, and configuration examples, see the Railway Deployment Guide.

Telemetry and privacy

n8n-MCP collects anonymous usage statistics to improve the tool. View the privacy policy.

Opt out of telemetry

For npx users:

npx n8n-mcp telemetry disable

For Docker users: Add the environment variable:

"-e", "N8N_MCP_TELEMETRY_DISABLED=true"

For docker-compose:

environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"

Database configuration

n8n-MCP uses SQLite for storing node documentation. Two adapters are available:

Database 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
- Used when better-sqlite3 compilation fails
- Memory usage: ~150-200 MB stable

Memory optimization (sql.js)

If using sql.js fallback, configure the save interval:

SQLJS_SAVE_INTERVAL_MS=5000  # Default: 5000ms (5 seconds)

Lower values = more frequent saves = higher memory churn
Higher values = less frequent saves = lower memory usage
Minimum: 100ms
Recommended for production: 5000-10000ms

Docker configuration:

"-e", "SQLJS_SAVE_INTERVAL_MS=10000"

Troubleshooting

JSON parsing errors

Problem: Claude shows "Unexpected token..." errors Solution:

Verify MCP_MODE: "stdio" is set
Add DISABLE_CONSOLE_OUTPUT: "true"
Restart Claude Desktop

Database not found

Problem: Error message about nodes.db not found Solution:

For npx: The database is included in the package
For local install: Run npm run rebuild
Check that the package downloaded completely

Node.js version mismatch

Problem: Error about NODE_MODULE_VERSION Solution:

cd n8n-mcp
npm rebuild better-sqlite3
# If that doesn't work:
rm -rf node_modules && npm install

Docker permission denied

Problem: Cannot connect to Docker daemon Solution:

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

Slow performance

Problem: MCP tools respond slowly Solution:

Check database adapter: better-sqlite3 is faster than sql.js
For sql.js: Increase SQLJS_SAVE_INTERVAL_MS to 10000
Verify you’re not running multiple instances
Check system resources (RAM, CPU)

Local n8n connection fails

Problem: Can’t connect to localhost n8n from Docker Solution:

Use http://host.docker.internal:5678 instead of localhost:5678
Add WEBHOOK_SECURITY_MODE=moderate
Verify n8n is running and accessible

What’s next?

Now that n8n-MCP is installed:

Quick start guide

Learn how to use n8n-MCP effectively

GitHub repository

View source code, report issues, or contribute

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

​Installation methods

Hosted service

npx (local)

Docker

npm install

Railway

​Hosted service

​Features

​Setup

​npx (Quick local setup)

​Prerequisites

​Installation

​Configuration file locations

​Environment variables

​Docker

​Prerequisites

​Local n8n instance configuration

​Docker environment variables

​Local installation

​Prerequisites

​Installation steps

​Development commands

​Railway cloud deployment

​Prerequisites

​Setup

​Railway benefits

​Telemetry and privacy

​Opt out of telemetry

​Database configuration

​Database adapters

​Memory optimization (sql.js)

​Troubleshooting

​JSON parsing errors

​Database not found

​Node.js version mismatch

​Docker permission denied

​Slow performance

​Local n8n connection fails

​What’s next?

Quick start guide

GitHub repository

Build docs developers (and LLMs) love

Installation methods

Hosted service

Features

Setup

npx (Quick local setup)

Prerequisites

Installation

Configuration file locations

Environment variables

Docker

Prerequisites

Local n8n instance configuration

Docker environment variables

Local installation

Prerequisites

Installation steps

Development commands

Railway cloud deployment

Prerequisites

Setup

Railway benefits

Telemetry and privacy

Opt out of telemetry

Database configuration

Database adapters

Memory optimization (sql.js)

Troubleshooting

JSON parsing errors

Database not found

Node.js version mismatch

Docker permission denied

Slow performance

Local n8n connection fails

What’s next?