NPM Installation Guide¶

This guide walks you through installing the n8n MCP Workflow Builder via npm, the recommended installation method for most users.

Prerequisites¶

Before installing, ensure your system meets the following requirements:

System Requirements¶

Verification Commands¶

Check your installed versions:

# Check Node.js version
node --version
# Expected output: v14.x.x or higher (v18.x.x or v20.x.x recommended)

# Check npm version
npm --version
# Expected output: 7.x.x or higher (9.x.x or 10.x.x recommended)

Operating System Compatibility¶

Installation Methods¶

Choose the installation method that best fits your use case:

Method 1: Global Installation (Recommended)¶

Global installation makes the n8n-workflow-builder command available system-wide.

Installation:

npm install -g @kernel.salacoste/n8n-workflow-builder

Expected Output:

added 45 packages in 8s

12 packages are looking for funding
  run `npm fund` for details

Verification:

# Check if globally installed
npm list -g @kernel.salacoste/n8n-workflow-builder

# Expected output:
# /usr/local/lib
# └── @kernel.salacoste/n8n-workflow-builder@0.9.1

Usage:

# Run the server
n8n-workflow-builder

# Or use npx
npx @kernel.salacoste/n8n-workflow-builder

Best For: - Personal development machines - System-wide CLI access - Multiple projects using the same version

Method 2: Local Project Installation¶

Local installation adds the package to your project's node_modules directory.

Installation:

# Navigate to your project directory
cd /path/to/your/project

# Install as a dependency
npm install @kernel.salacoste/n8n-workflow-builder

# Or install as a dev dependency
npm install --save-dev @kernel.salacoste/n8n-workflow-builder

Expected Output:

added 45 packages, and audited 46 packages in 6s

12 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Package.json Setup:

{
  "name": "my-n8n-project",
  "version": "1.0.0",
  "dependencies": {
    "@kernel.salacoste/n8n-workflow-builder": "^0.9.1"
  },
  "scripts": {
    "mcp-server": "n8n-workflow-builder"
  }
}

Usage:

# Via npx
npx @kernel.salacoste/n8n-workflow-builder

# Via npm script
npm run mcp-server

# Via node_modules
./node_modules/.bin/n8n-workflow-builder

Best For: - Project-specific installations - Version control across team members - CI/CD pipelines - Isolated project environments

Method 3: NPX Direct Execution (No Installation)¶

NPX allows you to run the package without installing it.

Command:

npx @kernel.salacoste/n8n-workflow-builder

Expected Output:

Need to install the following packages:
  @kernel.salacoste/n8n-workflow-builder@0.9.1
Ok to proceed? (y) y

[MCP Server] Starting n8n Workflow Builder MCP Server...
[MCP Server] Listening on stdio

Usage:

# One-time execution
npx @kernel.salacoste/n8n-workflow-builder

# With specific version
npx @kernel.salacoste/n8n-workflow-builder@0.9.1

# With configuration
N8N_HOST=http://localhost:5678 npx @kernel.salacoste/n8n-workflow-builder

Best For: - Quick testing without installation - CI/CD environments - Temporary usage - Trying different versions

Post-Installation Verification¶

After installation, verify everything is working correctly:

Step 1: Version Check¶

npm list -g @kernel.salacoste/n8n-workflow-builder

/usr/local/lib
└── @kernel.salacoste/n8n-workflow-builder@0.9.1

npm list @kernel.salacoste/n8n-workflow-builder

my-n8n-project@1.0.0
└── @kernel.salacoste/n8n-workflow-builder@0.9.1

npx @kernel.salacoste/n8n-workflow-builder --version

0.9.1

Step 2: Quick Test Run¶

Start the MCP server in test mode:

# For testing purposes, you can run without full configuration
npx @kernel.salacoste/n8n-workflow-builder

Expected Output:

[MCP Server] Starting n8n Workflow Builder MCP Server v0.9.1...
[MCP Server] Configuration loaded: 1 environment(s)
[MCP Server] Default environment: development
[MCP Server] Listening on stdio (MCP Protocol)
[MCP Server] Ready to accept requests

Step 3: Health Check (Optional)¶

If your server is configured and running, test the health endpoint:

# Start the server in the background
npx @kernel.salacoste/n8n-workflow-builder &

# Wait 2 seconds for startup
sleep 2

