n8n-mcp/
├── src/
│   ├── index.ts              # Entry point - server initialization
│   ├── server.ts             # MCP server implementation with dual transport
│   ├── types/               # TypeScript type definitions
│   │   ├── tools.ts        # Tool and handler types
│   │   ├── n8n-api.ts     # n8n API types
│   │   └── index.ts
│   ├── validation/           # Zod validation schemas by category
│   │   ├── base.ts         # Base schemas and utilities
│   │   ├── workflows.ts    # Workflow validation schemas
│   │   ├── credentials.ts  # Credential validation schemas
│   │   ├── tags.ts         # Tag validation schemas
│   │   ├── users.ts        # User validation schemas
│   │   ├── nodes.ts        # Node validation schemas
│   │   ├── templates.ts    # Template validation schemas
│   │   ├── audit.ts        # Audit validation schemas
│   │   └── index.ts
│   ├── tools/               # Tool definitions organized by category
│   │   ├── workflows.ts    # Workflow management tools
│   │   ├── credentials.ts  # Credential management tools
│   │   ├── tags.ts         # Tag management tools
│   │   ├── users.ts        # User management tools
│   │   ├── nodes.ts        # Node discovery tools
│   │   ├── templates.ts    # Template deployment tools
│   │   ├── audit.ts        # Audit tools
│   │   ├── documentation.ts # Documentation tools
│   │   └── index.ts
│   ├── handlers/            # Tool implementations with validation
│   │   ├── workflows.ts    # Workflow handlers
│   │   ├── credentials.ts  # Credential handlers
│   │   ├── tags.ts         # Tag handlers
│   │   ├── users.ts        # User handlers
│   │   ├── nodes.ts        # Node handlers
│   │   ├── templates.ts    # Template handlers
│   │   ├── audit.ts        # Audit handlers
│   │   ├── documentation.ts # Documentation handlers
│   │   └── index.ts
│   └── services/            # Business logic and API clients
│       └── n8n-api-client.ts # n8n API client
├── dist/                   # Compiled JavaScript (generated by build)
├── package.json
├── tsconfig.json
├── Dockerfile
└── README.md

┌─────────────┐                    ┌─────────────┐                    ┌─────────────┐
│   AI Model  │                    │  MCP Client  │                    │   n8n-mcp    │
│             │                    │   (Claude)  │                    │   (Server)    │
└─────┬─────┘                    └──────┬──────┘                    └──────┬──────┘
      │                                  │                                         │
      │ 1. Lists Tools                  │                                         │
      │<---------------------------------┘                                         │
      │                                  │                                         │
      │ 2. Request Tool                  │ 3. Call Tool (JSON)                  │
      │<---------------------------------┘<-----------------------------------┘
      │                                  │                                         │
      │ 5. Tool Result                  │ 4. n8n API Call                    │
      │<---------------------------------┘<---------------------------------┘
      │                                  │                                         │
      │                                  │                                         │
                                        │                                         │
                                        └────────────────┬─────────────────────────┘
                                                         │
                                                         │
                                                         │
                                                ┌────────┴────────┐
                                                │   n8n Instance   │
                                                └─────────────────┘

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

npm install

npm run build

# With environment variables
N8N_API_URL=https://your-n8n.com N8N_API_KEY=xxx npm start

# Or with .env file
npm start

# With environment variables
N8N_API_URL=https://your-n8n.com N8N_API_KEY=xxx npm run start:http

# Optional: Set API key for HTTP authentication
MCP_TRANSPORT=http MCP_API_KEY=your-secret-key npm run start:http

# Dockerfile for n8n-mcp
FROM node:20-alpine

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source and compiled files
COPY dist ./dist

# Create non-root user
RUN addgroup -g 1000 -S nodejs && \
    adduser -S -u 1000 -G nodejs nodejs

# Change ownership
RUN chown -R nodejs:nodejs /app

# Switch to non-root user
USER nodejs

# Expose port for HTTP mode
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

# Default command (stdio mode)
CMD ["node", "dist/index.js"]

docker build -t n8n-mcp:latest .

docker run --rm \
  -v /path/to/n8n-mcp/dist:/app/dist \
  -e N8N_API_URL=https://your-n8n.com \
  -e N8N_API_KEY=your-api-key \
  n8n-mcp:latest

