Skip to main content

​
Overview

Local installation gives you full control over the n8n-MCP source code, perfect for:
  • Development and contributions
  • Custom modifications
  • Testing new features
  • Understanding the codebase

​
Prerequisites

  • Node.js (v16+ required, v20+ recommended)
  • npm or yarn
  • Git
  • (Optional) n8n instance for workflow management

​
Installation Steps

​
1. Clone and Setup

# Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Initialize database
npm run rebuild

# Test it works
npm start
The npm run rebuild command downloads n8n packages and builds the node database. This can take 2-3 minutes.

​
2. (Optional) Clone n8n Documentation

For enhanced documentation coverage: 
# From the parent directory of n8n-mcp
cd ..
git clone https://github.com/n8n-io/n8n-docs.git
The rebuild script will automatically detect and use the n8n-docs if available.

​
Configuration

​
Environment Variables

Create a .env file in the project root: 
cp .env.example .env
Edit .env with your settings: 
# Server configuration
MCP_MODE=stdio          # or http
PORT=3000
HOST=0.0.0.0
NODE_ENV=development
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

# Optional: n8n API integration
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key

# Telemetry (optional)
N8N_MCP_TELEMETRY_DISABLED=true

​
Claude Desktop Configuration

​
Basic Configuration (Documentation Tools Only)

{
  "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 the absolute path to your n8n-mcp installation, not a relative path.

​
Full Configuration (With n8n Management Tools)

{
  "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",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

​
Local n8n Instance

If running n8n locally via Docker: 
{
  "env": {
    "N8N_API_URL": "http://host.docker.internal:5678",
    "N8N_API_KEY": "your-api-key"
  }
}
The n8n API credentials can be configured either in the .env file or directly in the Claude config.

​
Development Commands

​
Build & Test

# Build TypeScript
npm run build

# Rebuild node database
npm run rebuild

# Test critical nodes
npm run test-nodes

# Validate node data
npm run validate

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

​
Run Server

# Development mode (stdio)
npm run dev

# Start stdio mode
npm start

# Start HTTP mode
npm run start:http

# Development with auto-reload
npm run dev:http

​
Update Dependencies

# Check for n8n updates
npm run update:n8n:check

# Update n8n packages
npm run update:n8n

​
Project Structure

n8n-mcp/
├── src/
│   ├── loaders/          # NPM package loader
│   ├── parsers/          # Node parsing and extraction
│   ├── mappers/          # Documentation mapping
│   ├── database/         # SQLite schema and repositories
│   ├── services/         # Business logic
│   ├── templates/        # Template fetching and storage
│   ├── mcp/             # MCP server and tools
│   └── scripts/         # Build and maintenance scripts
├── data/
│   └── nodes.db         # SQLite database (generated)
├── dist/                # Compiled JavaScript (generated)
├── tests/               # Test suites
└── package.json         # Dependencies and scripts

​
Testing

​
Run Test Suites

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# Watch mode
npm run test:watch

# With UI
npm run test:ui

​
Test Specific Features

# Test essentials tools
npm run test:essentials

# Test validation system
npm run test:enhanced-validation

# Test workflow validation
npm run test:workflow-validation

# Test template functionality
npm run test:templates

# Test MCP tools
npm run test:mcp-tools

​
Debugging

​
Enable Debug Logging

# In .env file
LOG_LEVEL=debug

# Or as environment variable
LOG_LEVEL=debug npm start

​
Debug MCP Protocol

# Test stdio communication
npm run test:mcp-stdio

# Test HTTP endpoint
npm run test:mcp-endpoint

​
Database Issues

# Rebuild from scratch
npm run db:rebuild

# Migrate to FTS5 (if needed)
npm run migrate:fts5

# Validate database integrity
npm run validate

​
Common Issues

​
Build Fails

Ensure TypeScript is installed: 
npm install -g typescript
npm run build

​
Database Not Found

Rebuild the database: 
npm run rebuild

​
Node Version Issues

Check your Node.js version: 
node --version  # Should be v16+ (v20+ recommended)
Use nvm to switch versions: 
nvm install 20
nvm use 20

​
better-sqlite3 Compilation Errors

n8n-MCP automatically falls back to sql.js if better-sqlite3 fails to compile. This is normal and doesn’t affect functionality.

​
Contributing

When making changes:
  1. Create a feature branch: 
    git checkout -b feature/your-feature
  2. Make your changes and test: 
    npm run build
npm test
npm run typecheck
  3. Run validation: 
    npm run validate
npm run test-nodes
  4. Submit a pull request with:
    • Clear description of changes
    • Test coverage for new features
    • Documentation updates

​
Environment Variables Reference

VariableDescriptionDefault
MCP_MODEServer mode: stdio or httpstdio
PORTHTTP server port3000
HOSTHTTP server host0.0.0.0
NODE_ENVEnvironment: development or productiondevelopment
LOG_LEVELLogging levelinfo
AUTH_TOKENBearer token for HTTP modeRequired for HTTP
NODE_DB_PATHDatabase file path./data/nodes.db
REBUILD_ON_STARTAuto-rebuild database on startfalse
N8N_API_URLn8n instance URLOptional
N8N_API_KEYn8n API keyOptional
N8N_MCP_TELEMETRY_DISABLEDDisable telemetryfalse
DISABLE_CONSOLE_OUTPUTPrevent debug logs in stdiofalse

​
Next Steps

Development Guide

Learn about the codebase architecture

Contributing

Contribute to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us