n8n MCP Tools Expert

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

Tool Categories

n8n-mcp provides tools organized into categories:

Node Discovery → SEARCH_GUIDE.md
Configuration Validation → VALIDATION_GUIDE.md
Workflow Management → WORKFLOW_GUIDE.md
Template Library - Search and deploy 2,700+ real workflows
Documentation & Guides - Tool docs, AI agent guide, Code node guides

Quick Reference

Most Used Tools (by success rate)

Tool	Use When	Speed
`search_nodes`	Finding nodes by keyword	<20ms
`get_node`	Understanding node operations (detail="standard")	<10ms
`validate_node`	Checking configurations (mode="full")	<100ms
`n8n_create_workflow`	Creating workflows	100-500ms
`n8n_update_partial_workflow`	Editing workflows (MOST USED!)	50-200ms
`validate_workflow`	Checking complete workflow	100-500ms
`n8n_deploy_template`	Deploy template to n8n instance	200-500ms

Tool Selection Guide

Finding the Right Node

Workflow:

1. search_nodes({query: "keyword"})
2. get_node({nodeType: "nodes-base.name"})
3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})

Example:

javascript

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

// Step 2: Get details
get_node({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples (standard detail)

// Step 3: Get readable documentation
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// Returns: markdown documentation

Common pattern: search → get_node (18s average)

Validating Configuration

Workflow:

1. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
2. validate_node({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
5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})

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
validate_node
validate_workflow

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

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

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

// CORRECT
get_node({nodeType: "nodes-base.slack"})

Mistake 2: Using detail="full" by Default

Problem: Huge payload, slower response, token waste

javascript

// WRONG - Returns 3-8K tokens, use sparingly
get_node({nodeType: "nodes-base.slack", detail: "full"})

// CORRECT - Returns 1-2K tokens, covers 95% of use cases
get_node({nodeType: "nodes-base.slack"})  // detail="standard" is default
get_node({nodeType: "nodes-base.slack", detail: "standard"})

When to use detail="full":

Debugging complex configuration issues
Need complete property schema with all nested options
Exploring advanced features

Better alternatives:

```
get_node({detail: "standard"})
```
- for operations list (default)
```
get_node({mode: "docs"})
```
- for readable documentation

get_node({mode: "search_properties", propertyQuery: "auth"})

- 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

// WRONG - Uses default profile
validate_node({nodeType, config})

// CORRECT - Explicit profile
validate_node({nodeType, config, profile: "runtime"})

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
}

Mistake 6: Not Using intent Parameter

Problem: Less helpful tool responses

javascript

// WRONG - No context for response
n8n_update_partial_workflow({
  id: "abc",
  operations: [{type: "addNode", node: {...}}]
})

// CORRECT - Better AI responses
n8n_update_partial_workflow({
  id: "abc",
  intent: "Add error handling for API failures",
  operations: [{type: "addNode", node: {...}}]
})

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({
  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({
  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({...});  // 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",
  intent: "Add webhook trigger",
  operations: [{type: "addNode", node: {...}}]
});

// ~56s later...

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

// ~56s later...

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

// Ready? Activate!
await n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Activate workflow for production",
  operations: [{type: "activateWorkflow"}]
});

Detailed Guides

Node Discovery Tools

See SEARCH_GUIDE.md for:

search_nodes
get_node with detail levels (minimal, standard, full)
get_node modes (info, docs, search_properties, versions)

Validation Tools

See VALIDATION_GUIDE.md for:

Validation profiles explained
validate_node with modes (minimal, full)
validate_workflow complete structure
Auto-sanitization system
Handling validation errors

Workflow Management

See WORKFLOW_GUIDE.md for:

n8n_create_workflow
n8n_update_partial_workflow (17 operation types!)
Smart parameters (branch, case)
AI connection types (8 types)
Workflow activation (activateWorkflow/deactivateWorkflow)
n8n_deploy_template
n8n_workflow_versions

Template Usage

Search Templates

javascript

// Search by keyword (default mode)
search_templates({
  query: "webhook slack",
  limit: 20
});

// Search by node types
search_templates({
  searchMode: "by_nodes",
  nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]
});

// Search by task type
search_templates({
  searchMode: "by_task",
  task: "webhook_processing"
});

// Search by metadata (complexity, setup time)
search_templates({
  searchMode: "by_metadata",
  complexity: "simple",
  maxSetupMinutes: 15
});

Get Template Details

javascript

get_template({
  templateId: 2947,
  mode: "structure"  // nodes+connections only
});

get_template({
  templateId: 2947,
  mode: "full"  // complete workflow JSON
});

Deploy Template Directly

javascript

// Deploy template to your n8n instance
n8n_deploy_template({
  templateId: 2947,
  name: "My Weather to Slack",  // Custom name (optional)
  autoFix: true,  // Auto-fix common issues (default)
  autoUpgradeVersions: true  // Upgrade node versions (default)
});
// Returns: workflow ID, required credentials, fixes applied

Self-Help Tools

