# n8n MCP Server - Complete Deployment Guide
## Overview
The n8n MCP (Model Context Protocol) Server is a TypeScript-based application that provides documentation and tooling for n8n workflows. It can run in two modes:
- **STDIO Mode**: For local Claude Desktop integration
- **HTTP Mode**: For remote deployment and web-based access
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Local Development Setup](#local-development-setup)
3. [Production Deployment](#production-deployment)
4. [Configuration Options](#configuration-options)
5. [Troubleshooting](#troubleshooting)
6. [Security Considerations](#security-considerations)
---
## Prerequisites
### System Requirements
- **Node.js**: Version 22.x (recommended) or 18.x minimum
- **npm**: Version 8.x or higher
- **Operating System**: Linux, macOS, or Windows 10/11
### Hardware Requirements
- **Memory**: Minimum 512MB RAM, recommended 1GB+
- **Storage**: Minimum 500MB free space
- **CPU**: Any modern x64 or ARM64 processor
---
## Local Development Setup
### Step 1: Clone and Install Dependencies
```bash
# Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
# Install dependencies
npm install
# Build the TypeScript code
npm run build
# Initialize the database
npm run rebuild
```
### Step 2: Configure Environment
```bash
# Copy the example environment file
cp .env.example .env
# Edit the .env file with your preferred settings
# For local development, the defaults are usually fine
```
### Step 3: Run in Development Mode
```bash
# For STDIO mode (Claude Desktop integration)
npm run start
# For HTTP mode (web access)
npm run start:http:fixed
# For development with auto-reload
npm run dev
```
### Step 4: Verify Installation
```bash
# Test the build
npm run validate
# Run tests (optional)
npm test
# Test specific functionality
npm run test-nodes
# Verify database exists and has data
ls -la data/nodes.db
# Should show a file of several MB in size
```
---
## Database Setup
### Supabase Database Setup (Required)
This application requires Supabase as the database backend:
#### Step 1: Create Supabase Project
1. Go to [supabase.com](https://supabase.com) and create a new project
2. Note your project URL and anon key from the project settings
#### Step 2: Create Database Schema
Run this SQL in your Supabase SQL editor:
```sql
-- Create n8n_nodes table
CREATE TABLE n8n_nodes (
node_type TEXT PRIMARY KEY,
package_name TEXT NOT NULL,
display_name TEXT NOT NULL,
description TEXT,
category TEXT,
development_style TEXT CHECK(development_style IN ('declarative', 'programmatic')),
is_ai_tool BOOLEAN DEFAULT FALSE,
is_trigger BOOLEAN DEFAULT FALSE,
is_webhook BOOLEAN DEFAULT FALSE,
is_versioned BOOLEAN DEFAULT FALSE,
version TEXT,
documentation TEXT,
properties_schema JSONB,
operations JSONB,
credentials_required JSONB,
outputs JSONB,
output_names JSONB,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Create indexes
CREATE INDEX idx_n8n_nodes_package ON n8n_nodes(package_name);
CREATE INDEX idx_n8n_nodes_ai_tool ON n8n_nodes(is_ai_tool);
CREATE INDEX idx_n8n_nodes_category ON n8n_nodes(category);
-- Enable Row Level Security (optional but recommended)
ALTER TABLE n8n_nodes ENABLE ROW LEVEL SECURITY;
-- Create policy to allow all operations (adjust as needed)
CREATE POLICY "Allow all operations on n8n_nodes" ON n8n_nodes
FOR ALL USING (true);
```
#### Step 3: Configure Environment
```bash
# Set Supabase as database backend
USE_SUPABASE=true
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
```
#### Step 4: Populate Database
```bash
# Build and populate the database
npm run build
npm run rebuild
```
---
## Production Deployment
### Step 1: Server Preparation
```bash
# Update system packages (Ubuntu/Debian)
sudo apt update && sudo apt upgrade -y
# Install Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install PM2 for process management
sudo npm install -g pm2
# Create application user
sudo useradd -m -s /bin/bash n8n-mcp
sudo mkdir -p /var/www/mcp-server/n8n-mcp
sudo chown n8n-mcp:n8n-mcp /var/www/mcp-server/n8n-mcp
```
### Step 2: Application Deployment
```bash
# Switch to application user
sudo su - n8n-mcp
# Clone and build application
cd /var/www/mcp-server/n8n-mcp
git clone https://github.com/czlonkowski/n8n-mcp.git .
npm install --production
npm run build
npm run rebuild
```
### Step 3: Configure Environment
```bash
# Create production environment file
cat > /var/www/mcp-server/n8n-mcp/.env << 'EOF'
NODE_ENV=production
MCP_MODE=http
USE_FIXED_HTTP=true
PORT=3001
HOST=0.0.0.0
AUTH_TOKEN=your-secure-token-here
LOG_LEVEL=info
NODE_DB_PATH=/var/www/mcp-server/n8n-mcp/data/nodes.db
REBUILD_ON_START=true
# Optional: Reverse proxy configuration
# BASE_URL=https://n8n-mcp.yourdomain.com
# TRUST_PROXY=1
# CORS_ORIGIN=https://your-client-domain.com
# Optional: n8n API integration
# N8N_API_URL=https://your-n8n-instance.com
# N8N_API_KEY=your-n8n-api-key
EOF
# Secure the environment file
chmod 600 /var/www/mcp-server/n8n-mcp/.env
```
### Step 4: Process Management with PM2
```bash
# Create PM2 ecosystem file
cat > /var/www/mcp-server/n8n-mcp/ecosystem.config.js << 'EOF'
module.exports = {
apps: [{
name: 'n8n-mcp',
script: 'dist/mcp/index.js',
cwd: '/var/www/mcp-server/n8n-mcp',
instances: 1,
exec_mode: 'fork',
env_file: '.env',
env: {
NODE_ENV: 'production'
},
error_file: '/var/log/n8n-mcp/error.log',
out_file: '/var/log/n8n-mcp/out.log',
log_file: '/var/log/n8n-mcp/combined.log',
time: true,
max_memory_restart: '512M',
restart_delay: 4000,
max_restarts: 10,
min_uptime: '10s'
}]
};
EOF
# Create log directory
sudo mkdir -p /var/log/n8n-mcp
sudo chown n8n-mcp:n8n-mcp /var/log/n8n-mcp
# Start the application
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```
### Step 5: Reverse Proxy Setup (Nginx)
```bash
# Install Nginx
sudo apt install nginx -y
# Create Nginx configuration
sudo tee /etc/nginx/sites-available/n8n-mcp << 'EOF'
server {
listen 80;
server_name n8n-mcp.yourdomain.com;
# Security headers
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
# Rate limiting
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req zone=api burst=20 nodelay;
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 86400;
}
}
EOF
# Enable the site
sudo ln -s /etc/nginx/sites-available/n8n-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
### Step 6: SSL Certificate (Let's Encrypt)
```bash
# Install Certbot
sudo apt install certbot python3-certbot-nginx -y
# Obtain SSL certificate
sudo certbot --nginx -d n8n-mcp.yourdomain.com
# Test automatic renewal
sudo certbot renew --dry-run
```
---
## Configuration Options
### Environment Variables
#### Core Configuration
- `MCP_MODE`: Server mode (`stdio` for local, `http` for remote)
- `USE_FIXED_HTTP`: Use stable HTTP implementation (`true` recommended)
- `PORT`: HTTP server port (default: 3000)
- `HOST`: Bind address (default: 0.0.0.0 for HTTP mode)
- `NODE_ENV`: Environment (`development`, `production`)
- `LOG_LEVEL`: Logging level (`debug`, `info`, `warn`, `error`)
#### Database Configuration
- `USE_SUPABASE`: Use Supabase as database backend (always `true`)
- `SUPABASE_URL`: Supabase project URL (required)
- `SUPABASE_ANON_KEY`: Supabase anonymous key (required)
- `REBUILD_ON_START`: Rebuild database on startup (`true`/`false`)
#### Security Configuration
- `AUTH_TOKEN`: Required authentication token for HTTP mode
- `CORS_ORIGIN`: Allowed CORS origins (default: `*`)
- `TRUST_PROXY`: Trust proxy headers for IP logging (0=disabled, 1=enabled)
- `BASE_URL`: Base URL for the server (auto-detected if not set)
#### n8n API Integration (Optional)
- `N8N_API_URL`: Your n8n instance URL
- `N8N_API_KEY`: n8n API key
- `N8N_API_TIMEOUT`: API request timeout (default: 30000ms)
- `N8N_API_MAX_RETRIES`: Max API retry attempts (default: 3)
### Available Scripts
```bash
# Build and development
npm run build # Compile TypeScript
npm run rebuild # Rebuild database
npm run dev # Development mode with rebuild
npm run validate # Validate installation
# Server modes
npm run start # STDIO mode
npm run start:http # HTTP mode
npm run http # Build + HTTP mode
# Testing
npm test # Run all tests
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:coverage # Coverage report
# Database operations
npm run db:rebuild # Rebuild database
npm run migrate:fts5 # Migrate to FTS5 search
# Utilities
npm run fetch:templates # Fetch workflow templates
npm run sanitize:templates # Clean template data
```
---
## Troubleshooting
### Common Issues
#### 1. Database Not Found Error
```bash
# Symptoms: "nodes.db not found" error
# Solution:
npm run build
npm run rebuild
```
#### 2. Database Table Missing Error
```bash
# Symptoms: "no such table: nodes" error
# Solution: Rebuild the database
cd /var/www/mcp-server/n8n-mcp
npm run rebuild
# Or set REBUILD_ON_START=true in .env and restart
echo "REBUILD_ON_START=true" >> .env
pm2 restart n8n-mcp
# Verify database was created
ls -la data/nodes.db
sqlite3 data/nodes.db "SELECT COUNT(*) FROM nodes;"
```
#### 2. Node.js Version Mismatch
```bash
# Symptoms: "NODE_MODULE_VERSION" error
# Solution:
npm rebuild better-sqlite3
# Or if that fails:
rm -rf node_modules
npm install
```
#### 4. Authentication Failures
```bash
# Symptoms: 401 Unauthorized errors
# Solution: Verify AUTH_TOKEN is set correctly
echo $AUTH_TOKEN
# Test with curl:
curl -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:3001/health
```
#### 5. Port Already in Use
```bash
# Symptoms: "EADDRINUSE" error
# Solution: Change port or kill existing process
lsof -ti:3000 | xargs kill -9
# Or change PORT in .env file
```
### Health Checks
#### Basic Health Check
```bash
# For HTTP mode
curl -H "Authorization: Bearer your-token" http://localhost:3001/health
# Expected response: {"status":"ok","timestamp":"..."}
```
#### Detailed Status Check
```bash
# Check PM2 process status
pm2 status
# Check logs
pm2 logs n8n-mcp
# Check resource usage
pm2 monit
```
#### Database Verification
```bash
# Verify database exists and is readable
ls -la data/nodes.db
# Expected: File size should be several MB (contains n8n node documentation)
# Test database queries
npm run test-nodes
# Verify database content (should show node count)
sqlite3 data/nodes.db "SELECT COUNT(*) as node_count FROM nodes;"
```
### Performance Monitoring
#### Memory Usage
```bash
# Monitor memory usage with PM2
pm2 monit
# Or use system tools
htop
# Or
ps aux | grep n8n-mcp
```
#### Log Analysis
```bash
# View recent logs
pm2 logs n8n-mcp --lines 100
# Search for errors
pm2 logs n8n-mcp | grep -i error
# Monitor real-time logs
pm2 logs n8n-mcp -f
```
---
## Security Considerations
### Authentication
- **Always** set a strong `AUTH_TOKEN` for HTTP mode
- Use `openssl rand -base64 32` to generate secure tokens
- Rotate tokens regularly in production
### Network Security
- Use HTTPS in production (configure reverse proxy with SSL)
- Set appropriate `CORS_ORIGIN` (avoid `*` in production)
- Configure `TRUST_PROXY` correctly when behind a reverse proxy
- Use firewall rules to restrict access to necessary ports only
### Application Security
- Run the application as a non-root user (n8n-mcp)
- Set restrictive file permissions on configuration files
- Use environment variables for sensitive configuration
- Regularly update Node.js and dependencies
- Monitor for security vulnerabilities
### Data Protection
- Database contains n8n node documentation (no sensitive user data)
- Ensure proper file permissions on database file (600)
- Regular backups of the database volume (optional, can be rebuilt)
### Production Hardening
```bash
# Set restrictive file permissions
chmod 600 .env
chmod 755 dist/
# Use systemd for process management instead of PM2 (optional)
sudo systemctl enable n8n-mcp
sudo systemctl start n8n-mcp
# Configure log rotation
sudo tee /etc/logrotate.d/n8n-mcp << 'EOF'
/var/log/n8n-mcp/*.log {
daily
missingok
rotate 14
compress
notifempty
create 644 n8n-mcp n8n-mcp
postrotate
pm2 reloadLogs
endscript
}
EOF
```
---
## Integration Examples
### Claude Desktop Integration (STDIO Mode)
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/var/www/mcp-server/n8n-mcp/dist/mcp/index.js"],
"env": {
"MCP_MODE": "stdio"
}
}
}
}
```
### HTTP Client Integration
```javascript
// Example HTTP client usage
const response = await fetch('http://localhost:3001/mcp', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-auth-token'
},
body: JSON.stringify({
jsonrpc: '2.0',
method: 'tools/list',
id: 1
})
});
```
### n8n Workflow Integration
When `N8N_API_URL` and `N8N_API_KEY` are configured, you get 16 additional tools:
- Workflow management (create, update, delete)
- Execution management (start, stop, monitor)
- Template operations (import, export)
- Validation and testing tools
---
## Maintenance
### Regular Updates
```bash
# Update to latest version
git pull origin main
npm install
npm run build
npm run rebuild
# Restart the application
pm2 restart n8n-mcp
```
### Database Maintenance
```bash
# Rebuild database with latest n8n nodes
npm run rebuild
# Optimize database (optional)
npm run db:rebuild
```
### Backup and Recovery
```bash
# Backup database
cp /var/www/mcp-server/n8n-mcp/data/nodes.db ./backup-nodes.db
# Restore database
cp ./backup-nodes.db /var/www/mcp-server/n8n-mcp/data/nodes.db
pm2 restart n8n-mcp
# Note: The database can be rebuilt from scratch if lost
# It contains n8n node documentation that can be regenerated
npm run rebuild
# Or set REBUILD_ON_START=true in environment
```
---
## Support and Resources
### Documentation
- GitHub Repository: https://github.com/czlonkowski/n8n-mcp
- Issues and Bug Reports: https://github.com/czlonkowski/n8n-mcp/issues
- Model Context Protocol: https://modelcontextprotocol.io/
### Community
- Report issues on GitHub
- Check existing issues before creating new ones
- Provide detailed error logs and environment information
### Version Information
- Current Version: 2.10.8
- Node.js Compatibility: 18.x, 20.x, 22.x
---
*Last Updated: 2025-09-07*
*Guide Version: 1.0*
