N8n Mcp Tools Expert

n8n MCP Tools Expert

Master guide for using n8n-mcp MCP server tools to build workflows.

---

Tool Categories

n8n-mcp provides 40+ tools organized into categories:

1. Node Discovery → [SEARCHGUIDE.md](SEARCHGUIDE.md)
2. Configuration Validation → [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md)
3. Workflow Management → [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md)
4. Template Library - Search and access 2,653 real workflows
5. Documentation - Get tool and node documentation

---

Quick Reference

Most Used Tools (by success rate)

| Tool | Use When | Success Rate | Speed | |------|----------|--------------|-------| | search_nodes | Finding nodes by keyword | 99.9% | <20ms | | get_node_essentials | Understanding node operations | 91.7% | <10ms | | validate_node_operation | Checking configurations | Varies | <100ms | | n8n_create_workflow | Creating workflows | 96.8% | 100-500ms | | n8n_update_partial_workflow | Editing workflows (MOST USED!) | 99.0% | 50-200ms | | validate_workflow | Checking complete workflow | 95.5% | 100-500ms |

---

Tool Selection Guide

Finding the Right Node

Workflow:

1. search_nodes({query: "keyword"})
2. get_node_essentials({nodeType: "nodes-base.name"})
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"})

Example:

// Step 1: Search
search_nodes({query: "slack"})
// Returns: nodes-base.slack

// Step 2: Get details (18s avg between steps)
get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples

Common pattern: search → essentials (18s average)

Validating Configuration

Workflow:

1. validate_node_minimal({nodeType, config: {}}) - Check required fields
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation
3. [Repeat] Fix errors, validate again

Common pattern: validate → fix → validate (23s thinking, 58s fixing per cycle)

Managing Workflows

Workflow:

1. n8n_create_workflow({name, nodes, connections})
2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]})
4. n8n_validate_workflow({id}) again

Common pattern: iterative updates (56s average between edits)

---

Critical: nodeType Formats

Two different formats for different tools!

Format 1: Search/Validate Tools

// Use SHORT prefix
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

Tools that use this:

• search_nodes (returns this format)
• getnodeessentials
• getnodeinfo
• validatenodeminimal
• validatenodeoperation
• getpropertydependencies

Format 2: Workflow Tools

// Use FULL prefix
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

Tools that use this:

• n8ncreateworkflow
• n8nupdatepartial_workflow
• listnodetemplates

Conversion

// search_nodes returns BOTH formats
{
  "nodeType": "nodes-base.slack",          // For search/validate tools
  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
}

---

Common Mistakes

❌ Mistake 1: Wrong nodeType Format

Problem: "Node not found" error

❌ get_node_essentials({nodeType: "slack"})  // Missing prefix
❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix

✅ get_node_essentials({nodeType: "nodes-base.slack"})  // Correct!

❌ Mistake 2: Using getnodeinfo Instead of getnodeessentials

Problem: 20% failure rate, slow response, huge payload

❌ get_node_info({nodeType: "nodes-base.slack"})
// Returns: 100KB+ data, 20% chance of failure

✅ get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: 5KB focused data, 91.7% success, <10ms

When to use getnodeinfo:

• Debugging complex configuration issues
• Need complete property schema
• Exploring advanced features

Better alternatives:

1. getnodeessentials - for operations list
2. getnodedocumentation - for readable docs
3. searchnodeproperties - for specific property

❌ Mistake 3: Not Using Validation Profiles

Problem: Too many false positives OR missing real errors

Profiles:

• minimal - Only required fields (fast, permissive)
• runtime - Values + types (recommended for pre-deployment)
• ai-friendly - Reduce false positives (for AI configuration)
• strict - Maximum validation (for production)

❌ validate_node_operation({nodeType, config})  // Uses default

✅ validate_node_operation({nodeType, config, profile: "runtime"})  // Explicit

❌ Mistake 4: Ignoring Auto-Sanitization

What happens: ALL nodes sanitized on ANY workflow update

Auto-fixes:

• Binary operators (equals, contains) → removes singleValue
• Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
• IF/Switch nodes → adds missing metadata

Cannot fix:

• Broken connections
• Branch count mismatches
• Paradoxical corrupt states

// After ANY update, auto-sanitization runs on ALL nodes
n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures

❌ Mistake 5: Not Using Smart Parameters

Problem: Complex sourceIndex calculations for multi-output nodes

Old way (manual):

// IF node connection
{
  type: "addConnection",
  source: "IF",
  target: "Handler",
  sourceIndex: 0  // Which output? Hard to remember!
}

New way (smart parameters):

// IF node - semantic branch names
{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Clear and readable!
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"
}

// Switch node - semantic case numbers
{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

---

Tool Usage Patterns

Pattern 1: Node Discovery (Most Common)

Common workflow: 18s average between steps

// Step 1: Search (fast!)
const results = await search_nodes({
  query: "slack",
  mode: "OR",  // Default: any word matches
  limit: 20
});
// → Returns: nodes-base.slack, nodes-base.slackTrigger

// Step 2: Get details (~18s later, user reviewing results)
const details = await get_node_essentials({
  nodeType: "nodes-base.slack",
  includeExamples: true  // Get real template configs
});
// → Returns: operations, properties, metadata

Pattern 2: Validation Loop

Typical cycle: 23s thinking, 58s fixing

// Step 1: Validate
const result = await validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create"
  },
  profile: "runtime"
});

