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.
npxskills add davila7/claude-code-templates--skill n8n-mcp-tools-expertLoading…
Master guide for using n8n-mcp MCP server tools to build workflows.
n8n-mcp provides 40+ tools organized into categories:
| 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 |
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)
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)
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)
Two different formats for different tools!
// Use SHORT prefix
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"
Tools that use this:
// Use FULL prefix
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"
Tools that use this:
// search_nodes returns BOTH formats
{
"nodeType": "nodes-base.slack", // For search/validate tools
"workflowNodeType": "n8n-nodes-base.slack" // For workflow tools
}
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!
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 get_node_info:
Better alternatives:
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
What happens: ALL nodes sanitized on ANY workflow update
Auto-fixes:
Cannot fix:
// After ANY update, auto-sanitization runs on ALL nodes
n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures
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
}
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
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
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"});
See SEARCH_GUIDE.md for:
See VALIDATION_GUIDE.md for:
See WORKFLOW_GUIDE.md for:
// 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
});
Templates include:
// List all tools
tools_documentation()
// Specific tool details
tools_documentation({
topic: "search_nodes",
depth: "full"
})
// Verify MCP server connectivity
n8n_health_check()
// → Returns: status, features, API availability, version
get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates
Always Available (no n8n API needed):
Requires n8n API (N8N_API_URL + N8N_API_KEY):
If API tools unavailable, use templates and validation-only workflows.
| 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 |
Most Important:
nodes-base.* (search) vs n8n-nodes-base.* (workflows)Common Workflow:
For details, see:
Related Skills:
| 96.8% |
| n8n_update_partial_workflow | 50-200ms | Small | 99.0% |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).