# Check health endpoint (if HTTP mode is enabled)
curl http://localhost:3456/health

Expected Response:

{
  "status": "ok",
  "version": "0.9.1",
  "timestamp": "2025-12-27T12:00:00.000Z"
}

Troubleshooting¶

Issue 1: Node.js Version Too Old¶

Symptom:

error @kernel.salacoste/n8n-workflow-builder@0.9.1:
The engine "node" is incompatible with this module.
Expected version ">=14.0.0". Got "12.22.0"

Solution:

Upgrade Node.js to version 14.0.0 or higher (18.x or 20.x recommended):

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install latest LTS version
nvm install --lts

# Use the installed version
nvm use --lts

# Verify installation
node --version  # Should show v18.x.x or v20.x.x

# Update Homebrew
brew update

# Upgrade Node.js
brew upgrade node

# Verify installation
node --version

# Ubuntu/Debian - Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version

Prevention:

Always check Node.js version before installation using node --version.

Issue 2: Permission Errors (EACCES)¶

Symptom:

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

Solution Option A: Configure npm Prefix (Recommended)

# Create a directory for global packages
mkdir ~/.npm-global

# Configure npm to use the new directory
npm config set prefix '~/.npm-global'

# Add to your PATH (add this line to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

Solution Option B: Fix Permissions

# Fix npm directory ownership (macOS/Linux)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

Solution Option C: Use Local Installation

Avoid global installation entirely:

# Install locally in your project
npm install @kernel.salacoste/n8n-workflow-builder

# Use via npx
npx @kernel.salacoste/n8n-workflow-builder

Prevention:

Configure npm prefix before installing global packages.

Issue 3: Port 3456 Already in Use¶

Symptom:

Error: listen EADDRINUSE: address already in use :::3456

Solution:

Use the MCP_PORT environment variable to specify a different port:

# Option 1: Set port for single run
MCP_PORT=58921 npx @kernel.salacoste/n8n-workflow-builder

# Option 2: Add to .env file
echo "MCP_PORT=58921" >> .env

# Option 3: Export in shell
export MCP_PORT=58921
npx @kernel.salacoste/n8n-workflow-builder

Find and Kill Process Using Port 3456:

# Find process using port 3456
lsof -i :3456

# Kill the process (replace PID with actual process ID)
kill -9 <PID>

Prevention:

Choose a unique port number between 49152-65535 (dynamic/private ports).

Issue 4: Installation Hangs or Times Out¶

Symptom:

npm install -g @kernel.salacoste/n8n-workflow-builder
[hangs indefinitely...]

Solution:

# Increase npm timeout
npm config set fetch-timeout 60000
npm config set fetch-retry-maxtimeout 120000

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

# Set proxy (if behind corporate firewall)
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

# Use npm mirror
npm config set registry https://registry.npmmirror.com

# Or reset to default
npm config set registry https://registry.npmjs.org

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

Prevention:

Configure npm timeouts and proxy settings before installation.

Issue 5: Package Not Found¶

Symptom:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/@kernel.salacoste%2fn8n-workflow-builder
npm ERR! 404 '@kernel.salacoste/n8n-workflow-builder@*' is not in this registry.

Solution:

# Correct package name (with @kernel.salacoste scope)
npm install -g @kernel.salacoste/n8n-workflow-builder

# Incorrect (without scope) - will NOT work
# npm install -g n8n-workflow-builder

# Clear npm cache
npm cache clean --force

# Verify npm registry
npm config get registry
# Should show: https://registry.npmjs.org/

# Retry installation
npm install -g @kernel.salacoste/n8n-workflow-builder

# Search for package
npm search @kernel.salacoste/n8n-workflow-builder

# View package info
npm view @kernel.salacoste/n8n-workflow-builder

# Should display package details

Prevention:

Always use the full scoped package name: @kernel.salacoste/n8n-workflow-builder

Next Steps¶

After successful installation, proceed with:

1. Configuration Setup - Set up .config.json for multi-instance support
2. Claude Desktop Integration - Connect with Claude AI
3. First Workflow Tutorial - Create your first n8n workflow

Additional Resources¶

• Manual Installation Guide - Build from source
• Configuration Reference - Complete configuration options
• Troubleshooting Guide - Advanced troubleshooting
• GitHub Repository - Source code and issues