n8n-mcp

# n8n-MCP: Model Context Protocol for n8n

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
[![Version](https://img.shields.io/badge/version-2.7.8-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
[![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
[![n8n version](https://img.shields.io/badge/n8n-v1.100.1-orange.svg)](https://github.com/n8n-io/n8n)
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)

Empower AI assistants with deep knowledge of n8n's workflow automation capabilities. n8n-MCP (Model Context Protocol) provides AI models like Claude with comprehensive access to n8n node documentation, properties, and operations, enabling them to design, build, and validate n8n workflows effectively. Deploy in minutes and unlock the full potential of AI-assisted n8n automation.

## 💡 Overview

n8n-MCP acts as a bridge between n8n and AI models, providing structured access to:

*   **Nodes:** 525+ n8n nodes from `n8n-nodes-base` and `@n8n/n8n-nodes-langchain`.
*   **Node Properties:** ~99% coverage with detailed schemas for accurate configuration.
*   **Node Operations:** ~63.6% coverage of available actions within nodes.
*   **Documentation:** ~90% coverage from official n8n documentation, including AI nodes.
*   **AI Tools:** Identification of 263+ AI-capable nodes, enabling their use in AI-driven workflows.

## 🚀 Quick Start

Get n8n-MCP running in minutes using one of the following methods:

### Option 1: npx (Fastest - No Installation Required)

**Prerequisites:** Node.js installed on your system.

```bash
# Run directly with npx (no installation needed!)
npx n8n-mcp

Configure Claude Desktop:

Add the following configuration to your Claude Desktop config file. You can choose between a basic configuration (documentation tools only) or a full configuration (with n8n management tools, requiring n8n API credentials).

Basic Configuration (Documentation Tools Only):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

Full Configuration (with n8n Management Tools):

{
  "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"
      }
    }
  }
}

Note: npx will download and run the latest version automatically. The package includes a pre-built database with all n8n node information.

Configuration File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating the configuration.

Option 2: Docker (Easy & Isolated)

Prerequisites: Docker installed on your system.

<details> <summary><strong>📦 Install Docker</strong> (click to expand)</summary>

macOS:

# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/

Linux (Ubuntu/Debian):

# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

Windows:

# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop

# Option 2: Using Chocolatey
choco install docker-desktop

# Option 3: Download installer from https://www.docker.com/products/docker-desktop/

Verify installation:

docker --version

</details>

# Pull the Docker image (~280MB, no n8n dependencies!)
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

⚡ Ultra-optimized: The Docker image is significantly smaller than typical n8n images because it contains only the runtime MCP server and a pre-built database, without any n8n dependencies.

Configure Claude Desktop:

Add the following configuration to your Claude Desktop config file. Choose between a basic configuration (documentation tools only) or a full configuration (with n8n management tools, requiring n8n API credentials).

Basic Configuration (Documentation Tools Only):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Full Configuration (with n8n Management Tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.

Note: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).

Important: The -i flag is required for MCP stdio communication.

Configuration File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating the configuration.

Option 3: Local Installation (For Development)

Prerequisites: Node.js installed on your system.

# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2