docker run -d \
  --name n8n-mcp \
  -p 3000:3000 \
  -v /path/to/n8n-mcp/dist:/app/dist \
  -e N8N_API_URL=https://your-n8n.com \
  -e N8N_API_KEY=your-api-key \
  -e MCP_TRANSPORT=http \
  -e MCP_API_KEY=your-http-secret-key \
  n8n-mcp:latest

# docker-compose.yml
version: "3.8"

services:
  n8n-mcp:
    build: .
    container_name: n8n-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - N8N_API_URL=https://your-n8n-instance.com
      - N8N_API_KEY=${N8N_API_KEY}
      - MCP_TRANSPORT=http
      - MCP_API_KEY=${MCP_API_KEY}
      - PORT=3000
    volumes:
      - ./dist:/app/dist
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js (if not installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2 (process manager)
sudo npm install -g pm2

# Create application directory
sudo mkdir -p /opt/n8n-mcp
sudo chown $USER:$USER /opt/n8n-mcp
cd /opt/n8n-mcp

# Clone repository
git clone https://github.com/your-org/n8n-mcp.git .

# Install dependencies
npm install --production

# Build application
npm run build

# Create .env file
cat > .env << EOF
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key
MCP_TRANSPORT=http
PORT=3000
MCP_API_KEY=your-secret-http-key
EOF

# Protect .env file
chmod 600 .env

# Start application (HTTP mode)
pm2 start dist/index.js --name n8n-mcp -- --env-file .env

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup systemd -u $USER --hp /opt/n8n-mcp

# Allow traffic on port 3000
sudo ufw allow 3000/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

sudo apt install -y nginx

# Create Nginx config
sudo nano /etc/nginx/sites-available/n8n-mcp

# /etc/nginx/sites-available/n8n-mcp
server {
    listen 80;
    server_name your-domain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/ssl/cert.pem;
    ssl_certificate_key /path/to/ssl/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;

        # WebSocket support for SSE
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/n8n-mcp /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Create directory
mkdir -p ~/n8n-mcp
cd ~/n8n-mcp

# Clone repository
git clone https://github.com/your-org/n8n-mcp.git .

# Create .env file
cat > .env << EOF
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key
MCP_TRANSPORT=http
PORT=3000
MCP_API_KEY=your-secret-http-key
EOF

chmod 600 .env

# Start with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f

# View application status
pm2 status

# View logs
pm2 logs n8n-mcp

# Restart application
pm2 restart n8n-mcp

# Stop application
pm2 stop n8n-mcp

# Monitor resources
pm2 monit

cat > .env << EOF
N8N_API_URL=https://n8n.your-domain.com
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxx
MCP_TRANSPORT=http
PORT=3000
MCP_API_KEY=your-secret-http-key
EOF

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/index.js"],
      "env": {
        "N8N_API_URL": "https://xxxxx.es",
        "N8N_API_KEY": "xxx.xxx.xx",
        "MCP_TRANSPORT": "stdio"
      },
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/index.js"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key",

        // Optional: HTTP mode configuration
        "MCP_TRANSPORT": "http",
        "PORT": "3000",
        "MCP_API_KEY": "your-secret-http-key",

        // Optional: Node environment
        "NODE_ENV": "production"
      },
      "disabled": false
    }
  }
}

# n8n Configuration
N8N_API_URL=https://n8n.your-domain.com
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxx

# MCP Server Configuration
MCP_TRANSPORT=http
PORT=3000
MCP_API_KEY=your-secret-http-key

# Optional: Override for backward compatibility
# N8N_HOST=https://n8n.your-domain.com
# N8N_KEY=n8n_api_xxxxxxxxxxxxxxxx

curl http://localhost:3000/health

curl -H "x-api-key: your-http-secret" \
  http://localhost:3000/mcp/tools

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-http-secret" \
  -d '{
    "name": "n8n_list_workflows",
    "arguments": {"limit": 10}
  }' \
  http://localhost:3000/mcp/call

// Connect via Server-Sent Events
const eventSource = new EventSource("http://localhost:3000/mcp");

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("MCP Event:", data);
};

eventSource.onerror = (error) => {
  console.error("SSE Error:", error);
};

// In Claude, ask:
"Create a workflow named 'Hello World' with a webhook trigger and a HTTP request node that sends a GET request to https://api.example.com";

