n8n Integration

Overview

n8n-MCP provides two categories of tools:

Documentation Tools - Work without n8n API (node search, documentation, validation)
Management Tools - Require n8n API credentials (create, update, execute workflows)

This guide covers how to connect n8n-MCP to your n8n instance to enable management tools.

Prerequisites

n8n Instance

Running n8n instance (local, cloud, or self-hosted)

API Access

n8n API key from Settings → API

Network Access

n8n-MCP can reach your n8n instance URL

n8n Version

n8n 1.0.0 or newer recommended

Getting n8n API Credentials

Access n8n Settings

Open your n8n instance and navigate to Settings → API

Create API Key

Click Create API Key and give it a descriptive name (e.g., “n8n-MCP”)

Copy Credentials

Save your API key securely - you’ll need:

API URL: Your n8n instance URL (e.g., https://your-instance.n8n.cloud)
API Key: The generated key (starts with n8n_api_)

Keep your API key secure. It has full access to your n8n workflows and executions.

Configuration Methods

Environment Variables

N8N_API_URL

string

required

Your n8n instance URL (without /api/v1 suffix).Examples:

# Cloud
N8N_API_URL=https://your-instance.n8n.cloud

# Self-hosted
N8N_API_URL=https://n8n.example.com

# Local development
N8N_API_URL=http://localhost:5678

# Docker (from another container)
N8N_API_URL=http://host.docker.internal:5678

N8N_API_KEY

string

required

Your n8n API key from Settings → API.

N8N_API_KEY=n8n_api_your-key-here

N8N_API_TIMEOUT

number

default:"30000"

API request timeout in milliseconds.

N8N_API_TIMEOUT=30000

N8N_API_MAX_RETRIES

number

default:"3"

Maximum number of API request retries.

N8N_API_MAX_RETRIES=3

Claude Desktop Configuration

Add n8n credentials to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "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"
      }
    }
  }
}

Docker Compose Configuration

For HTTP mode deployments:

docker-compose.yml

version: '3.8'

services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    pull_policy: always
    container_name: n8n-mcp
    restart: unless-stopped
    environment:
      - MCP_MODE=http
      - PORT=3000
      - N8N_API_URL=${N8N_API_URL}
      - N8N_API_KEY=${N8N_API_KEY}
      - AUTH_TOKEN=${AUTH_TOKEN}
      - LOG_LEVEL=info
    ports:
      - "3000:3000"

Local n8n Instance Setup

When connecting to n8n running locally:

Use Correct URL

For Docker, use host.docker.internal instead of localhost:

N8N_API_URL=http://host.docker.internal:5678

Allow Localhost Webhooks

Set security mode to moderate:

WEBHOOK_SECURITY_MODE=moderate

This allows webhooks to localhost while still blocking private networks and cloud metadata.

Test Connection

Verify connectivity:

# From host
curl http://localhost:5678/api/v1/workflows

# From Docker container
docker exec n8n-mcp curl http://host.docker.internal:5678/api/v1/workflows

Complete Local Development Configuration

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "-e", "WEBHOOK_SECURITY_MODE=moderate",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Available Management Tools

With n8n API configured, you gain access to these additional tools:

Workflow Management

n8n_create_workflow - Create new workflows with nodes and connections
n8n_get_workflow - Retrieve workflow details (full, structure, minimal modes)
n8n_update_full_workflow - Complete workflow replacement
n8n_update_partial_workflow - Efficient diff-based updates
n8n_delete_workflow - Delete workflows permanently
n8n_list_workflows - List workflows with filtering and pagination
n8n_validate_workflow - Validate workflows by ID
n8n_autofix_workflow - Auto-fix common errors
n8n_workflow_versions - Version history and rollback
n8n_deploy_template - Deploy templates from n8n.io

Execution Management

n8n_test_workflow - Test/trigger workflow execution
n8n_executions - List, get, or delete executions

System Tools

n8n_health_check - Check n8n API connectivity and features

Verify Integration

Check Health

Ask Claude: “Use n8n_health_check to verify my n8n connection”

