n8n Workflow Automation Plugin

Build, validate, and deploy production-ready n8n workflows with AI assistance.

---

Overview

This plugin transforms Claude into an expert n8n workflow builder. It combines:

• MCP Integration - Direct connection to your n8n instance via n8n-mcp
• 7 Expert Skills - Domain knowledge for building flawless workflows
• 9 Specialized Agents - Multi-agent orchestration for complex workflows
• Edge Case Knowledge - Documented gotchas and solutions from real-world usage

What You Can Do

Capability	Example
Search & Discovery	"Find nodes for sending emails"
Build Workflows	"Create a webhook that posts to Slack"
Validate & Fix	"Why is my workflow failing?"
Deploy	"Activate my workflow"
Templates	"Show me CRM integration templates"

---

Quick Start

1. Install Dependencies

n8n-mcp server (required):

# Via npx (simplest)
npx n8n-mcp

# Or via Docker
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

2. Configure Environment

Add to your .env file:

N8N_API_URL=https://your-instance.app.n8n.cloud
N8N_API_KEY=your-api-key

3. Install Plugin

Claude Code:

claude plugins add knowledge-work-plugins/n8n

Manual:

git clone https://github.com/your-repo/n8n-plugin
cp -r n8n-plugin ~/.claude/plugins/

---

Commands

Explicit workflows triggered with slash commands:

Command	Description
/n8n:build	Interactive workflow builder with validation
/n8n:validate	Validate an existing workflow
/n8n:templates	Search workflow templates by use case
/n8n:debug	Debug workflow errors with AI assistance
/n8n:deploy	Deploy workflow with safety checks

Examples

/n8n:build "webhook that receives form data and saves to Google Sheets"

/n8n:validate workflow_id:abc123

/n8n:templates "CRM sync with Hubspot"

/n8n:debug "Error: Cannot read property 'email' of undefined"

---

Skills

Domain expertise that activates automatically:

Core Skills

Skill	Activates When
MCP Tools Expert	Searching nodes, using MCP tools
Expression Syntax	Writing {{ }} expressions
Workflow Patterns	Designing workflow architecture
Validation Expert	Interpreting and fixing errors
Node Configuration	Setting up node parameters

Code Skills

Skill	Activates When
Code JavaScript	Writing JS in Code nodes
Code Python	Writing Python in Code nodes

How Skills Compose

When you ask: "Build a webhook that transforms data and posts to Slack"

1. Workflow Patterns - Selects webhook processing pattern
2. MCP Tools Expert - Searches for Webhook, Set, Slack nodes
3. Node Configuration - Guides parameter setup
4. Expression Syntax - Helps with data mapping
5. Validation Expert - Validates the complete workflow

All skills work together seamlessly!

---

Multi-Agent System

For complex workflows, the plugin uses 9 specialized agents:

┌─────────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR (White)                      │
│                 Coordinates all agents                       │
└─────────────────────────────────────────────────────────────┘
                            │
       ┌────────────────────┼────────────────────┐
       ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  DISCOVERY  │      │  ARCHITECT  │      │   BUILDER   │
│   (Purple)  │      │   (Blue)    │      │   (Green)   │
│ Requirements│      │  Blueprint  │      │   Nodes     │
└─────────────┘      └─────────────┘      └─────────────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  VALIDATOR  │      │ EDGE CASE   │      │ INTEGRATION │
│  (Yellow)   │      │  HUNTER     │      │   TESTER    │
│ Validation  │      │  (Orange)   │      │    (Red)    │
└─────────────┘      └─────────────┘      └─────────────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            ▼
                   ┌─────────────┐
                   │  RECOVERY   │
                   │   (Brown)   │
                   │ Checkpoints │
                   └─────────────┘

Agent Responsibilities

