n8n-mcp-tools-expert

# 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](SEARCH_GUIDE.md) 2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) 3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) 4. **Template Library** - Search and access 2,653 real workflows 5. **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**: 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) ```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](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](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](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 |