n8n-mcp-tools-expert

name	n8n-mcp-tools-expert
description	Navigate the n8n-mcp server's 40+ tools for node discovery, configuration validation, template access, and workflow management. Covers tool selection strategy, parameter formatting, and integration patterns. Consult when building workflows programmatically via MCP.

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 → SEARCH_GUIDE.md
2. Configuration Validation → VALIDATION_GUIDE.md
3. Workflow Management → WORKFLOW_GUIDE.md
4. Template Library - Search and access thousands of real workflows
5. Documentation - Get tool and node documentation

---

Quick Reference

Most Used Tools

Tool	Use When	Reliability	Speed
search_nodes	Finding nodes by keyword	Very high	<20ms
get_node_essentials	Understanding node operations	High	<10ms
validate_node_operation	Checking configurations	Varies	<100ms
n8n_create_workflow	Creating workflows	High	100-500ms
n8n_update_partial_workflow	Editing workflows (MOST USED!)	Very high	50-200ms
validate_workflow	Checking complete workflow	High	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
get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples

Common pattern: search → essentials

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

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

---

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)
• get_node_essentials
• get_node_info
• validate_node_minimal
• validate_node_operation
• get_property_dependencies

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:

• n8n_create_workflow
• n8n_update_partial_workflow
• list_node_templates

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

Problem: frequent failures, slow response, huge payload

❌ get_node_info({nodeType: "nodes-base.slack"})
// Returns: 100KB+ data, prone to failure

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

When to use get_node_info:

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

Better alternatives:

1. get_node_essentials - for operations list
2. get_node_documentation - for readable docs
3. 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)

❌ 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: search, then get details

// 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 (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: check errors, then fix

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

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

// Step 3: Fix config
config.name = "general";

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

Pattern 3: Workflow Editing

Most used update tool: highly reliable, used iteratively

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

// later...

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

// later...

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

---

Detailed Guides

Node Discovery Tools

See SEARCH_GUIDE.md for:

• search_nodes (highly reliable)
• 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

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

• 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	Very high
list_nodes	<20ms	Small	Very high
get_node_essentials	<10ms	~5KB	High
get_node_info	Varies	100KB+	Low ⚠️
validate_node_minimal	<100ms	Small	High
validate_node_operation	<100ms	Medium	Varies
validate_workflow	100-500ms	Medium	High
n8n_create_workflow	100-500ms	Medium	High
n8n_update_partial_workflow	50-200ms	Small	Very high

---

Best Practices

✅ Do

• Use get_node_essentials over get_node_info (far more reliable)
• Specify validation profile explicitly
• Use smart parameters (branch, case) for clarity
• Follow search → essentials → validate workflow
• Iterate workflows (make incremental edits)
• Validate after every significant change
• Use includeExamples: true for real configs

❌ Don't

• Use get_node_info unless necessary (unreliable!)
• 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 get_node_essentials, not get_node_info (5KB vs 100KB, far more reliable)
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 (incremental edits)

Common Workflow:

1. search_nodes → find node
2. get_node_essentials → understand config
3. validate_node_operation → check config
4. n8n_create_workflow → build
5. n8n_validate_workflow → verify
6. 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