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 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 deploy 2,700+ real workflows 5. **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**: 1. `get_node({detail: "standard"})` - for operations list (default) 2. `get_node({mode: "docs"})` - for readable documentation 3. `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](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](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](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" });