Agent	Role
Orchestrator	Overall coordination, state management
Discovery	Gather requirements, ask clarifying questions
Architect	Design workflow blueprint
Builder	Construct nodes with MCP tools
Validator	Continuous validation during build
Edge Case Hunter	Identify potential issues
Integration Tester	End-to-end testing
Recovery	Checkpoint creation and rollback
Prompt Designer	AI prompt design for AI Agent nodes

---

MCP Tools Reference

Node Discovery

Tool	Purpose
search_nodes	Find nodes by keyword
get_node	Get complete node details (100KB+)
get_node_essentials	Get focused node data (5KB)
list_nodes	List all available nodes

Validation

Tool	Purpose
validate_node_minimal	Check required fields
validate_node_operation	Full operation validation
validate_workflow	Validate complete workflow

Workflow Management

Tool	Purpose
n8n_create_workflow	Create new workflow
n8n_get_workflow	Get workflow by ID
n8n_list_workflows	List all workflows
n8n_update_partial_workflow	Incremental updates (recommended)
n8n_update_full_workflow	Full workflow replacement
n8n_autofix_workflow	Auto-fix common issues
n8n_test_workflow	Test/trigger workflow
n8n_delete_workflow	Delete workflow

Templates

Tool	Purpose
search_templates	Find workflow templates
get_template	Get template details

---

Edge Cases & Gotchas

Critical: Webhook Data Structure

// CORRECT - Webhook data is nested under .body
$json.body.email
$json.body.name
$json.headers.authorization

// WRONG - Direct access fails
$json.email        // undefined!
$json.Authorization // undefined!

Expression Syntax

// CORRECT - Double braces in n8n expressions
{{ $json.body.email }}

// WRONG - Single braces or no braces
{ $json.body.email }  // syntax error
$json.body.email      // depends on context

Code Node Returns

// CORRECT - Array of objects with json property
return [{ json: { result: data } }];

// WRONG - Plain object or array
return { result: data };      // fails
return [{ result: data }];    // fails

See edge-cases/ for comprehensive documentation of all gotchas.

---

Configuration

Local Settings

Create .claude/settings.local.json:

{
  "n8n": {
    "defaultWebhookPath": "/webhook",
    "draftDirectory": "n8n-workflows-draft/",
    "validateBeforeDeploy": true,
    "autoBackup": true
  }
}

MCP Configuration

The .mcp.json connects to your n8n instance:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "N8N_API_URL": "${N8N_API_URL}",
        "N8N_API_KEY": "${N8N_API_KEY}"
      }
    }
  }
}

---

Safety Guidelines

Production Safety

NEVER edit production workflows directly with AI!

Always:

1. Copy the workflow first
2. Test in development
3. Export a backup
4. Validate changes
5. Deploy with review

Recommended Workflow

1. Build in draft → n8n-workflows-draft/
2. Validate → n8n_validate_workflow
3. Review JSON → User confirms
4. Deploy → n8n_create_workflow or n8n_update_*
5. Test → n8n_test_workflow

---

Statistics

Metric	Value
Nodes Supported	1,084 (537 core + 547 community)
Templates Available	2,709
Code Patterns	10 production-tested
Edge Cases Documented	50+
Multi-Agent System	9 specialized agents

---

Credits

Core Technology

This plugin is built on top of the excellent work by Romuald Członkowski:

• n8n-mcp - MCP server for n8n integration
• n8n-skills - Claude Code skills for n8n

Author: Romuald Członkowski Website: www.aiadvisors.pl/en GitHub: @czlonkowski

Related Projects

• n8n - Workflow automation platform
• Model Context Protocol - MCP specification
• Claude Code - AI-powered coding assistant

---

License

MIT License - see LICENSE file for details.

---

Contributing

Contributions welcome! See DEVELOPMENT.md for guidelines.

Development Approach

1. Evaluation-First - Write test scenarios before implementation
2. MCP-Informed - Test tools, document real responses
3. Iterative - Test against evaluations until 100% pass
4. Concise - Keep documentation focused
5. Real Examples - All examples from real templates/tools

---

Ready to automate with n8n? Get started now!