n8n-mcp/docs/INSTALLATION.md

Installation Guide

This guide covers all installation methods for n8n-MCP.

Table of Contents

• Quick Start
• Docker Installation
• Manual Installation
• Development Setup
• Troubleshooting

Quick Start

The fastest way to get n8n-MCP running:

# Using Docker (recommended)
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
USE_FIXED_HTTP=true
EOF
docker compose up -d

Docker Installation

Prerequisites

• Docker Desktop or Docker Engine
• Docker Compose (included with Docker Desktop)

Method 1: Using Pre-built Images

1. Create a project directory:

   mkdir n8n-mcp && cd n8n-mcp
   

2. Create docker-compose.yml:

   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}
         USE_FIXED_HTTP: ${USE_FIXED_HTTP:-true}
         AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required}
         NODE_ENV: ${NODE_ENV:-production}
         LOG_LEVEL: ${LOG_LEVEL:-info}
         PORT: ${PORT:-3000}
   
       volumes:
         - n8n-mcp-data:/app/data
   
       ports:
         - "${PORT:-3000}:3000"
   
       healthcheck:
         test: ["CMD", "curl", "-f", "http://127.0.0.1:3000/health"]
         interval: 30s
         timeout: 10s
         retries: 3
   
   volumes:
     n8n-mcp-data:
       driver: local
   

3. Create .env file:

   echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
   

4. Start the container:

   docker compose up -d
   

5. Verify installation:

   curl http://localhost:3000/health
   

Method 2: Building from Source

1. Clone the repository:

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

2. Build the image:

   docker build -t n8n-mcp:local .
   

3. Run with docker-compose:

   docker compose up -d
   

Docker Management Commands

# View logs
docker compose logs -f

# Stop the container
docker compose stop

# Remove container and volumes
docker compose down -v

# Update to latest image
docker compose pull
docker compose up -d

# Execute commands inside container
docker compose exec n8n-mcp npm run validate

# Backup database
docker cp n8n-mcp:/app/data/nodes.db ./nodes-backup.db

Manual Installation

Prerequisites

• Node.js v16+ (v20+ recommended)
• npm or yarn
• Git

Step-by-Step Installation

1. Clone the repository:

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

2. Clone n8n documentation (optional but recommended):

   git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
   

3. Install dependencies:

   npm install
   

4. Build the project:

   npm run build
   

5. Initialize the database:

   npm run rebuild
   

6. Validate installation:

   npm run test-nodes
   

Running the Server

stdio Mode (for Claude Desktop)

npm start

HTTP Mode (for remote access)

npm run start:http

Environment Configuration

Create a .env file in the project root:

# Server configuration
MCP_MODE=http          # or stdio
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info

# Authentication (required for HTTP mode)
AUTH_TOKEN=your-secure-token-here

# Database
NODE_DB_PATH=./data/nodes.db
REBUILD_ON_START=false

Development Setup

Prerequisites

• All manual installation prerequisites
• TypeScript knowledge
• Familiarity with MCP protocol

Setup Steps

1. Clone and install:

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

2. Set up development environment:

   cp .env.example .env
   # Edit .env with your settings
   

3. Development commands:

   # Run in development mode with auto-reload
   npm run dev
   
   # Run tests
   npm test
   
   # Type checking
   npm run typecheck
   
   # Linting
   npm run lint
   

Docker Development

1. Use docker-compose override:

   cp docker-compose.override.yml.example docker-compose.override.yml
   

2. Edit override for development:

   version: '3.8'
   
   services:
     n8n-mcp:
       build: .
       environment:
         NODE_ENV: development
         LOG_LEVEL: debug
       volumes:
         - ./src:/app/src:ro
         - ./dist:/app/dist
   

3. Run with live reload:

   docker compose up --build
   

Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3000
lsof -i :3000

# Use a different port
PORT=3001 docker compose up -d

Database Initialization Failed

# For Docker
docker compose exec n8n-mcp npm run rebuild

# For manual installation
npm run rebuild

Permission Denied Errors

# Fix permissions (Linux/macOS)
sudo chown -R $(whoami) ./data

# For Docker volumes
docker compose exec n8n-mcp chown -R nodejs:nodejs /app/data

Node Version Mismatch

The project includes automatic fallback to sql.js for compatibility. If you still have issues:

# Check Node version
node --version

# Use nvm to switch versions
nvm use 20

Getting Help

1. Check the logs:

   • Docker: docker compose logs
   • Manual: Check console output or LOG_LEVEL=debug npm start

2. Validate the database:

   npm run validate
   

3. Run tests:

   npm test
   

4. Report issues:

   • GitHub Issues: https://github.com/czlonkowski/n8n-mcp/issues
   • Include logs and environment details

Next Steps

After installation, configure Claude Desktop to use n8n-MCP:

• See Claude Desktop Setup Guide
• For remote deployments, see HTTP Deployment Guide
• For Docker details, see Docker README