n8n MCP Tools Expert

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
2. Configuration Validation → VALIDATION_GUIDE.md
3. Workflow Management → 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 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:

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

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

// 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 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"}}}  // ✅

Full WRONG/CORRECT examples for each: see VALIDATION_GUIDE.md → Common Mistakes.

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.
• Pattern 2 — Validation Loop (23s thinking, 58s fixing): validate_node({profile: "runtime"}) → read errors → fix config → validate again until clean. See 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.

Detailed Guides

Node Discovery Tools

See 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 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 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 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 for full search/get/deploy examples.

Running Workflows

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

• The last three need N8N_MCP_ACCESS_TOKEN (n8n 2.34+) and the workflow's "Available in MCP" setting.
• pinData is keyed by node name, and every value is an array of items wrapped as {"json": {...}} — {"Webhook": [{"json": {"id": "123"}}]}, never a flat object. It must be non-empty.
• triggerNodeName picks the trigger node to start from (defaults to the detected one; n8n requires it whenever inputs are given).
• Both run methods execute the workflow's nodes for real. direct runs every node; pinned pins only trigger nodes, nodes with credentials and HTTP Request nodes, so Code, Set, If and credential-free I/O (Execute Command, file read/write) still run. Confirm with the user before running a workflow that writes anywhere.
• executionMode applies to direct: manual (default) or production. It changes the execution context, not whether the run has side effects — a production run goes through the production execution path and is recorded as one. Only pass it when the user asked for one.
• timeoutMs is the client deadline for the official call (5000-600000; default 30000 for prepare, 300000 for pinned/direct).
• direct returns as soon as the run starts, so it reports success with an executionId regardless of how the run ends — poll n8n_executions({action: "get", id: executionId}) for the outcome. A dispatch n8n refuses outright comes back as OFFICIAL_MCP_ERROR, not EXECUTION_FAILED.
• A workflow whose "Available in MCP" setting is off answers WORKFLOW_NOT_EXPOSED; exposeToMcp: true turns the setting on and retries once. That is a visible, persistent change — ask the user first, and note that enabling it is itself a workflow update, so it can overwrite a concurrent UI edit.

Successful and routed responses state method and backend (public-api or official-mcp); an envelope rejected on argument validation may carry neither.

See WORKFLOW_GUIDE.md for runnable examples of each method.

Version History

n8n_workflow_versions reads two independent histories, selected with source:

• source: "local" (default) — the snapshots n8n-mcp takes before it changes a workflow. Any n8n version, no token, ids are numbers. Blind to edits made in the n8n UI. The only source that supports delete and prune.
• source: "native" — n8n's own workflow history, the same list the UI shows, including edits made by people. Needs N8N_MCP_ACCESS_TOKEN (n8n 2.34+; the native diff needs 2.36, where get_workflow_versions_diff shipped) and the workflow's "Available in MCP" setting; ids are opaque strings; list is capped at 50 with an offset; delete and prune are refused with MODE_NOT_SUPPORTED_FOR_SOURCE (n8n owns that retention). Native rollback is not pre-validated — validateBefore is accepted and ignored.

mode: "diff" compares two versions (versionId + toVersionId, both from the same source and workflow). A local diff (data.format: "n8n-mcp") reports added/removed/modified nodes as node IDs; a native diff (data.format: "n8n") is n8n's own payload with field-level before/after values. Branch on data.format rather than assuming field names.

Native modes hit the same consent gate as the routed run methods: a workflow whose "Available in MCP" setting is off answers WORKFLOW_NOT_EXPOSED, and re-running with exposeToMcp: true turns that setting on and retries once (the response then carries exposedToMcp: true). It is a visible, persistent change to the workflow — ask the user before passing it. timeoutMs (5000-600000) is the client deadline for the native call.

See WORKFLOW_GUIDE.md for every mode with runnable examples of both sources.

Data Table Management

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.

Column actions — addColumn, deleteColumn, renameColumn — change an existing table's columns, which the Public API cannot do; they run through n8n's MCP server and need N8N_MCP_ACCESS_TOKEN (n8n 2.34+). addColumn takes column: {name, type} (name starts with a letter, letters/digits/underscores only, at most 63 chars; type is string, number, boolean or date); deleteColumn/renameColumn take the columnId from getTable, and renameColumn puts the new column name in name. They address the table by project: projectId is resolved automatically when exactly one project is accessible, otherwise the call returns PROJECT_REQUIRED and lists the candidates — pass projectId (from n8n_list_catalog({kind: "projects"})) to skip resolution. Renaming the table is not a column action: use updateTable on the Public API.

deleteColumn drops the column's values along with the column, and there is no undo. That bites hardest where you'd least expect it: a column's type cannot be changed after creation, so "make this column a number" really means drop-and-re-add, which throws away everything in it. Read the values out with getRows first if they matter, and confirm with the user before dropping a populated column.

See OPERATIONS_GUIDE.md for all actions, filter conditions, and examples.

Workflow Folders

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