Claude Code: Step 1 – n8n MCP Server

By /

Overview

The n8n-MCP server (by czlonkowski) connects Claude Code to your n8n instance, allowing you to build, modify, validate, and deploy n8n workflows directly from the CLI.

GitHub: https://github.com/czlonkowski/n8n-mcp

Prerequisites

  • A running n8n instance with API access enabled
  • Node.js / npm installed (for npx)
  • Claude Code installed

Step 1: Generate n8n API Key

  1. Open your n8n instance (e.g. https://n8n.adventuretube.net)
  2. Go to Settings > API
  3. Click Create API Key
  4. Copy the generated JWT token — you’ll need it in Step 2

Note: The API key is a JWT token that expires. You’ll need to regenerate it when it expires.

Step 2: Create .mcp.json in Project Root

In your project directory, create a .mcp.json file:

{
  "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-n8n-api-key-here"
      }
    }
  }
}

Key environment variables:

  • MCP_MODE: Must be stdio for Claude Code integration
  • LOG_LEVEL: Set to error to suppress noisy logs
  • DISABLE_CONSOLE_OUTPUT: Prevents stdout pollution that breaks MCP protocol
  • N8N_API_URL: Your n8n instance URL (no trailing slash)
  • N8N_API_KEY: The JWT token from Step 1

Step 3: Create .claude/settings.local.json for Tool Permissions

Create .claude/settings.local.json in your project directory to auto-approve all n8n-MCP tools:

{
  "permissions": {
    "allow": [
      "mcp__n8n-mcp__tools_documentation",
      "mcp__n8n-mcp__search_nodes",
      "mcp__n8n-mcp__get_node",
      "mcp__n8n-mcp__validate_node",
      "mcp__n8n-mcp__validate_workflow",
      "mcp__n8n-mcp__search_templates",
      "mcp__n8n-mcp__get_template",
      "mcp__n8n-mcp__n8n_health_check",
      "mcp__n8n-mcp__n8n_create_workflow",
      "mcp__n8n-mcp__n8n_get_workflow",
      "mcp__n8n-mcp__n8n_update_full_workflow",
      "mcp__n8n-mcp__n8n_update_partial_workflow",
      "mcp__n8n-mcp__n8n_delete_workflow",
      "mcp__n8n-mcp__n8n_list_workflows",
      "mcp__n8n-mcp__n8n_validate_workflow",
      "mcp__n8n-mcp__n8n_autofix_workflow",
      "mcp__n8n-mcp__n8n_workflow_versions",
      "mcp__n8n-mcp__n8n_deploy_template",
      "mcp__n8n-mcp__n8n_test_workflow",
      "mcp__n8n-mcp__n8n_executions"
    ]
  }
}

Step 4: Create CLAUDE.md — The Critical Piece

This is the most important file. The CLAUDE.md file tells Claude Code HOW to use the MCP tools effectively. Without it, Claude will have the tools available but won’t know the best practices, validation strategy, or workflow patterns.

Why CLAUDE.md matters:

  • Defines the workflow process: templates first, then node discovery, validation, building
  • Sets parallel execution rules: independent operations run simultaneously
  • Establishes validation strategy: minimal > full > workflow-level validation
  • Documents critical warnings: never trust defaults, explicit parameter configuration
  • Provides correct syntax for operations like addConnection (4 separate string params)
  • Lists popular node types with correct prefixes
  • Defines response format: silent execution, no commentary between tools

Without CLAUDE.md: Claude has the tools but uses them inefficiently — sequential calls, no validation, missing parameters, verbose output.

With CLAUDE.md: Claude operates like an n8n expert — parallel tool calls, templates-first approach, multi-level validation, silent execution.

Shared File Approach (Recommended)

The n8n instructions are stored as a shared file so any project can import them:

Shared file location:

~/.claude/shared/n8n-mcp-instructions.md

In your project’s .claude/CLAUDE.md, add this line at the end:

@import /Users/chrislee/.claude/shared/n8n-mcp-instructions.md

Replicating to Another Project

