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 sickn33/antigravity-awesome-skills--skill n8n-mcp-tools-expertLoading…
Master guide for using n8n-mcp MCP server tools to build workflows.
n8n-mcp toolset to discover nodes, validate configs, or manage workflows.n8n-mcp provides tools organized into categories:
| 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 |
Workflow:
1. search_nodes({query: "keyword"})
2. get_node({nodeType: "nodes-base.name"})
3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
Example:
// 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)
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)
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)
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
// WRONG
get_node({nodeType: "slack"}) // Missing prefix
get_node({nodeType: "n8n-nodes-base.slack"}) // Wrong prefix
// CORRECT
get_node({nodeType: "nodes-base.slack"})
Problem: Huge payload, slower response, token waste
// 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":
Better alternatives:
get_node({detail: "standard"}) - for operations list (default)get_node({mode: "docs"}) - for readable documentationget_node({mode: "search_properties", propertyQuery: "auth"}) - for specific propertyProblem: 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)// WRONG - Uses default profile
validate_node({nodeType, config})
// CORRECT - Explicit profile
validate_node({nodeType, config, profile: "runtime"})
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
}
Problem: Less helpful tool responses
// 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: {...}}]
})
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({
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({
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
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",
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"}]
});
See SEARCH_GUIDE.md for:
See VALIDATION_GUIDE.md for:
See WORKFLOW_GUIDE.md for:
// 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"
});
// Search by metadata (complexity, setup time)
search_templates({
searchMode: "by_metadata",
complexity: "simple",
maxSetupMinutes: 15
});
get_template({
templateId: 2947,
mode: "structure" // nodes+connections only
});
get_template({
templateId: 2947,
mode: "full" // complete workflow JSON
});
// Deploy template to your n8n instance
n8n_deploy_template({
templateId: 2947,
name: "My Weather to Slack", // Custom name (optional)
autoFix: true, // Auto-fix common issues (default)
autoUpgradeVersions: true // Upgrade node versions (default)
});
// Returns: workflow ID, required credentials, fixes applied
// Overview of all tools
tools_documentation()
// Specific tool details
tools_documentation({
topic: "search_nodes",
depth: "full"
})
// Code node guides
tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
tools_documentation({topic: "python_code_node_guide", depth: "full"})
// Comprehensive AI workflow guide
ai_agents_guide()
// Returns: Architecture, connections, tools, validation, best practices
// Quick health check
n8n_health_check()
// Detailed diagnostics
n8n_health_check({mode: "diagnostic"})
// → Returns: status, env vars, tool status, API connectivity
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.
Detail Levels (mode="info", default):
minimal (~200 tokens) - Basic metadata onlystandard (~1-2K tokens) - Essential properties + operations (RECOMMENDED)full (~3-8K tokens) - Complete schema (use sparingly)Operation Modes:
info (default) - Node schema with detail leveldocs - Readable markdown documentationsearch_properties - Find specific properties (use with propertyQuery)versions - List all versions with breaking changescompare - Compare two versionsbreaking - Show only breaking changesmigrations - Show auto-migratable changes// Standard (recommended)
get_node({nodeType: "nodes-base.httpRequest"})
// Get documentation
get_node({nodeType: "nodes-base.webhook", mode: "docs"})
// Search for properties
get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
// Check versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
Modes:
full (default) - Comprehensive validation with errors/warnings/suggestionsminimal - Quick required fields check onlyProfiles (for mode="full"):
minimal - Very lenientruntime - Standard (default, recommended)ai-friendly - Balanced for AI workflowsstrict - Most thorough (production)// Full validation with runtime profile
validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})
// Quick required fields check
validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
| 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_create_workflow | 100-500ms | Medium |
| n8n_update_partial_workflow | 50-200ms | Small |
| n8n_deploy_template | 200-500ms | Medium |
get_node({detail: "standard"}) for most use casesprofile: "runtime")branch, case) for clarityintent parameter in workflow updatesincludeExamples: true for real configsn8n_deploy_template for quick startsdetail: "full" unless necessary (wastes tokens)nodes-base.*)n8n-nodes-base.*) with search/validate toolsMost Important:
detail: "standard" (default) - covers 95% of use casesnodes-base.* (search/validate) vs n8n-nodes-base.* (workflows)runtime recommended)branch="true", case=0)activateWorkflow operation)Common Workflow:
For details, see:
Related Skills:
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).