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:

Node Discovery → SEARCH_GUIDE.md
Configuration Validation → VALIDATION_GUIDE.md
Workflow Management → WORKFLOW_GUIDE.md
Template Library - Search and access 2,653 real workflows
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:

javascript

// 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

javascript

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

Tools that use this:

search_nodes (returns this format)
get_node_essentials
get_node_info
validate_node_minimal
validate_node_operation
get_property_dependencies

Format 2: Workflow Tools

javascript

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

Tools that use this:

n8n_create_workflow
n8n_update_partial_workflow
list_node_templates

Conversion

javascript

// 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

javascript

❌ 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 get_node_info Instead of get_node_essentials

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

javascript

❌ 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 get_node_info:

Debugging complex configuration issues
Need complete property schema
Exploring advanced features

Better alternatives:

get_node_essentials - for operations list
get_node_documentation - for readable docs
search_node_properties - 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)

javascript

❌ 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

javascript

// 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):

javascript

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

New way (smart parameters):

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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 SEARCH_GUIDE.md for:

search_nodes (99.9% success)
get_node_essentials vs get_node_info
list_nodes by category
search_node_properties for specific fields

Validation Tools

See VALIDATION_GUIDE.md for:

Validation profiles explained
validate_node_minimal vs validate_node_operation
validate_workflow complete structure
Auto-sanitization system
Handling validation errors

Workflow Management

See WORKFLOW_GUIDE.md for:

n8n_create_workflow
n8n_update_partial_workflow (15 operation types!)
Smart parameters (branch, case)
AI connection types (8 types)
cleanStaleConnections recovery

Template Usage

Search Templates

javascript

// 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

javascript

// List all tools
tools_documentation()

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

Health Check

javascript

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

Database Statistics

javascript

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

Tool Availability

Always Available (no n8n API needed):

search_nodes, list_nodes, get_node_essentials ✅
validate_node_minimal, validate_node_operation ✅
validate_workflow, get_property_dependencies ✅
search_templates, get_template, list_tasks ✅
tools_documentation, get_database_statistics ✅

Requires n8n API (N8N_API_URL + N8N_API_KEY):

n8n_create_workflow ⚠️
n8n_update_partial_workflow ⚠️
n8n_validate_workflow (by ID) ⚠️
n8n_list_workflows, n8n_get_workflow ⚠️
n8n_trigger_webhook_workflow ⚠️

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

Performance Characteristics

Tool	Response Time	Payload Size	Reliability
search_nodes	<20ms	Small	99.9%
list_nodes	<20ms	Small	99.6%
get_node_essentials	<10ms	~5KB	91.7%
get_node_info	Varies	100KB+	80% ⚠️
validate_node_minimal	<100ms	Small	97.4%
validate_node_operation	<100ms	Medium	Varies
validate_workflow	100-500ms	Medium	95.5%
n8n_create_workflow	100-500ms	Medium	96.8%
n8n_update_partial_workflow	50-200ms	Small	99.0%

Best Practices

✅ Do

Use get_node_essentials over get_node_info (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 get_node_info 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:

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

Common Workflow:

search_nodes → find node
get_node_essentials → understand config
validate_node_operation → check config
n8n_create_workflow → build
n8n_validate_workflow → verify
n8n_update_partial_workflow → iterate

For details, see:

SEARCH_GUIDE.md - Node discovery
VALIDATION_GUIDE.md - Configuration validation
WORKFLOW_GUIDE.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

n8n-mcp-tools-expert

NPX Install

SKILL.md Content

n8n MCP Tools Expert

Tool Categories

Quick Reference

Most Used Tools (by success rate)

Tool Selection Guide

Finding the Right Node

Validating Configuration

Managing Workflows

Critical: nodeType Formats

Format 1: Search/Validate Tools

Format 2: Workflow Tools

Conversion

Common Mistakes

❌ Mistake 1: Wrong nodeType Format

❌ Mistake 2: Using get_node_info Instead of get_node_essentials

❌ Mistake 3: Not Using Validation Profiles

❌ Mistake 4: Ignoring Auto-Sanitization

❌ Mistake 5: Not Using Smart Parameters

Tool Usage Patterns

Pattern 1: Node Discovery (Most Common)

Pattern 2: Validation Loop

Pattern 3: Workflow Editing

Detailed Guides

Node Discovery Tools

Validation Tools

Workflow Management

Template Usage

Search Templates

Template Metadata

Self-Help Tools

Get Tool Documentation

Health Check

Database Statistics

Tool Availability

Performance Characteristics

Best Practices

✅ Do

❌ Don't

Summary