To set up n8n-MCP in a new project:

  1. Copy .mcp.json to new project root — update N8N_API_URL and N8N_API_KEY if connecting to a different n8n instance
  2. Copy .claude/settings.local.json — can be reused as-is
  3. Add @import to the end of your existing .claude/CLAUDE.md
  4. Run claude in the new project directory

Available Tools (20 total)

Category Tools
Discovery tools_documentation, search_nodes, get_node, search_templates, get_template
Validation validate_node, validate_workflow, n8n_validate_workflow
CRUD n8n_create_workflow, n8n_get_workflow, n8n_update_full_workflow, n8n_update_partial_workflow, n8n_delete_workflow, n8n_list_workflows
Operations n8n_health_check, n8n_autofix_workflow, n8n_workflow_versions, n8n_deploy_template, n8n_test_workflow, n8n_executions

Core Principles for Using n8n MCP

1. Silent Execution

Execute tools without commentary. Only respond AFTER all tools complete.

2. Parallel Execution

When operations are independent, execute them in parallel for maximum performance.

3. Templates First

ALWAYS check templates before building from scratch (2,709 available).

4. Multi-Level Validation

Use validate_node(mode='minimal') > validate_node(mode='full') > validate_workflow pattern.

5. Never Trust Defaults

Default parameter values are the #1 source of runtime failures. ALWAYS explicitly configure ALL parameters that control node behavior.

Workflow Process

  1. Start: Call tools_documentation() for best practices
  2. Template Discovery Phase – Search templates using metadata, task, keyword, or node types
  3. Node Discovery – If no suitable template, search for nodes with search_nodes
  4. Configuration Phase – Use get_node with different detail levels
  5. Validation Phase – Validate nodes with minimal then full mode
  6. Building Phase – Build from validated configurations with explicit parameters
  7. Workflow Validation – Complete validation before deployment
  8. Deployment – Create, validate, and test workflow on n8n instance

Critical Warnings

Never Trust Defaults

Default values cause runtime failures. Always explicitly set all parameters:

// FAILS at runtime
{"resource": "message", "operation": "post", "text": "Hello"}

// WORKS - all parameters explicit
{"resource": "message", "operation": "post", "select": "channel", "channelId": "C123", "text": "Hello"}

addConnection Syntax

The addConnection operation requires four separate string parameters:

{
  "type": "addConnection",
  "source": "node-id-string",
  "target": "target-node-id-string",
  "sourcePort": "main",
  "targetPort": "main"
}

IF Node Multi-Output Routing

IF nodes have two outputs (TRUE and FALSE). Use the branch parameter:

// Route to TRUE branch:
{"type": "addConnection", "source": "if-node-id", "target": "success-handler-id", "sourcePort": "main", "targetPort": "main", "branch": "true"}

// Route to FALSE branch:
{"type": "addConnection", "source": "if-node-id", "target": "failure-handler-id", "sourcePort": "main", "targetPort": "main", "branch": "false"}

Most Popular n8n Nodes

# Node Description
1 n8n-nodes-base.code JavaScript/Python scripting
2 n8n-nodes-base.httpRequest HTTP API calls
3 n8n-nodes-base.webhook Event-driven triggers
4 n8n-nodes-base.set Data transformation
5 n8n-nodes-base.if Conditional routing
6 n8n-nodes-base.manualTrigger Manual workflow execution
7 n8n-nodes-base.scheduleTrigger Time-based triggers
8 @n8n/n8n-nodes-langchain.agent AI agents
9 n8n-nodes-base.googleSheets Spreadsheet integration
10 n8n-nodes-base.telegram Telegram bot integration

Note: LangChain nodes use the @n8n/n8n-nodes-langchain. prefix, core nodes use n8n-nodes-base.

Troubleshooting

  • MCP server not connecting: Check N8N_API_URL has no trailing slash and API key is valid
  • Tools not auto-approved: Verify .claude/settings.local.json is in the correct directory
  • Claude not following best practices: Check .claude/CLAUDE.md exists and is properly formatted
  • API key expired: Regenerate in n8n Settings > API

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top