viriansemail-sys/claude-code-helper/n8n-mcp-tools-expert

Name: n8n-mcp-tools-expert
Author: viriansemail-sys

Claude Code and agent skill by viriansemail-sys/claude-code-helper

Trust tier 3

community

Source check pending

Checking that the SKILL.md file is still in the repository.

Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns.

Install

npx vskill@latest install viriansemail-sys/claude-code-helper/n8n-mcp-tools-expert

SKILL.md

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)

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/n8n-mcp-tools-expert/SKILL.md

Popularity

7-day trend score: 0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/viriansemail-sys/claude-code-helper/n8n-mcp-tools-expert/badge)](https://verified-skill.com/skills/viriansemail-sys/claude-code-helper/n8n-mcp-tools-expert)

Something wrong with this skill or its page? Tell us.