--- 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. 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.

---

## 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. **Data Tables** - Manage n8n data tables, rows and columns (`n8n_manage_datatable`) 6. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`) 7. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`) 8. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`) 9. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides 10. **Agents** - Create, configure, validate, run and publish persisted n8n Agents (`n8n_manage_agents`, requires `N8N_MCP_ACCESS_TOKEN`) 11. **Node Resource Resolution** - Resolve live dropdown/resource-locator values with a real credential (`n8n_explore_node_resources`, requires `N8N_MCP_ACCESS_TOKEN`) 12. **Instance Catalog** - List projects and tags (`n8n_list_catalog`)

---

## 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 | | `n8n_manage_datatable` | Managing data tables and rows | 50-500ms | | `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms | | `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms | | `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms | | `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms | | `n8n_manage_agents` | Persisted n8n Agent CRUD/validate/publish | 150-400ms; `call` action: 5-60s | | `n8n_explore_node_resources` | Resolve live loadOptions/listSearch values | 200 ms - 5 s | | `n8n_list_catalog` | List projects or tags | 50-300ms |

---

## 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: 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 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.

```javascript // ❌ 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 ```

2. **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.

3. **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 ```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

Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:

```javascript // 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 tools get_node({nodeType: "nodes-base.slack"}) // ✅

// credentials must be nested by type with {id, name} — not a flat string updates: {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: {...}` | | 8 | Wrong credential format | Nest by type with `{id, name}` (see above) |

Full WRONG/CORRECT examples for each: see [VALIDATION_GUIDE.md → Common Mistakes](VALIDATION_GUIDE.md).

---

## Tool Usage Patterns

Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.

- **Pattern 1 — Node Discovery** (18s avg between steps): `search_nodes({query})` → `get_node({nodeType, includeExamples: true})`. See [SEARCH_GUIDE.md](SEARCH_GUIDE.md). - **Pattern 2 — Validation Loop** (23s thinking, 58s fixing): `validate_node({profile: "runtime"})` → read `errors` → fix config → validate again until clean. See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md). - **Pattern 3 — Workflow Editing** (99.0% success, 56s avg between edits): iterate `n8n_update_partial_workflow` (with `intent`) → `n8n_validate_workflow` → finally `activateWorkflow`. Build iteratively, NOT one-shot. See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md).

---

## 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 (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!) - Smart parameters (branch, case) - AI connection types (8 types) - Workflow activation (activateWorkflow/deactivateWorkflow) - n8n_deploy_template - n8n_workflow_versions - n8n_manage_folders (folder CRUD + workflow placement) - n8n_manage_credentials (credential CRUD + schema discovery) - n8n_audit_instance (security auditing)

### Templates, Data Tables & Self-Help See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for: - search_templates / get_template / n8n_deploy_template examples - n8n_manage_datatable (full actions, filter conditions, examples) - tools_documentation, ai_agents_guide, n8n_health_check

---

## Template Usage

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).

See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy examples.

---

## Running Workflows

`n8n_test_workflow` has one required parameter (`workflowId`) and a `method` that picks the path:

| `method` | Backend | What it does | |---|---|---| | `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be **active**. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** | | `trigger` | Public API | Same HTTP path, requested explicitly. | | `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. | | `pinned` | n8n's MCP server | Runs the workflow with `pinData` standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in `error`/`crashed`/`canceled` comes back as `EXECUTION_FAILED` with the `executionId`. | | `direct` | n8n's MCP server | Starts a run and returns once it has started; nothing is pinned, so every node runs. `message` or `data`/`headers` are forwarded to the trigger as input. |

- The last three need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+) a

--- 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. 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.

---

## 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. **Data Tables** - Manage n8n data tables, rows and columns (`n8n_manage_datatable`) 6. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`) 7. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`) 8. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`) 9. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides 10. **Agents** - Create, configure, validate, run and publish persisted n8n Agents (`n8n_manage_agents`, requires `N8N_MCP_ACCESS_TOKEN`) 11. **Node Resource Resolution** - Resolve live dropdown/resource-locator values with a real credential (`n8n_explore_node_resources`, requires `N8N_MCP_ACCESS_TOKEN`) 12. **Instance Catalog** - List projects and tags (`n8n_list_catalog`)

---

## 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 | | `n8n_manage_datatable` | Managing data tables and rows | 50-500ms | | `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms | | `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms | | `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms | | `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms | | `n8n_manage_agents` | Persisted n8n Agent CRUD/validate/publish | 150-400ms; `call` action: 5-60s | | `n8n_explore_node_resources` | Resolve live loadOptions/listSearch values | 200 ms - 5 s | | `n8n_list_catalog` | List projects or tags | 50-300ms |

---

## 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: 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 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.

```javascript // ❌ 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 ```

2. **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.