// Step 2: Check errors (~23s thinking)
if (!result.valid) {
  console.log(result.errors);  // "Missing required field: name"
}

// Step 3: Fix config (~58s fixing)
config.name = "general";

// Step 4: Validate again
await validate_node_operation({...});  // Repeat until clean

Pattern 3: Workflow Editing

Most used update tool: 99.0% success rate, 56s average between edits

// Iterative workflow building (NOT one-shot!)
// Edit 1
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addNode", node: {...}}]
});

// ~56s later...

// Edit 2
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addConnection", source: "...", target: "..."}]
});

// ~56s later...

// Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"});

---

Detailed Guides

Node Discovery Tools

See [SEARCHGUIDE.md](SEARCHGUIDE.md) for:

• search_nodes (99.9% success)
• getnodeessentials vs getnodeinfo
• list_nodes by category
• searchnodeproperties for specific fields

Validation Tools

See [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md) for:

• Validation profiles explained
• validatenodeminimal vs validatenodeoperation
• validate_workflow complete structure
• Auto-sanitization system
• Handling validation errors

Workflow Management

See [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) for:

• n8ncreateworkflow
• n8nupdatepartial_workflow (15 operation types!)
• Smart parameters (branch, case)
• AI connection types (8 types)
• cleanStaleConnections recovery

---

Template Usage

Search Templates

// Search by keyword
search_templates({
  query: "webhook slack",
  limit: 20
});
// → Returns: 1,085 templates with metadata

// Get template details
get_template({
  templateId: 2947,  // Weather to Slack
  mode: "structure"  // or "full" for complete JSON
});

Template Metadata

Templates include:

• Complexity (simple, medium, complex)
• Setup time estimate
• Required services
• Categories and use cases
• View counts (popularity)

---

Self-Help Tools

Get Tool Documentation

// List all tools
tools_documentation()

// Specific tool details
tools_documentation({
  topic: "search_nodes",
  depth: "full"
})

Health Check

// Verify MCP server connectivity
n8n_health_check()
// → Returns: status, features, API availability, version

Database Statistics

get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates

---

Tool Availability

Always Available (no n8n API needed):

• searchnodes, listnodes, getnodeessentials ✅
• validatenodeminimal, validatenodeoperation ✅
• validateworkflow, getproperty_dependencies ✅
• searchtemplates, gettemplate, list_tasks ✅
• toolsdocumentation, getdatabase_statistics ✅

Requires n8n API (N8NAPIURL + N8NAPIKEY):

• n8ncreateworkflow ⚠️
• n8nupdatepartial_workflow ⚠️
• n8nvalidateworkflow (by ID) ⚠️
• n8nlistworkflows, n8ngetworkflow ⚠️
• n8ntriggerwebhook_workflow ⚠️

If API tools unavailable, use templates and validation-only workflows.

---

Performance Characteristics

| Tool | Response Time | Payload Size | Reliability | |------|---------------|--------------|-------------| | searchnodes | <20ms | Small | 99.9% | | listnodes | <20ms | Small | 99.6% | | getnodeessentials | <10ms | ~5KB | 91.7% | | getnodeinfo | Varies | 100KB+ | 80% ⚠️ | | validatenodeminimal | <100ms | Small | 97.4% | | validatenodeoperation | <100ms | Medium | Varies | | validateworkflow | 100-500ms | Medium | 95.5% | | n8ncreateworkflow | 100-500ms | Medium | 96.8% | | n8nupdatepartialworkflow | 50-200ms | Small | 99.0% |

---

Best Practices

✅ Do

• Use getnodeessentials over getnodeinfo (91.7% vs 80%)
• Specify validation profile explicitly
• Use smart parameters (branch, case) for clarity
• Follow search → essentials → validate workflow
• Iterate workflows (avg 56s between edits)
• Validate after every significant change
• Use includeExamples: true for real configs

❌ Don't

• Use getnodeinfo unless necessary (20% failure rate!)
• Forget nodeType prefix (nodes-base.*)
• Skip validation profiles (use "runtime")
• Try to build workflows in one shot (iterate!)
• Ignore auto-sanitization behavior
• Use full prefix (n8n-nodes-base.*) with search tools

---

Summary

Most Important:

1. Use getnodeessentials, not getnodeinfo (5KB vs 100KB, 91.7% vs 80%)
2. nodeType formats differ: nodes-base.* (search) vs n8n-nodes-base.* (workflows)
3. Specify validation profiles (runtime recommended)
4. Use smart parameters (branch="true", case=0)
5. Auto-sanitization runs on ALL nodes during updates
6. Workflows are built iteratively (56s avg between edits)

Common Workflow:

1. search_nodes → find node
2. getnodeessentials → understand config
3. validatenodeoperation → check config
4. n8ncreateworkflow → build
5. n8nvalidateworkflow → verify
6. n8nupdatepartial_workflow → iterate

For details, see:

• [SEARCHGUIDE.md](SEARCHGUIDE.md) - Node discovery
• [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md) - Configuration validation
• [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) - Workflow management

---

Related Skills:

• n8n Expression Syntax - Write expressions in workflow fields
• n8n Workflow Patterns - Architectural patterns from templates
• n8n Validation Expert - Interpret validation errors
• n8n Node Configuration - Operation-specific requirements

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: echoleesong
• Source: echoleesong/claude-skills-plugin
• License: MIT

Install and usage instructions live in the source repository linked above.