# n8n-mcp

> MCP Server

**n8n workflow builder MCP for Claude Desktop/Code/Windsurf/Cursor. Automates n8n workflow creation using AI.**

## Overview

- **Category:** AI
- **Language:** TypeScript
- **Stars:** 22857
- **Forks:** 205
- **Owner:** czlonkowski
- **GitHub:** https://github.com/czlonkowski/n8n-mcp
- **Homepage:** https://www.n8n-mcp.com/
- **Created:** 2025-06-07T12:15:57+00:00
- **Updated:** 2025-07-07T16:55:50+00:00
- **Source:** https://model-context-protocol.com/servers/n8n-mcp

## Setup

## Setup

### Option 1: npx (Fastest - No Installation!) 🚀

**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system

1.  **Run n8n-MCP:**

    ```bash
    npx n8n-mcp
    ```

2.  **Configure Claude Desktop:**

    Add the following configuration to your Claude Desktop config file. Choose either the basic or full configuration based on your needs.

    **Basic configuration (documentation tools only):**

    ```json
    {
      "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):**

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

    *   Replace `https://your-n8n-instance.com` with the URL of your n8n instance.
    *   Replace `your-api-key` with your n8n API key.

    **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`

3.  **Restart Claude Desktop:**

    Restart Claude Desktop after updating the configuration file.

**Environment Variables:**

*   `MCP_MODE`: Set to `stdio` for Claude Desktop integration.
*   `LOG_LEVEL`: Set to `error` to minimize console output.
*   `DISABLE_CONSOLE_OUTPUT`: Set to `true` to disable console output.
*   `N8N_API_URL` (Optional): URL of your n8n instance. Required for workflow management tools.
*   `N8N_API_KEY` (Optional): API key for your n8n instance. Required for workflow management tools.

### Option 2: Docker (Easy & Isolated) 🐳

**Prerequisites:** Docker installed on your system

1.  **Pull the Docker image:**

    ```bash
    docker pull ghcr.io/czlonkowski/n8n-mcp:latest
    ```

2.  **Configure Claude Desktop:**

    Add the following configuration to your Claude Desktop config file. Choose either the basic or full configuration based on your needs.

    **Basic configuration (documentation tools only):**

    ```json
    {
      "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):**

    ```json
    {
      "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"
          ]
        }
      }
    }
    ```

    *   Replace `https://your-n8n-instance.com` with the URL of your n8n instance.
    *   Replace `your-api-key` with your n8n API key.
    *   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`.

    **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`

3.  **Restart Claude Desktop:**

    Restart Claude Desktop after updating the configuration file.

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

**Environment Variables (Docker):**

*   `MCP_MODE`: Set to `stdio` for Claude Desktop integration.
*   `LOG_LEVEL`: Set to `error` to minimize console output.
*   `DISABLE_CONSOLE_OUTPUT`: Set to `true` to disable console output.
*   `N8N_API_URL` (Optional): URL of your n8n instance. Required for workflow management tools.
*   `N8N_API_KEY` (Optional): API key for your n8n instance. Required for workflow management tools.

### Option 3: Local Installation (For Development)

**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system

1.  **Clone and setup:**

    ```bash
    git clone https://github.com/czlonkowski/n8n-mcp.git
    cd n8n-mcp
    npm install
    npm run build
    npm run rebuild
    ```

2.  **Test the installation:**

    ```bash
    npm start
    ```

3.  **Configure Claude Desktop:**

    Add the following configuration to your Claude Desktop config file. Choose either the basic or full configuration based on your needs.  Replace `/absolute/path/to/n8n-mcp` with the actual absolute path to the cloned `n8n-mcp` directory.

    **Basic configuration (documentation tools only):**

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

    **Full configuration (with n8n management tools):**

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

    *   Replace `https://your-n8n-instance.com` with the URL of your n8n instance.
    *   Replace `your-api-key` with your n8n API key.
    *   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`.

    **Configuration file locations:**

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

## Tools

## Available Tools

- **🔍 Smart Node Search**: Find nodes by name, category, or functionality.
- **📖 Essential Properties**: Get only the 10-20 properties that matter.
- **🎯 Task Templates**: Pre-configured settings for common automation tasks.
- **✅ Config Validation**: Validate node configurations before deployment.
- **🔗 Dependency Analysis**: Understand property relationships and conditions.
- **💡 Working Examples**: Real-world examples for immediate use.
- **⚡ Fast Response**: Average query time ~12ms with optimized SQLite.
- **🌐 Universal Compatibility**: Works with any Node.js version.

### Core Tools
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!).
- **`list_nodes`** - List all n8n nodes with filtering options.
- **`get_node_info`** - Get comprehensive information about a specific node.
- **`get_node_essentials`** - Get only essential properties with examples (10-20 properties instead of 200+).
- **`search_nodes`** - Full-text search across all node documentation.
- **`search_node_properties`** - Find specific properties within nodes.
- **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!).
- **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool.

### Advanced Tools
- **`get_node_for_task`** - Pre-configured node settings for common tasks.
- **`list_tasks`** - Discover available task templates.
- **`validate_node_operation`** - Validate node configurations (operation-aware, profiles support).
- **`validate_node_minimal`** - Quick validation for just required fields.
- **`validate_workflow`** - Complete workflow validation including AI tool connections.
- **`validate_workflow_connections`** - Check workflow structure and AI tool connections.
- **`validate_workflow_expressions`** - Validate n8n expressions including $fromAI().
- **`get_property_dependencies`** - Analyze property visibility conditions.
- **`get_node_documentation`** - Get parsed documentation from n8n-docs.
- **`get_database_statistics`** - View database metrics and coverage.

### n8n Management Tools (Optional - Requires API Configuration)
These powerful tools allow you to manage n8n workflows directly from Claude. They're only available when you provide `N8N_API_URL` and `N8N_API_KEY` in your configuration.

#### Workflow Management
- **`n8n_create_workflow`** - Create new workflows with nodes and connections.
- **`n8n_get_workflow`** - Get complete workflow by ID.
- **`n8n_get_workflow_details`** - Get workflow with execution statistics.
- **`n8n_get_workflow_structure`** - Get simplified workflow structure.
- **`n8n_get_workflow_minimal`** - Get minimal workflow info (ID, name, active status).
- **`n8n_update_full_workflow`** - Update entire workflow (complete replacement).
- **`n8n_update_partial_workflow`** - Update workflow using diff operations.
- **`n8n_delete_workflow`** - Delete workflows permanently.
- **`n8n_list_workflows`** - List workflows with filtering and pagination.
- **`n8n_validate_workflow`** - Validate workflows already in n8n by ID.

#### Execution Management
- **`n8n_trigger_webhook_workflow`** - Trigger workflows via webhook URL.
- **`n8n_get_execution`** - Get execution details by ID.
- **`n8n_list_executions`** - List executions with status filtering.
- **`n8n_delete_execution`** - Delete execution records.

#### System Tools
- **`n8n_health_check`** - Check n8n API connectivity and features.
- **`n8n_diagnostic`** - Troubleshoot management tools visibility and configuration issues.
- **`n8n_list_available_tools`** - List all available management tools.

### Example Usage

```typescript
// Get essentials for quick configuration
get_node_essentials("nodes-base.httpRequest")

// Find nodes for a specific task
search_nodes({ query: "send email gmail" })

// Get pre-configured settings
get_node_for_task("send_email")

// Validate before deployment
validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config: { method: "POST", url: "..." },
  profile: "runtime" // or "minimal", "ai-friendly", "strict"
})

// Quick required field check
validate_node_minimal({
  nodeType: "nodes-base.slack",
  config: { resource: "message", operation: "send" }
})
```