3. **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 ```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

Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:

```javascript // 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 tools get_node({nodeType: "nodes-base.slack"}) // ✅

// credentials must be nested by type with {id, name} — not a flat string updates: {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: {...}` | | 8 | Wrong credential format | Nest by type with `{id, name}` (see above) |

Full WRONG/CORRECT examples for each: see [VALIDATION_GUIDE.md → Common Mistakes](VALIDATION_GUIDE.md).

---

## Tool Usage Patterns

Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.

- **Pattern 1 — Node Discovery** (18s avg between steps): `search_nodes({query})` → `get_node({nodeType, includeExamples: true})`. See [SEARCH_GUIDE.md](SEARCH_GUIDE.md). - **Pattern 2 — Validation Loop** (23s thinking, 58s fixing): `validate_node({profile: "runtime"})` → read `errors` → fix config → validate again until clean. See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md). - **Pattern 3 — Workflow Editing** (99.0% success, 56s avg between edits): iterate `n8n_update_partial_workflow` (with `intent`) → `n8n_validate_workflow` → finally `activateWorkflow`. Build iteratively, NOT one-shot. See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md).

---

## 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 (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!) - Smart parameters (branch, case) - AI connection types (8 types) - Workflow activation (activateWorkflow/deactivateWorkflow) - n8n_deploy_template - n8n_workflow_versions - n8n_manage_folders (folder CRUD + workflow placement) - n8n_manage_credentials (credential CRUD + schema discovery) - n8n_audit_instance (security auditing)

### Templates, Data Tables & Self-Help See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for: - search_templates / get_template / n8n_deploy_template examples - n8n_manage_datatable (full actions, filter conditions, examples) - tools_documentation, ai_agents_guide, n8n_health_check

---

## Template Usage

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).

See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy examples.

---

## Running Workflows

`n8n_test_workflow` has one required parameter (`workflowId`) and a `method` that picks the path:

| `method` | Backend | What it does | |---|---|---| | `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be **active**. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** | | `trigger` | Public API | Same HTTP path, requested explicitly. | | `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. | | `pinned` | n8n's MCP server | Runs the workflow with `pinData` standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in `error`/`crashed`/`canceled` comes back as `EXECUTION_FAILED` with the `executionId`. | | `direct` | n8n's MCP server | Starts a run and returns once it has started; nothing is pinned, so every node runs. `message` or `data`/`headers` are forwarded to the trigger as input. |

- The last three need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+) a

--- 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. 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.

---

## 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. **Data Tables** - Manage n8n data tables, rows and columns (`n8n_manage_datatable`) 6. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`) 7. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`) 8. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`) 9. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides 10. **Agents** - Create, configure, validate, run and publish persisted n8n Agents (`n8n_manage_agents`, requires `N8N_MCP_ACCESS_TOKEN`) 11. **Node Resource Resolution** - Resolve live dropdown/resource-locator values with a real credential (`n8n_explore_node_resources`, requires `N8N_MCP_ACCESS_TOKEN`) 12. **Instance Catalog** - List projects and tags (`n8n_list_catalog`)

---

## 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 | | `n8n_manage_datatable` | Managing data tables and rows | 50-500ms | | `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms | | `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms | | `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms | | `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms | | `n8n_manage_agents` | Persisted n8n Agent CRUD/validate/publish | 150-400ms; `call` action: 5-60s | | `n8n_explore_node_resources` | Resolve live loadOptions/listSearch values | 200 ms - 5 s | | `n8n_list_catalog` | List projects or tags | 50-300ms |

---

## 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: 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 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.

```javascript // ❌ 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 ```

2. **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.

3. **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 ```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

Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:

```javascript // 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 tools get_node({nodeType: "nodes-base.slack"}) // ✅

// credentials must be nested by type with {id, name} — not a flat string updates: {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: {...}` | | 8 | Wrong credential format | Nest by type with `{id, name}` (see above) |

Full WRONG/CORRECT examples for each: see [VALIDATION_GUIDE.md → Common Mistakes](VALIDATION_GUIDE.md).

---

## Tool Usage Patterns

Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.

- **Pattern 1 — Node Discovery** (18s avg between steps): `search_nodes({query})` → `get_node({nodeType, includeExamples: true})`. See [SEARCH_GUIDE.md](SEARCH_GUIDE.md). - **Pattern 2 — Validation Loop** (23s thinking, 58s fixing): `validate_node({profile: "runtime"})` → read `errors` → fix config → validate again until clean. See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md). - **Pattern 3 — Workflow Editing** (99.0% success, 56s avg between edits): iterate `n8n_update_partial_workflow` (with `intent`) → `n8n_validate_workflow` → finally `activateWorkflow`. Build iteratively, NOT one-shot. See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md).

---

