Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, organizing workflows into folders, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, organizing workflows into folders, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
n8n MCP Tools Expert
Master guide for using n8n-mcp MCP server tools to build workflows.
Common pattern: iterative updates (56s average between edits)
Critical: Node JSON Hygiene When Creating Workflows
Three structural mistakes in generated node JSON break the n8n UI even when the workflow validates:
Never emit a credentials block with a placeholder ID. A fake ID like "id": "REPLACE_ME" renders the credential selector permanently disabled and non-clickable in the n8n UI ("No credentials yet") — the user has to recreate the node from scratch. If you don't know the real credential ID, omit the credentials block entirely; an absent block shows a normal empty dropdown the user can click. Use n8n_manage_credentials({action: "list"}) to discover real credential IDs first.
// ❌ Breaks the credential selector"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "My API Key"}}
// ✅ Unknown ID → omit credentials block; user picks in UI// ✅ Known ID (from n8n_manage_credentials list) → use the real ID
Generate UUID v4 values for node id — not human-readable strings like "http-list-node". n8n's frontend uses node IDs for form binding and credential component initialization; non-UUID IDs cause subtle UI breakage.
Use the current typeVersion for each node — check get_node rather than hardcoding remembered versions (e.g. httpRequest is at 4.4+, not 4.2).
Critical: nodeType Formats
Two different formats for different tools!
Format 1: Search/Validate Tools
// 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
// 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
// search_nodes returns BOTH formats
{
"nodeType": "nodes-base.slack", // For search/validate tools"workflowNodeType": "n8n-nodes-base.slack"// For workflow tools
}
Common Mistakes
Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:
// nodeType prefix (search/validate tools want the SHORT form)get_node({nodeType: "slack"}) // ❌ missing prefix → "Node not found"get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ FULL prefix is for workflow toolsget_node({nodeType: "nodes-base.slack"}) // ✅// credentials must be nested by type with {id, name} — not a flat stringupdates: {credentials: "myApiKey"} // ❌updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "My API Key"}}} // ✅
#
Mistake
Fix
1
Wrong nodeType format
SHORT nodes-base.* for search/validate; FULL n8n-nodes-base.* for workflow tools (see above)
2
detail: "full" by default
Default standard covers 95%; reach for docs/search_properties instead of full
3
No validation profile
Pass profile: "runtime" explicitly (minimal/ai-friendly/strict for other stages)
4
Ignoring auto-sanitization
ALL nodes sanitized on ANY update (operator structures, IF/Switch metadata); it can't fix broken connections or branch-count mismatches
5
Not using smart parameters
Use branch: "true" / case: 0 instead of fragile sourceIndex math
6
Omitting intent
Always include intent on n8n_update_partial_workflow for better responses
7
parameters instead of updates
updateNode takes updates: {...}, not parameters: {...}
The 2,700+ template library has three tools: search_templates (modes query/by_nodes/by_task/by_metadata), get_template (modes structure/full), and n8n_deploy_template (deploys to your instance with autoFix/autoUpgradeVersions, returns workflow ID + required credentials + fixes applied).
n8n_manage_datatable is the MCP tool for managing data tables and rows from outside a workflow (table actions createTable/listTables/getTable/updateTable/deleteTable; row actions getRows/insertRows/updateRows/upsertRows/deleteRows, with filtering, pagination, and dryRun). Don't confuse it with the in-workflow nodes-base.dataTable node, which reads/writes rows during execution (see n8n-node-configuration → OPERATION_PATTERNS.md). Rule of thumb: MCP tool to set up a table once, workflow node to read/write on every execution. deleteRows requires a filter; use dryRun: true before bulk changes.
n8n_manage_folders organizes workflows into folders (actions create/list/get/rename/move/delete; n8n 2.19+, registered free Community tier and up). projectId defaults to 'personal'. Placing workflows happens in the workflow tools: parentFolderId on n8n_create_workflow, or the moveToFolder operation of n8n_update_partial_workflow (both n8n 2.32+; null = project root). Two things to internalize: a workflow's folder is write-only in n8n's API (verify placement via a folder's get counts, never by reading the workflow), and delete without transferToFolderIdarchives the folder's workflows (transferToFolderId: "0" moves them to the project root instead, keeping them active).
See WORKFLOW_GUIDE.md for all actions, list filters/counts, and the delete semantics.
Credential Management
n8n_manage_credentials is the unified credential tool: actions list, get, create, update, delete, getSchema. It never returns secrets — get/create/update strip the data field. Use getSchema before create to discover required fields. The optional includeUsage: true flag (on list/get) reverse-scans workflows and attaches usedIn: [{id, name, active}] + usageCount — use it before deleting or rotating a credential to see what breaks (it triggers a full client-side scan, caps at 5000 workflows, excludes archived, and degrades to a usageScanError field on failure).
See WORKFLOW_GUIDE.md for all actions, the includeUsage shape, security notes, and the safe delete/rotate workflow.
Security & Audit
n8n_audit_instance combines n8n's built-in audit (categories credentials/database/nodes/instance/filesystem) with a custom deep scan (hardcoded_secrets, unauthenticated_webhooks, error_handling, data_retention). All parameters optional: categories, includeCustomScan (default true), customChecks, daysAbandonedWorkflow. Detected secrets are masked (first 6 + last 4 chars). Output is an actionable markdown report — summary table, findings by workflow, and a Remediation Playbook split into auto-fixable / requires-review / requires-user-action.
See WORKFLOW_GUIDE.md for the two scanning approaches, examples, and remediation types in full.
Self-Help Tools
tools_documentation() — overview of all tools; tools_documentation({topic, depth: "full"}) for a specific tool. Code node guides via topics javascript_code_node_guide / python_code_node_guide.
AI agent guide — tools_documentation({topic: "ai_agents_guide", depth: "full"}) (no standalone tool); returns architecture, connections, tools, validation, best practices.
n8n_evaluations (reads: n8n 2.30+ with an API key created on 2.30+; run/cancel: n8n 2.32+ with a key created on 2.32+ — older keys lack the testRun scopes)
n8n_deploy_template
n8n_workflow_versions
n8n_autofix_workflow
n8n_manage_datatable
n8n_manage_folders (folder CRUD: n8n 2.19+, registered Community tier and up; workflow placement via parentFolderId/moveToFolder: n8n 2.32+)
n8n_manage_credentials
n8n_audit_instance
If API tools unavailable, use templates and validation-only workflows.
Unified Tool Reference
get_node — detail levels (minimal ~200 tok / standard ~1-2K, RECOMMENDED / full ~3-8K, sparingly) and modes (info default, docs, search_properties + propertyQuery, versions, compare, breaking, migrations). Deep dive in SEARCH_GUIDE.md.
validate_node — modes full (default, errors/warnings/suggestions) and minimal (required-fields check); profiles minimal/runtime (default, recommended)/ai-friendly/strict. Deep dive in VALIDATION_GUIDE.md.
Performance Characteristics
Tool
Response Time
Payload Size
search_nodes
<20ms
Small
get_node (standard)
<10ms
~1-2KB
get_node (full)
<100ms
3-8KB
validate_node (minimal)
<50ms
Small
validate_node (full)
<100ms
Medium
validate_workflow
100-500ms
Medium
n8n_manage_folders
100-500ms
Small
n8n_manage_credentials
50-500ms
Small-Medium
n8n_audit_instance
500-5000ms
Large
n8n_create_workflow
100-500ms
Medium
n8n_update_partial_workflow
50-200ms
Small
n8n_deploy_template
200-500ms
Medium
Best Practices
Do
For simple workflows (<=5 nodes), use MCP tools directly — don't over-engineer the investigation
Use patchNodeField for surgical edits to Code node content instead of replacing the entire node
Use get_node({detail: "standard"}) for most use cases