Get Tool Documentation

javascript

// Overview of all tools
tools_documentation()

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

// Code node guides
tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
tools_documentation({topic: "python_code_node_guide", depth: "full"})

AI Agent Guide

javascript

// Comprehensive AI workflow guide
ai_agents_guide()
// Returns: Architecture, connections, tools, validation, best practices

Health Check

javascript

// Quick health check
n8n_health_check()

// Detailed diagnostics
n8n_health_check({mode: "diagnostic"})
// → Returns: status, env vars, tool status, API connectivity

Tool Availability

Always Available (no n8n API needed):

search_nodes, get_node
validate_node, validate_workflow
search_templates, get_template
tools_documentation, ai_agents_guide

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_test_workflow
n8n_executions
n8n_deploy_template
n8n_workflow_versions
n8n_autofix_workflow

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

Unified Tool Reference

get_node (Unified Node Information)

Detail Levels (mode="info", default):

```
minimal
```
(~200 tokens) - Basic metadata only
```
standard
```
(~1-2K tokens) - Essential properties + operations (RECOMMENDED)
```
full
```
(~3-8K tokens) - Complete schema (use sparingly)

Operation Modes:

```
info
```
(default) - Node schema with detail level
```
docs
```
- Readable markdown documentation
```
search_properties
```
- Find specific properties (use with propertyQuery)
```
versions
```
- List all versions with breaking changes
```
compare
```
- Compare two versions
```
breaking
```
- Show only breaking changes
```
migrations
```
- Show auto-migratable changes

javascript

// Standard (recommended)
get_node({nodeType: "nodes-base.httpRequest"})

// Get documentation
get_node({nodeType: "nodes-base.webhook", mode: "docs"})

// Search for properties
get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})

// Check versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})

validate_node (Unified Validation)

Modes:

```
full
```
(default) - Comprehensive validation with errors/warnings/suggestions
```
minimal
```
- Quick required fields check only

Profiles (for mode="full"):

```
minimal
```
- Very lenient
```
runtime
```
- Standard (default, recommended)
```
ai-friendly
```
- Balanced for AI workflows
```
strict
```
- Most thorough (production)

javascript

// Full validation with runtime profile
validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})

// Quick required fields check
validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})

Performance Characteristics

Tool	Response Time	Payload Size
search_nodes	<20ms	Small
get_node (standard)	<10ms	~1-2KB
get_node (full)	<100ms	3-8KB
validate_node (minimal)	<50ms	Small
validate_node (full)	<100ms	Medium
validate_workflow	100-500ms	Medium
n8n_create_workflow	100-500ms	Medium
n8n_update_partial_workflow	50-200ms	Small
n8n_deploy_template	200-500ms	Medium

Best Practices

Do

Use
```
get_node({detail: "standard"})
```
for most use cases
Specify validation profile explicitly (
```
profile: "runtime"
```
)
Use smart parameters (
```
branch
```
,
```
case
```
) for clarity
Include
```
intent
```
parameter in workflow updates
Follow search → get_node → validate workflow
Iterate workflows (avg 56s between edits)
Validate after every significant change
Use
```
includeExamples: true
```
for real configs
Use
```
n8n_deploy_template
```
for quick starts

Don't

Use
```
detail: "full"
```
unless necessary (wastes tokens)
Forget nodeType prefix (
```
nodes-base.*
```
)
Skip validation profiles
Try to build workflows in one shot (iterate!)
Ignore auto-sanitization behavior
Use full prefix (
```
n8n-nodes-base.*
```
) with search/validate tools
Forget to activate workflows after building

Summary

Most Important:

Use get_node with
```
detail: "standard"
```
(default) - covers 95% of use cases
nodeType formats differ:
```
nodes-base.*
```
(search/validate) vs
```
n8n-nodes-base.*
```
(workflows)
Specify validation profiles (
```
runtime
```
recommended)
Use smart parameters (
```
branch="true"
```
,
```
case=0
```
)
Include intent parameter in workflow updates
Auto-sanitization runs on ALL nodes during updates
Workflows can be activated via API (
```
activateWorkflow
```
operation)
Workflows are built iteratively (56s avg between edits)

Common Workflow:

search_nodes → find node
get_node → understand config
validate_node → check config
n8n_create_workflow → build
n8n_validate_workflow → verify
n8n_update_partial_workflow → iterate
activateWorkflow → go live!

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 Code JavaScript - Write JavaScript in Code nodes
n8n Code Python - Write Python in Code nodes

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 detail="full" by Default

Mistake 3: Not Using Validation Profiles

Mistake 4: Ignoring Auto-Sanitization

Mistake 5: Not Using Smart Parameters

Mistake 6: Not Using intent Parameter

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

Get Template Details

Deploy Template Directly

Self-Help Tools

Get Tool Documentation

AI Agent Guide

Health Check

Tool Availability

Unified Tool Reference

get_node (Unified Node Information)

validate_node (Unified Validation)

Performance Characteristics

Best Practices

Do

Don't

Summary