domains / agent-tooling / n8n-mcp-tool-usage / n8n-mcp-tools-expert

n8n-mcp-tools-expert

Skill card

combined

The two copies cover the same n8n-mcp tooling domain but each contains material steps the other lacks. The czlonkowski copy is the more complete, original-style guide: it enumerates the full tool catalog (data tables, folders, credentials, audit, agents, resource resolution, instance catalog), gives a quick-reference table with success-rate/speed heuristics, and—critically—includes a 'Node JSON Hygiene' section (omit placeholder credentials, use UUID v4 node IDs, use current typeVersion) and a 'nodeType Formats' section that the other copy does not. The sickn33 copy is a wrapper that defers to a references/detailed-guide.md and adds its own material: explicit 'When to Use' triggers, a 'Limitations' section (stop and ask for clarification when inputs/permissions/safety boundaries are missing), and a more detailed Template Usage section (search by nodes/task/metadata, get_template modes, n8n_deploy_template with autoFix/autoUpgradeVersions). They also disagree on how to proceed: czlonkowski says 'Always consult this skill before calling any n8n-mcp tool' and inlines the full procedure, while sickn33 says 'Read the detailed guide before executing this skill' and treats its safety/prerequisites as mandatory. Crowning one would hide the other's real alternative (the wrapper's safety/limitations framing and template-search modes vs. the original's JSON-hygiene and nodeType-format rules).

Repositories

Other copies

Combined skill

---
name: n8n-mcp-tools-expert
description: 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. Always consult this skill before calling any n8n-mcp tool.
---

# n8n MCP Tools Expert

Master guide for using n8n-mcp MCP server tools to build workflows.

## When to Use
- You are using the n8n-mcp toolset to discover nodes, validate configs, or manage workflows.
- The task involves choosing the right MCP tool or understanding its expected parameters and usage pattern.
- You need guidance on workflow creation or editing through n8n MCP rather than through the n8n UI alone.
- If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.

## Prerequisites and Safety
- Treat safety, prerequisites, and validation requirements as mandatory.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

## Tool Categories
1. Node Discovery (search_nodes, get_node)
2. Configuration Validation (validate_node, validate_workflow)
3. Workflow Management (n8n_create_workflow, n8n_update_partial_workflow, n8n_validate_workflow, n8n_autofix_workflow)
4. Template Library (search_templates, get_template, n8n_deploy_template)
5. Data Tables (n8n_manage_datatable)
6. Workflow Folders (n8n_manage_folders)
7. Credential Management (n8n_manage_credentials)
8. Security & Audit (n8n_audit_instance)
9. Documentation & Guides
10. Agents (n8n_manage_agents, requires N8N_MCP_ACCESS_TOKEN)
11. Node Resource Resolution (n8n_explore_node_resources, requires N8N_MCP_ACCESS_TOKEN)
12. Instance Catalog (n8n_list_catalog)

## Tool Selection Guide

### Finding the Right Node
1. search_nodes({query: "keyword"})
2. get_node({nodeType: "nodes-base.name"})
3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})

Common pattern: search → get_node (~18s average).

### Validating Configuration
1. validate_node({nodeType, config: {}, mode: "minimal"}) — check required fields
2. validate_node({nodeType, config, profile: "runtime"}) — full validation
3. Fix errors, validate again

Common pattern: validate → fix → validate (~23s thinking, ~58s fixing per cycle).

### Managing Workflows
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). Use n8n_update_partial_workflow for most edits (highest success rate).

### Critical: Node JSON Hygiene When Creating Workflows
Three structural mistakes in generated node JSON break the n8n UI even when the workflow validates:
1. Never emit a credentials block with a placeholder ID. A fake ID like "id": "REPLACE_ME" renders the credential selector permanently disabled. If you don't know the real credential ID, omit the credentials block entirely. Use n8n_manage_credentials({action: "list"}) to discover real credential IDs first.
2. Generate UUID v4 values for node id — not human-readable strings. Non-UUID IDs cause subtle UI breakage.
3. Use the current typeVersion for each node — check get_node rather than hardcoding remembered versions.

### Critical: nodeType Formats
Two different formats for different tools:
- Search/Validate tools: use SHORT prefix (e.g. "nodes-base.slack").
- Workflow creation/update tools: use the full node type as returned by get_node.

## Template Usage

### Search Templates
- search_templates({query: "webhook slack", limit: 20})
- search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})
- search_templates({searchMode: "by_task", task: "webhook_processing"})
- search_templates({searchMode: "by_metadata", complexity: "simple", maxSetupMinutes: 15})

### Get Template Details
- get_template({templateId: 2947, mode: "structure"}) — nodes+connections only
- get_template({templateId: 2947, mode: "full"}) — complete workflow JSON

### Deploy Template Directly
n8n_deploy_template({
  templateId: 2947,
  name: "My Weather to Slack",
  autoFix: true,
  autoUpgradeVersions: true
})
Returns: workflow ID, required credentials, fixes applied.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.