List Workflows

Try: “Use n8n_list_workflows to show my workflows”

Test Workflow Creation

Create a simple workflow: “Create a workflow with a webhook trigger and HTTP request node”

Troubleshooting

Connection Failed

Check URL Format

Ensure URL does not include /api/v1 suffix:

# Correct
N8N_API_URL=https://your-instance.com

# Wrong
N8N_API_URL=https://your-instance.com/api/v1

Verify API Key

Test API key directly:

curl -H "X-N8N-API-KEY: your-api-key" \
     https://your-n8n-instance.com/api/v1/workflows

Check Network Access

Ensure n8n-MCP can reach n8n:

# From Docker container
docker exec n8n-mcp curl -v https://your-n8n-instance.com

Authentication Failed

Symptom: “Invalid API key” or “Authentication failed” Solutions:

Regenerate API Key

Create a new API key in n8n Settings → API

Check Key Format

API keys should start with n8n_api_

Verify Permissions

Ensure the API key has necessary permissions

Timeout Errors

Symptom: “Request timeout” or “Connection timeout” Solutions:

# Increase timeout
N8N_API_TIMEOUT=60000  # 60 seconds

# Increase retries
N8N_API_MAX_RETRIES=5

Local Docker Network Issues

Symptom: “Cannot resolve host.docker.internal” Solutions:

Linux
Docker Compose
Alternative

Add extra host to Docker run command:

docker run \
  --add-host=host.docker.internal:host-gateway \
  -e N8N_API_URL=http://host.docker.internal:5678 \
  # ... other flags

Add to service configuration:

services:
  n8n-mcp:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Use Docker network instead:

# Create network
docker network create n8n-net

# Run both on same network
docker run --network n8n-net --name n8n ...
docker run --network n8n-net -e N8N_API_URL=http://n8n:5678 ...

Security Best Practices

Use HTTPS

Always use HTTPS in production:

N8N_API_URL=https://n8n.example.com

Rotate API Keys

Regularly rotate API keys for security

Limit Permissions

Use API keys with minimal required permissions

Network Isolation

Run n8n-MCP in the same network as n8n when possible

Multi-Tenant Configuration

For SaaS platforms managing multiple n8n instances:

# Enable multi-tenant mode
ENABLE_MULTI_TENANT=true
MULTI_TENANT_SESSION_STRATEGY=instance

# Instance credentials provided via HTTP headers
# X-N8N-API-URL: https://customer1.n8n.cloud
# X-N8N-API-KEY: customer1-api-key

Multi-tenant mode only works in HTTP mode. Instance configuration comes from request headers instead of environment variables.

Next Steps

Workflow Tools

Learn about workflow management tools

Execution Tools

Test and execute workflows

Validation

Validate workflows before deployment

Deployment

Deploy with n8n MCP Client Tool

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

​Overview

​Prerequisites

n8n Instance

API Access

Network Access

n8n Version

​Getting n8n API Credentials

​Configuration Methods

​Environment Variables

​Claude Desktop Configuration

​Docker Compose Configuration

​Local n8n Instance Setup

​Complete Local Development Configuration

​Available Management Tools

​Workflow Management

​Execution Management

​System Tools

​Verify Integration

​Troubleshooting

​Connection Failed

​Authentication Failed

​Timeout Errors

​Local Docker Network Issues

​Security Best Practices

Use HTTPS

Rotate API Keys

Limit Permissions

Network Isolation

​Multi-Tenant Configuration

​Next Steps

Workflow Tools

Execution Tools

Validation

Deployment

Build docs developers (and LLMs) love

Overview

Prerequisites

Getting n8n API Credentials

Configuration Methods

Environment Variables

Claude Desktop Configuration

Docker Compose Configuration

Local n8n Instance Setup

Complete Local Development Configuration

Available Management Tools

Workflow Management

Execution Management

System Tools

Verify Integration

Troubleshooting

Connection Failed

Authentication Failed

Timeout Errors

Local Docker Network Issues

Security Best Practices

Multi-Tenant Configuration

Next Steps