N8n MCP Tools Expert

1---
2name: n8n-mcp-tools-expert
3description: 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.
4---
5 
6# n8n MCP Tools Expert
7 
8Master guide for using n8n-mcp MCP server tools to build workflows.
9 
10---
11 
12## Tool Categories
13 
14n8n-mcp provides tools organized into categories:
15 
161. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md)
172. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md)
183. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
194. **Template Library** - Search and deploy 2,700+ real workflows
205. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
21 
22---
23 
24## Quick Reference
25 
26### Most Used Tools (by success rate)
27 
28| Tool | Use When | Speed |
29|------|----------|-------|
30| `search_nodes` | Finding nodes by keyword | <20ms |
31| `get_node` | Understanding node operations (detail="standard") | <10ms |
32| `validate_node` | Checking configurations (mode="full") | <100ms |
33| `n8n_create_workflow` | Creating workflows | 100-500ms |
34| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 50-200ms |
35| `validate_workflow` | Checking complete workflow | 100-500ms |
36| `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
37 
38---
39 
40## Tool Selection Guide
41 
42### Finding the Right Node
43 
44**Workflow**:
45```
461. search_nodes({query: "keyword"})
472. get_node({nodeType: "nodes-base.name"})
483. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
49```
50 
51**Example**:
52```javascript
53// Step 1: Search
54search_nodes({query: "slack"})
55// Returns: nodes-base.slack
56 
57// Step 2: Get details
58get_node({nodeType: "nodes-base.slack"})
59// Returns: operations, properties, examples (standard detail)
60 
61// Step 3: Get readable documentation
62get_node({nodeType: "nodes-base.slack", mode: "docs"})
63// Returns: markdown documentation
64```
65 
66**Common pattern**: search → get_node (18s average)
67 
68### Validating Configuration
69 
70**Workflow**:
71```
721. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
732. validate_node({nodeType, config, profile: "runtime"}) - Full validation
743. [Repeat] Fix errors, validate again
75```
76 
77**Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle)
78 
79### Managing Workflows
80 
81**Workflow**:
82```
831. n8n_create_workflow({name, nodes, connections})
842. n8n_validate_workflow({id})
853. n8n_update_partial_workflow({id, operations: [...]})
864. n8n_validate_workflow({id}) again
875. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})
88```
89 
90**Common pattern**: iterative updates (56s average between edits)
91 
92---
93 
94## Critical: nodeType Formats
95 
96**Two different formats** for different tools!
97 
98### Format 1: Search/Validate Tools
99```javascript
100// Use SHORT prefix
101"nodes-base.slack"
102"nodes-base.httpRequest"
103"nodes-base.webhook"
104"nodes-langchain.agent"
105```
106 
107**Tools that use this**:
108- search_nodes (returns this format)
109- get_node
110- validate_node
111- validate_workflow
112 
113### Format 2: Workflow Tools
114```javascript
115// Use FULL prefix
116"n8n-nodes-base.slack"
117"n8n-nodes-base.httpRequest"
118"n8n-nodes-base.webhook"
119"@n8n/n8n-nodes-langchain.agent"
120```
121 
122**Tools that use this**:
123- n8n_create_workflow
124- n8n_update_partial_workflow
125 
126### Conversion
127 
128```javascript
129// search_nodes returns BOTH formats
130{
131  "nodeType": "nodes-base.slack",          // For search/validate tools
132  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
133}
134```
135 
136---
137 
138## Common Mistakes
139 
140### Mistake 1: Wrong nodeType Format
141 
142**Problem**: "Node not found" error
143 
144```javascript
145// WRONG
146get_node({nodeType: "slack"})  // Missing prefix
147get_node({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix
148 
149// CORRECT
150get_node({nodeType: "nodes-base.slack"})
151```
152 
153### Mistake 2: Using detail="full" by Default
154 
155**Problem**: Huge payload, slower response, token waste
156 
157```javascript
158// WRONG - Returns 3-8K tokens, use sparingly
159get_node({nodeType: "nodes-base.slack", detail: "full"})
160 
161// CORRECT - Returns 1-2K tokens, covers 95% of use cases
162get_node({nodeType: "nodes-base.slack"})  // detail="standard" is default
163get_node({nodeType: "nodes-base.slack", detail: "standard"})
164```
165 
166**When to use detail="full"**:
167- Debugging complex configuration issues
168- Need complete property schema with all nested options
169- Exploring advanced features
170 
171**Better alternatives**:
1721. `get_node({detail: "standard"})` - for operations list (default)
1732. `get_node({mode: "docs"})` - for readable documentation
1743. `get_node({mode: "search_properties", propertyQuery: "auth"})` - for specific property
175 
176### Mistake 3: Not Using Validation Profiles
177 
178**Problem**: Too many false positives OR missing real errors
179 
180**Profiles**:
181- `minimal` - Only required fields (fast, permissive)
182- `runtime` - Values + types (recommended for pre-deployment)
183- `ai-friendly` - Reduce false positives (for AI configuration)
184- `strict` - Maximum validation (for production)
185 
186```javascript
187// WRONG - Uses default profile
188validate_node({nodeType, config})
189 
190// CORRECT - Explicit profile
191validate_node({nodeType, config, profile: "runtime"})
192```
193 
194### Mistake 4: Ignoring Auto-Sanitization
195 
196**What happens**: ALL nodes sanitized on ANY workflow update
197 
198**Auto-fixes**:
199- Binary operators (equals, contains) → removes singleValue
200- Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
201- IF/Switch nodes → adds missing metadata
202 
203**Cannot fix**:
204- Broken connections
205- Branch count mismatches
206- Paradoxical corrupt states
207 
208```javascript
209// After ANY update, auto-sanitization runs on ALL nodes
210n8n_update_partial_workflow({id, operations: [...]})
211// → Automatically fixes operator structures
212```
213 
214### Mistake 5: Not Using Smart Parameters
215 
216**Problem**: Complex sourceIndex calculations for multi-output nodes
217 
218**Old way** (manual):
219```javascript
220// IF node connection
221{
222  type: "addConnection",
223  source: "IF",
224  target: "Handler",
225  sourceIndex: 0  // Which output? Hard to remember!
226}
227```
228 
229**New way** (smart parameters):
230```javascript
231// IF node - semantic branch names
232{
233  type: "addConnection",
234  source: "IF",
235  target: "True Handler",
236  branch: "true"  // Clear and readable!
237}
238 
239{
240  type: "addConnection",
241  source: "IF",
242  target: "False Handler",
243  branch: "false"
244}
245 
246// Switch node - semantic case numbers
247{
248  type: "addConnection",
249  source: "Switch",
250  target: "Handler A",
251  case: 0
252}
253```
254 
255### Mistake 6: Not Using intent Parameter
256 
257**Problem**: Less helpful tool responses
258 
259```javascript
260// WRONG - No context for response
261n8n_update_partial_workflow({
262  id: "abc",
263  operations: [{type: "addNode", node: {...}}]
264})
265 
266// CORRECT - Better AI responses
267n8n_update_partial_workflow({
268  id: "abc",
269  intent: "Add error handling for API failures",
270  operations: [{type: "addNode", node: {...}}]
271})
272```
273 
274---
275 
276## Tool Usage Patterns
277 
278### Pattern 1: Node Discovery (Most Common)
279 
280**Common workflow**: 18s average between steps
281 
282```javascript
283// Step 1: Search (fast!)
284const results = await search_nodes({
285  query: "slack",
286  mode: "OR",  // Default: any word matches
287  limit: 20
288});
289// → Returns: nodes-base.slack, nodes-base.slackTrigger
290 
291// Step 2: Get details (~18s later, user reviewing results)
292const details = await get_node({
293  nodeType: "nodes-base.slack",
294  includeExamples: true  // Get real template configs
295});
296// → Returns: operations, properties, metadata
297```
298 
299### Pattern 2: Validation Loop
300 
301**Typical cycle**: 23s thinking, 58s fixing
302 
303```javascript
304// Step 1: Validate
305const result = await validate_node({
306  nodeType: "nodes-base.slack",
307  config: {
308    resource: "channel",
309    operation: "create"
310  },
311  profile: "runtime"
312});
313 
314// Step 2: Check errors (~23s thinking)
315if (!result.valid) {
316  console.log(result.errors);  // "Missing required field: name"
317}
318 
319// Step 3: Fix config (~58s fixing)
320config.name = "general";
321 
322// Step 4: Validate again
323await validate_node({...});  // Repeat until clean
324```
325 
326### Pattern 3: Workflow Editing
327 
328**Most used update tool**: 99.0% success rate, 56s average between edits
329 
330```javascript
331// Iterative workflow building (NOT one-shot!)
332// Edit 1
333await n8n_update_partial_workflow({
334  id: "workflow-id",
335  intent: "Add webhook trigger",
336  operations: [{type: "addNode", node: {...}}]
337});
338 
339// ~56s later...
340 
341// Edit 2
342await n8n_update_partial_workflow({
343  id: "workflow-id",
344  intent: "Connect webhook to processor",
345  operations: [{type: "addConnection", source: "...", target: "..."}]
346});
347 
348// ~56s later...
349 
350// Edit 3 (validation)
351await n8n_validate_workflow({id: "workflow-id"});
352 
353// Ready? Activate!
354await n8n_update_partial_workflow({
355  id: "workflow-id",
356  intent: "Activate workflow for production",
357  operations: [{type: "activateWorkflow"}]
358});
359```
360 
361---
362 
363## Detailed Guides
364 
365### Node Discovery Tools
366See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for:
367- search_nodes
368- get_node with detail levels (minimal, standard, full)
369- get_node modes (info, docs, search_properties, versions)
370 
371### Validation Tools
372See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
373- Validation profiles explained
374- validate_node with modes (minimal, full)
375- validate_workflow complete structure
376- Auto-sanitization system
377- Handling validation errors
378 
379### Workflow Management
380See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
381- n8n_create_workflow
382- n8n_update_partial_workflow (17 operation types!)
383- Smart parameters (branch, case)
384- AI connection types (8 types)
385- Workflow activation (activateWorkflow/deactivateWorkflow)
386- n8n_deploy_template
387- n8n_workflow_versions
388 
389---
390 
391## Template Usage
392 
393### Search Templates
394 
395```javascript
396// Search by keyword (default mode)
397search_templates({
398  query: "webhook slack",
399  limit: 20
400});
401 
402// Search by node types
403search_templates({
404  searchMode: "by_nodes",
405  nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]
406});
407 
408// Search by task type
409search_templates({
410  searchMode: "by_task",
411  task: "webhook_processing"
412});
413 
414// Search by metadata (complexity, setup time)
415search_templates({
416  searchMode: "by_metadata",
417  complexity: "simple",
418  maxSetupMinutes: 15
419});
420```
421 
422### Get Template Details
423 
424```javascript
425get_template({
426  templateId: 2947,
427  mode: "structure"  // nodes+connections only
428});
429 
430get_template({
431  templateId: 2947,
432  mode: "full"  // complete workflow JSON
433});
434```
435 
436### Deploy Template Directly
437 
438```javascript
439// Deploy template to your n8n instance
440n8n_deploy_template({
441  templateId: 2947,
442  name: "My Weather to Slack",  // Custom name (optional)
443  autoFix: true,  // Auto-fix common issues (default)
444  autoUpgradeVersions: true  // Upgrade node versions (default)
445});
446// Returns: workflow ID, required credentials, fixes applied
447```
448 
449---
450 
451## Self-Help Tools
452 
453### Get Tool Documentation
454 
455```javascript
456// Overview of all tools
457tools_documentation()
458 
459// Specific tool details
460tools_documentation({
461  topic: "search_nodes",
462  depth: "full"
463})
464 
465// Code node guides
466tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
467tools_documentation({topic: "python_code_node_guide", depth: "full"})
468```
469 
470### AI Agent Guide
471 
472```javascript
473// Comprehensive AI workflow guide
474ai_agents_guide()
475// Returns: Architecture, connections, tools, validation, best practices
476```
477 
478### Health Check
479 
480```javascript
481// Quick health check
482n8n_health_check()
483 
484// Detailed diagnostics
485n8n_health_check({mode: "diagnostic"})
486// → Returns: status, env vars, tool status, API connectivity
487```
488 
489---
490 
491## Tool Availability
492 
493**Always Available** (no n8n API needed):
494- search_nodes, get_node
495- validate_node, validate_workflow
496- search_templates, get_template
497- tools_documentation, ai_agents_guide
498 
499**Requires n8n API** (N8N_API_URL + N8N_API_KEY):
500- n8n_create_workflow
501- n8n_update_partial_workflow
502- n8n_validate_workflow (by ID)
503- n8n_list_workflows, n8n_get_workflow
504- n8n_test_workflow
505- n8n_executions
506- n8n_deploy_template
507- n8n_workflow_versions
508- n8n_autofix_workflow
509 
510If API tools unavailable, use templates and validation-only workflows.
511 
512---
513 
514## Unified Tool Reference
515 
516### get_node (Unified Node Information)
517 
518**Detail Levels** (mode="info", default):
519- `minimal` (~200 tokens) - Basic metadata only
520- `standard` (~1-2K tokens) - Essential properties + operations (RECOMMENDED)
521- `full` (~3-8K tokens) - Complete schema (use sparingly)
522 
523**Operation Modes**:
524- `info` (default) - Node schema with detail level
525- `docs` - Readable markdown documentation
526- `search_properties` - Find specific properties (use with propertyQuery)
527- `versions` - List all versions with breaking changes
528- `compare` - Compare two versions
529- `breaking` - Show only breaking changes
530- `migrations` - Show auto-migratable changes
531 
532```javascript
533// Standard (recommended)
534get_node({nodeType: "nodes-base.httpRequest"})
535 
536// Get documentation
537get_node({nodeType: "nodes-base.webhook", mode: "docs"})
538 
539// Search for properties
540get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
541 
542// Check versions
543get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
544```
545 
546### validate_node (Unified Validation)
547 
548**Modes**:
549- `full` (default) - Comprehensive validation with errors/warnings/suggestions
550- `minimal` - Quick required fields check only
551 
552**Profiles** (for mode="full"):
553- `minimal` - Very lenient
554- `runtime` - Standard (default, recommended)
555- `ai-friendly` - Balanced for AI workflows
556- `strict` - Most thorough (production)
557 
558```javascript
559// Full validation with runtime profile
560validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})
561 
562// Quick required fields check
563validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
564```
565 
566---
567 
568## Performance Characteristics
569 
570| Tool | Response Time | Payload Size |
571|------|---------------|--------------|
572| search_nodes | <20ms | Small |
573| get_node (standard) | <10ms | ~1-2KB |
574| get_node (full) | <100ms | 3-8KB |
575| validate_node (minimal) | <50ms | Small |
576| validate_node (full) | <100ms | Medium |
577| validate_workflow | 100-500ms | Medium |
578| n8n_create_workflow | 100-500ms | Medium |
579| n8n_update_partial_workflow | 50-200ms | Small |
580| n8n_deploy_template | 200-500ms | Medium |
581 
582---
583 
584## Best Practices
585 
586### Do
587- Use `get_node({detail: "standard"})` for most use cases
588- Specify validation profile explicitly (`profile: "runtime"`)
589- Use smart parameters (`branch`, `case`) for clarity
590- Include `intent` parameter in workflow updates
591- Follow search → get_node → validate workflow
592- Iterate workflows (avg 56s between edits)
593- Validate after every significant change
594- Use `includeExamples: true` for real configs
595- Use `n8n_deploy_template` for quick starts
596 
597### Don't
598- Use `detail: "full"` unless necessary (wastes tokens)
599- Forget nodeType prefix (`nodes-base.*`)
600- Skip validation profiles
601- Try to build workflows in one shot (iterate!)
602- Ignore auto-sanitization behavior
603- Use full prefix (`n8n-nodes-base.*`) with search/validate tools
604- Forget to activate workflows after building
605 
606---
607 
608## Summary
609 
610**Most Important**:
6111. Use **get_node** with `detail: "standard"` (default) - covers 95% of use cases
6122. nodeType formats differ: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
6133. Specify **validation profiles** (`runtime` recommended)
6144. Use **smart parameters** (`branch="true"`, `case=0`)
6155. Include **intent parameter** in workflow updates
6166. **Auto-sanitization** runs on ALL nodes during updates
6177. Workflows can be **activated via API** (`activateWorkflow` operation)
6188. Workflows are built **iteratively** (56s avg between edits)
619 
620**Common Workflow**:
6211. search_nodes → find node
6222. get_node → understand config
6233. validate_node → check config
6244. n8n_create_workflow → build
6255. n8n_validate_workflow → verify
6266. n8n_update_partial_workflow → iterate
6277. activateWorkflow → go live!
628 
629For details, see:
630- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery
631- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Configuration validation
632- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Workflow management
633 
634---
635 
636**Related Skills**:
637- n8n Expression Syntax - Write expressions in workflow fields
638- n8n Workflow Patterns - Architectural patterns from templates
639- n8n Validation Expert - Interpret validation errors
640- n8n Node Configuration - Operation-specific requirements
641- n8n Code JavaScript - Write JavaScript in Code nodes
642- n8n Code Python - Write Python in Code nodes
643