## 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 (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!) - Smart parameters (branch, case) - AI connection types (8 types) - Workflow activation (activateWorkflow/deactivateWorkflow) - n8n_deploy_template - n8n_workflow_versions - n8n_manage_folders (folder CRUD + workflow placement) - n8n_manage_credentials (credential CRUD + schema discovery) - n8n_audit_instance (security auditing)

### Templates, Data Tables & Self-Help See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for: - search_templates / get_template / n8n_deploy_template examples - n8n_manage_datatable (full actions, filter conditions, examples) - tools_documentation, ai_agents_guide, n8n_health_check

---

## Template Usage

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).

See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy examples.

---

## Running Workflows

`n8n_test_workflow` has one required parameter (`workflowId`) and a `method` that picks the path:

| `method` | Backend | What it does | |---|---|---| | `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be **active**. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** | | `trigger` | Public API | Same HTTP path, requested explicitly. | | `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. | | `pinned` | n8n's MCP server | Runs the workflow with `pinData` standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in `error`/`crashed`/`canceled` comes back as `EXECUTION_FAILED` with the `executionId`. | | `direct` | n8n's MCP server | Starts a run and returns once it has started; nothing is pinned, so every node runs. `message` or `data`/`headers` are forwarded to the trigger as input. |

- The last three need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+) a

--- 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. 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.

---

## 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. **Data Tables** - Manage n8n data tables, rows and columns (`n8n_manage_datatable`) 6. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`) 7. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`) 8. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`) 9. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides 10. **Agents** - Create, configure, validate, run and publish persisted n8n Agents (`n8n_manage_agents`, requires `N8N_MCP_ACCESS_TOKEN`) 11. **Node Resource Resolution** - Resolve live dropdown/resource-locator values with a real credential (`n8n_explore_node_resources`, requires `N8N_MCP_ACCESS_TOKEN`) 12. **Instance Catalog** - List projects and tags (`n8n_list_catalog`)

---

## 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 | | `n8n_manage_datatable` | Managing data tables and rows | 50-500ms | | `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms | | `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms | | `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms | | `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms | | `n8n_manage_agents` | Persisted n8n Agent CRUD/validate/publish | 150-400ms; `call` action: 5-60s | | `n8n_explore_node_resources` | Resolve live loadOptions/listSearch values | 200 ms - 5 s | | `n8n_list_catalog` | List projects or tags | 50-300ms |

---

## 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: 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 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.

```javascript // ❌ 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 ```

2. **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.

3. **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 ```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

Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:

```javascript // 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 tools get_node({nodeType: "nodes-base.slack"}) // ✅

// credentials must be nested by type with {id, name} — not a flat string updates: {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: {...}` | | 8 | Wrong credential format | Nest by type with `{id, name}` (see above) |

Full WRONG/CORRECT examples for each: see [VALIDATION_GUIDE.md → Common Mistakes](VALIDATION_GUIDE.md).

---

## Tool Usage Patterns

Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.

- **Pattern 1 — Node Discovery** (18s avg between steps): `search_nodes({query})` → `get_node({nodeType, includeExamples: true})`. See [SEARCH_GUIDE.md](SEARCH_GUIDE.md). - **Pattern 2 — Validation Loop** (23s thinking, 58s fixing): `validate_node({profile: "runtime"})` → read `errors` → fix config → validate again until clean. See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md). - **Pattern 3 — Workflow Editing** (99.0% success, 56s avg between edits): iterate `n8n_update_partial_workflow` (with `intent`) → `n8n_validate_workflow` → finally `activateWorkflow`. Build iteratively, NOT one-shot. See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md).

---

## 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 (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!) - Smart parameters (branch, case) - AI connection types (8 types) - Workflow activation (activateWorkflow/deactivateWorkflow) - n8n_deploy_template - n8n_workflow_versions - n8n_manage_folders (folder CRUD + workflow placement) - n8n_manage_credentials (credential CRUD + schema discovery) - n8n_audit_instance (security auditing)

### Templates, Data Tables & Self-Help See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for: - search_templates / get_template / n8n_deploy_template examples - n8n_manage_datatable (full actions, filter conditions, examples) - tools_documentation, ai_agents_guide, n8n_health_check

---

## Template Usage

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).

See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy examples.

---

## Running Workflows

`n8n_test_workflow` has one required parameter (`workflowId`) and a `method` that picks the path:

| `method` | Backend | What it does | |---|---|---| | `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be **active**. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** | | `trigger` | Public API | Same HTTP path, requested explicitly. | | `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. | | `pinned` | n8n's MCP server | Runs the workflow with `pinData` standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in `error`/`crashed`/`canceled` comes back as `EXECUTION_FAILED` with the `executionId`. | | `direct` | n8n's MCP server | Starts a run and returns once it has started; nothing is pinned, so every node runs. `message` or `data`/`headers` are forwarded to the trigger as input. |

- The last three need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+) a