n8n_create_workflow({
  name: "Hello World",
  nodes: [
    {
      id: "webhook_1",
      name: "Webhook",
      type: "n8n-nodes-base.webhook",
      typeVersion: 1,
      position: [250, 300],
      parameters: {
        httpMethod: "POST",
        path: "hello",
      },
    },
    {
      id: "http_1",
      name: "HTTP Request",
      type: "n8n-nodes-base.httpRequest",
      typeVersion: 4.1,
      position: [450, 300],
      parameters: {
        method: "GET",
        url: "https://api.example.com",
      },
    },
  ],
  connections: {
    Webhook: {
      main: [[{ node: "HTTP Request", type: "main", index: 0 }]],
    },
  },
});

// In Claude, ask:
"List all workflows in n8n";

{
  "data": [
    {
      "id": "abc123",
      "name": "Daily Sales Report",
      "active": true,
      "tags": ["reports", "sales"],
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-20T15:30:00Z"
    }
  ],
  "nextCursor": null
}

// In Claude, ask:
"Show me the structure of workflow 'abc123' with just nodes and connections";

{
  "id": "abc123",
  "name": "Daily Sales Report",
  "nodes": [
    {
      "id": "node_1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300],
      "disabled": false
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{ "node": "HTTP Request", "type": "main", "index": 0 }]]
    }
  }
}

// In Claude, ask:
"Validate workflow 'abc123' and check for errors";

{
  "valid": false,
  "summary": {
    "totalNodes": 5,
    "enabledNodes": 5,
    "triggerNodes": 1,
    "errorCount": 2,
    "warningCount": 1
  },
  "errors": [
    {
      "node": "HTTP Request",
      "message": "Missing node ID"
    },
    {
      "node": "Webhook",
      "message": "Missing webhook path"
    }
  ],
  "warnings": [
    {
      "node": "Function",
      "message": "Node has no connections"
    }
  ]
}

// In Claude, ask:
"Disable node 'Function' in workflow 'abc123'";

{
  "success": true,
  "workflowId": "abc123",
  "applied": 1,
  "failed": 0,
  "operations": [
    {
      "index": 0,
      "type": "disableNode",
      "nodeName": "Function"
    }
  ],
  "message": "Applied 1 operations to workflow"
}

// In Claude, ask:
"Check n8n instance health";

{
  "status": "healthy",
  "n8nVersion": "1.120.0",
  "instanceId": "abc123-def456",
  "features": {
    "sourceControl": true,
    "externalHooks": true,
    "workers": false
  },
  "performance": {
    "responseTimeMs": 150,
    "cacheHitRate": "85%"
  },
  "nextSteps": ["Instance is healthy", "n8n version is up to date"]
}

// In Claude, ask:
"Generate an audit report of all workflows";

{
  "summary": {
    "totalWorkflows": 25,
    "activeWorkflows": 18,
    "inactiveWorkflows": 7,
    "credentials": 12,
    "tags": 8
  },
  "workflows": [
    {
      "id": "abc123",
      "name": "Daily Sales Report",
      "status": "active",
      "lastExecution": "2024-01-30T10:00:00Z",
      "executionsLastWeek": 7
    }
  ],
  "recommendations": [
    "Consider enabling error workflows",
    "Review inactive workflows for cleanup"
  ]
}

# Clone repository
git clone https://github.com/your-org/n8n-mcp.git
cd n8n-mcp

# Install dependencies
npm install

# Run in watch mode
npm run dev

# Run TypeScript compiler check
npm run lint

# Build for production
npm run build

# Test with MCP Inspector
npm run inspector

# Set N8N_API_URL environment variable
export N8N_API_URL=https://your-n8n-instance.com

# Or create .env file
echo "N8N_API_URL=https://your-n8n-instance.com" > .env

# Generate API key in n8n Settings → API
# Then set environment variable
export N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxx

# Or add to .env
echo "N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxx" >> .env

# Check logs
docker logs n8n-mcp

# Common causes:
# - Missing environment variables
# - Invalid N8N_API_URL or N8N_API_KEY
# - Network connectivity issues

# Clean and rebuild
npm run clean
npm run build

# Check TypeScript version
npm list typescript

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Set verbose mode
export DEBUG=n8n-mcp:*

# Or in .env
echo "DEBUG=n8n-mcp:*" >> .env

# Via HTTP endpoint
curl http://localhost:3000/health

# Via MCP tool
n8n_health_check({ mode: "diagnostic", verbose: true })