Workflow Management Tools

Create, update, and manage n8n workflows directly from your AI assistant. These tools connect to your n8n instance and require API credentials.

Setup Required

To use these tools, you need to connect your n8n instance:

1.Go to your n8n-mcp dashboard
2.Navigate to Instances, then add your instance URL and API key

You can generate an API key in your n8n instance under Settings → API. Some features — n8n Agents, running workflows without an HTTP trigger, native version history, data-table column changes — additionally use an instance-level MCP access token (n8n 2.34+, Settings → Instance-level MCP).

Available Tools

`n8n_create_workflow`

Create a new workflow in your n8n instance. Workflows are always created in an inactive state, allowing you to configure credentials before activation.

n8n API Key Required

Parameter	Type	Default	Description
`name`*	`string`	—	Workflow name
`nodes`*	`array`	—	Array of node objects with id, name, type, typeVersion, position, and parameters
`connections`*	`object`	—	Node connections object
`settings`	`object`	—	Workflow settings (timezone, error handling, etc.)
`nodeGroups`	`array`	—	Canvas groups (n8n 2.28+): [{name, nodeIds, description?}]. Members must form a connected run with no trigger among them. Dropped with a warning on older n8n.
`projectId`	`string`	—	Project to create the workflow in (enterprise). Defaults to the personal project.
`parentFolderId`	`string`	—	Folder to place the workflow in (n8n 2.32+; rejected with a 400 on older instances). Omit for the project root. Create folders with n8n_manage_folders.

Basic webhook to Slack workflow

javascript

n8n_create_workflow({
  name: "Webhook to Slack",
  nodes: [
    {
      id: "webhook_1",
      name: "Webhook",
      type: "n8n-nodes-base.webhook",
      typeVersion: 1,
      position: [250, 300],
      parameters: {
        httpMethod: "POST",
        path: "slack-notify"
      }
    },
    {
      id: "slack_1",
      name: "Slack",
      type: "n8n-nodes-base.slack",
      typeVersion: 1,
      position: [450, 300],
      parameters: {
        resource: "message",
        operation: "post",
        channel: "#general",
        text: "={{$json.message}}"
      }
    }
  ],
  connections: {
    "webhook_1": {
      "main": [[{node: "slack_1", type: "main", index: 0}]]
    }
  }
})

Use Cases

•Creating new automation workflows
•Deploying workflows programmatically
•Setting up integrations via API

✓Best Practices

•Validate with validate_workflow first
•Use unique node IDs
•Position nodes for readability (typically 200px apart)
•Test with n8n_test_workflow after creation
•Use n8n_get_workflow if you need to verify the created workflow structure

Common Pitfalls

•Workflows are created INACTIVE - must activate separately
•Node IDs must be unique within workflow
•Credentials must be configured separately in n8n UI
•Node type names must include package prefix

`n8n_get_workflow`

Retrieve a workflow from your n8n instance. n8n keeps a draft (what you see in the editor) and an active version (the published graph that actually runs) — the workflow body is the draft, and mode="active" returns the published graph. Six modes control response size.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID
`mode`	`string`	`full`	Detail level. "active" returns the published graph; every other mode reads the draft. `fulldetailsactivestructurefilteredminimal`
`nodeNames`	`array`	—	Required when mode="filtered". Node names or node IDs to return with full config. Discover names cheaply with mode="structure" first.

Get the draft workflow

javascript

n8n_get_workflow({id: "abc123"})

Get the published (running) graph

javascript

n8n_get_workflow({id: "abc123", mode: "active"})

Use this to reason about what is actually running in production, not what is being edited. Diff against mode="full" to see unpublished changes.

Read one heavy node without the whole workflow

javascript

n8n_get_workflow({
  id: "abc123",
  mode: "filtered",
  nodeNames: ["Process Data"]
})

Pulls the full config of just these nodes — the way to read a long Code node on a large workflow that would otherwise be truncated

Get workflow with execution stats

javascript

n8n_get_workflow({id: "abc123", mode: "details"})

Quick metadata check

javascript

n8n_get_workflow({id: "abc123", mode: "minimal"})

Use Cases

•View and edit the draft (mode=full)
•Inspect what is actually running in production (mode=active)
•Diff draft vs published before promoting (mode=full + mode=active)
•Read a single heavy node such as a long Code body (mode=filtered)
•Analyze workflow performance (mode=details)
•Clone or compare workflow structure (mode=structure)
•List workflows with status (mode=minimal)

✓Best Practices

•Use mode="minimal" when you only need metadata
•Use mode="structure" for topology analysis, then mode="filtered" to read a specific heavy node
•Use mode="active" when the question is "what is running right now?"
•Use mode="details" for debugging execution issues

Common Pitfalls

•mode="full" no longer carries the nested activeVersion payload — use mode="active" if you previously read it from there
•mode="active" returns code NO_ACTIVE_VERSION for workflows that were never published
•mode="filtered" matches each entry against node name OR node id, so returnedCount can exceed nodeNames.length when names collide — disambiguate by the id on each returned node
•Older n8n versions have no draft/publish split; mode="active" falls back to workflow.nodes when the workflow is active
•Credentials are referenced by ID but their values are never included

`n8n_update_full_workflow`

Complete workflow replacement. Any nodes or connections not included will be removed.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID to update
`name`	`string`	—	New workflow name
`nodes`	`array`	—	Complete array of nodes
`connections`	`object`	—	Complete connections object
`settings`	`object`	—	Workflow settings
`nodeGroups`	`array`	—	Canvas groups (n8n 2.28+): [{name, nodeIds, description?}]. Omit to keep existing groups; pass [] to ungroup everything. Groups whose members a nodes[] update deleted are pruned automatically.
`intent`	`string`	—	Description of the change

Rename only

javascript

n8n_update_full_workflow({
  id: "abc",
  name: "New Name"
})

Full structure update

javascript

n8n_update_full_workflow({
  id: "xyz",
  intent: "Add error handling nodes",
  nodes: [...],
  connections: {...}
})

Use Cases

•Major workflow restructuring
•Complete workflow replacement
•Renaming workflows

✓Best Practices

•Always include intent parameter for better responses
•Get workflow first, modify, then update
•Validate with validate_workflow before updating
•Use n8n_update_partial_workflow for small changes
•Use n8n_get_workflow with mode='structure' if you need to verify the update

`n8n_update_partial_workflow`

Update workflow incrementally with diff operations. Supports 21 operation types for precise modifications, including patchNodeField for surgical string edits inside Code nodes. Operations are validated and applied atomically by default.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID
`operations`*	`array`	—	Array of diff operations. Nodes — addNode, removeNode, updateNode, patchNodeField, moveNode, enableNode, disableNode. Connections — addConnection, removeConnection, rewireConnection, cleanStaleConnections, replaceConnections. Metadata — updateSettings, updateName, setNodeGroups, addTag, removeTag. Activation — activateWorkflow, deactivateWorkflow. Placement — transferWorkflow, moveToFolder.
`validateOnly`	`boolean`	`false`	Only validate without applying
`continueOnError`	`boolean`	`false`	Best-effort mode
`intent`	`string`	—	Description of the change

Add a node and connect it

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "Add HTTP request for API call",
  operations: [
    {type: "addNode", node: {
      name: "HTTP Request",
      type: "n8n-nodes-base.httpRequest",
      position: [400, 300],
      parameters: {url: "https://api.example.com"}
    }},
    {type: "addConnection", source: "Webhook", target: "HTTP Request"}
  ]
})

Update node parameter

javascript

n8n_update_partial_workflow({
  id: "abc",
  intent: "Fix API URL",
  operations: [{
    type: "updateNode",
    nodeName: "HTTP Request",
    updates: {"parameters.url": "https://new-api.example.com"}
  }]
})

AI Agent connections

javascript

n8n_update_partial_workflow({
  id: "ai_wf",
  intent: "Set up AI Agent with tools",
  operations: [
    {type: "addConnection", source: "OpenAI", target: "AI Agent", sourceOutput: "ai_languageModel"},
    {type: "addConnection", source: "HTTP Tool", target: "AI Agent", sourceOutput: "ai_tool"},
    {type: "addConnection", source: "Memory", target: "AI Agent", sourceOutput: "ai_memory"}
  ]
})

Surgical Code node edit (patchNodeField)

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "Bump retry limit in Code node from 3 to 5",
  operations: [{
    type: "patchNodeField",
    nodeName: "Process Items",
    fieldPath: "parameters.jsCode",
    patches: [{
      find: "const MAX_RETRIES = 3;",
      replace: "const MAX_RETRIES = 5;"
    }]
  }]
})

Edits a specific string inside a long Code node body without re-sending the whole script. Strict: errors if the find string is missing, and errors on multiple matches unless replaceAll is set.

Replace every occurrence, or match by regex

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "Point the Code node at the new API domain",
  operations: [{
    type: "patchNodeField",
    nodeName: "Process Items",
    fieldPath: "parameters.jsCode",
    patches: [
      {find: "api.old.com", replace: "api.new.com", replaceAll: true},
      {find: "const\\s+limit\\s*=\\s*\\d+", replace: "const limit = 100", regex: true}
    ]
  }]
})

Patches apply sequentially. Escape regex metacharacters when regex: true and you want a literal match.

Remove a property with null

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "Migrate deprecated continueOnFail to onError",
  operations: [{
    type: "updateNode",
    nodeName: "HTTP Request",
    updates: {
      continueOnFail: null,
      onError: "continueErrorOutput"
    }
  }]
})

Setting a value to null removes the property. Required here because continueOnFail and onError are mutually exclusive — setting only the new one fails validation.

Move a workflow into a folder

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "File this workflow under Production",
  operations: [{
    type: "moveToFolder",
    parentFolderId: "abc123"
  }]
})

Pass null for parentFolderId to move it back to the project root. Requires n8n 2.32+; create folders with n8n_manage_folders.

IF node with semantic branch

javascript

n8n_update_partial_workflow({
  id: "wf_123",
  intent: "Wire IF node outputs",
  operations: [
    {type: "addConnection", source: "If Premium User", target: "Send VIP Email", branch: "true"},
    {type: "addConnection", source: "If Premium User", target: "Send Standard Email", branch: "false"}
  ]
})

Use Cases

•Incremental workflow updates
•Adding/removing individual nodes
•Rewiring connections
•Setting up AI Agent workflows
•Surgical edits to Code node bodies and email templates (patchNodeField)
•Removing deprecated properties during node version migrations (updates: {prop: null})
•Managing canvas groups (setNodeGroups, n8n 2.28+)
•Transferring workflows between team projects (transferWorkflow, enterprise/cloud)
•Filing a workflow into a folder (moveToFolder, n8n 2.32+)

✓Best Practices

•Always include intent parameter with specific description
•Use patchNodeField (not full updateNode) for small string edits inside Code nodes
•Prefer patchNodeField over the older __patch_find_replace form — it errors on not-found and detects ambiguous matches instead of warning
•Use rewireConnection instead of remove+add for changing targets
•Use branch="true"/"false" for IF nodes and case=N for Switch nodes (avoids manual sourceIndex math)
•Rename nodes with updateNode — all connection references update automatically, no manual rewiring needed
•Use cleanStaleConnections after renaming/removing nodes
•Validate with validateOnly first for complex changes
•Use n8n_get_workflow with mode='structure' if you need to verify applied operations

Common Pitfalls

•For IF nodes ALWAYS use branch="true"/"false" — reusing sourceIndex=0 for multiple connections puts them all on the TRUE branch and silently breaks your logic
•For Switch nodes ALWAYS use case=N — the same sourceIndex for multiple connections lands them on one output
•Explicit sourceIndex overrides the smart branch/case parameters if both are given
•Over MCP always use null (not undefined) to remove a property — undefined is dropped by JSON serialization and becomes a silent no-op
•setNodeGroups is a full replacement: pass every group you want to keep, or [] to ungroup everything
•n8n validates canvas groups on every write, so groups may be auto-pruned by unrelated edits — check details.warnings
•continueOnError breaks the atomic guarantee — valid operations apply even if others fail
•replaceConnections overwrites the entire connections object; cleanStaleConnections removes all broken connections and cannot be selective
•Array elements are addressed by index, and out-of-range indices are rejected — new elements cannot be appended this way

`n8n_delete_workflow`

Permanently delete a workflow including all associated data and execution history. This action cannot be undone.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID to delete

Delete a workflow

javascript

n8n_delete_workflow({id: "abc123"})

Use Cases

•Removing obsolete workflows
•Cleanup after testing
•Managing workflow lifecycle

✓Best Practices

•Always confirm before deleting
•Consider exporting workflow first for backup
•Deactivate workflow before deletion

Common Pitfalls

•Cannot be undone - permanent deletion
•Deletes all execution history
•Active workflows can be deleted
•No built-in confirmation

`n8n_list_workflows`

List workflows from n8n with filtering options. Returns only minimal metadata (id, name, active, dates, tags).

n8n API Key Required

Parameter	Type	Default	Description
`limit`	`number`	`100`	Results per page (max: 100)
`cursor`	`string`	—	Pagination cursor
`active`	`boolean`	—	Filter by active/inactive
`tags`	`array`	—	Filter by exact tag matches
`projectId`	`string`	—	Filter by project (enterprise)
`excludePinnedData`	`boolean`	`true`	Exclude pinned data from the response

First 20 workflows

javascript

n8n_list_workflows({limit: 20})

Active production workflows

javascript

n8n_list_workflows({active: true, tags: ["production"]})

Use Cases

•Listing all workflows in an instance
•Finding active workflows
•Filtering by tags for organization
•Pagination through large workflow sets

✓Best Practices

•Use tags to organize workflows
•Always check the hasMore flag, then page with nextCursor until it is false
•Filter by active=true to find running workflows

Common Pitfalls

•Maximum 100 workflows per request, and the server may return fewer than requested
•The returned field counts the current page only — it is not the instance total
•Returns no nodes or connections; use n8n_get_workflow for structure

`n8n_validate_workflow`

Validate a workflow from your n8n instance by ID. Fetches a workflow from n8n and runs comprehensive validation.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID to validate
`options`	`object`	—	Validation options (same as validate_workflow)

Default validation

javascript

n8n_validate_workflow({id: "wf_abc123"})

Strict validation

javascript

n8n_validate_workflow({
  id: "wf_abc123",
  options: {profile: "strict"}
})

Use Cases

•Validating workflows before running them in production
•Checking imported workflows for compatibility
•Debugging workflow execution failures
•Pre-deployment validation in CI/CD pipelines

✓Best Practices

•Validate before activating workflows
•Use strict profile for production workflows
•Check warnings even if validation passes

`n8n_autofix_workflow`

Automatically fix common workflow validation errors including expression formats, typeVersions, error outputs, webhook paths, and node type corrections.

n8n API Key Required

Parameter	Type	Default	Description
`id`*	`string`	—	Workflow ID to fix
`applyFixes`	`boolean`	`false`	Apply fixes (false = preview)
`fixTypes`	`array`	`all`	Types of fixes to apply `expression-formattypeversion-correctionerror-output-confignode-type-correctionwebhook-missing-pathtypeversion-upgradeversion-migration`
`confidenceThreshold`	`string`	`medium`	Minimum confidence `highmediumlow`
`maxFixes`	`number`	`50`	Maximum fixes to apply

Preview all fixes

javascript

n8n_autofix_workflow({id: "wf_abc123"})

Apply all medium+ confidence fixes

javascript

n8n_autofix_workflow({id: "wf_abc123", applyFixes: true})

Only high-confidence fixes

javascript

n8n_autofix_workflow({
  id: "wf_abc123",
  applyFixes: true,
  confidenceThreshold: "high"
})

Use Cases

•Fixing expression format issues
•Upgrading node versions
•Fixing configuration errors
•Migrating workflows to newer n8n versions

✓Best Practices

•Always preview fixes first (applyFixes: false)
•Start with high confidence threshold for production
•Review the fix summary to understand what changed
•Test workflows after auto-fixing

`n8n_test_workflow`

Run a workflow. method: "auto" (default) triggers it over HTTP through its webhook, form, or chat trigger. Workflows without such a trigger can run through n8n's instance-level MCP server instead: "prepare" lists the nodes that need pinned data, "pinned" runs the workflow with that data standing in for triggers and external calls, and "direct" starts a real run. The MCP-server methods need N8N_MCP_ACCESS_TOKEN (n8n 2.34+) and the workflow's "Available in MCP" setting.

n8n API Key Required

Instance-level MCP Token Optional

Parameter	Type	Default	Description
`workflowId`*	`string`	—	Workflow ID to execute
`method`	`string`	`auto`	How to run it. auto/trigger: over HTTP via the workflow's webhook/form/chat trigger (auto never runs through n8n's MCP server). prepare: read-only, lists the nodes that need pinned data. pinned: run with pinData through n8n's MCP server and wait. direct: start a run through n8n's MCP server with optional inputs. `autotriggerpreparepinneddirect`
`triggerType`	`string`	—	Trigger type for the HTTP path. Auto-detected if not specified. `webhookformchat`
`httpMethod`	`string`	`POST`	For webhook: HTTP method `GETPOSTPUTDELETE`
`webhookPath`	`string`	—	Override webhook path
`message`	`string`	—	For chat: message to send. For method=direct: forwarded to the trigger as input.
`sessionId`	`string`	—	For chat: session ID
`data`	`object`	—	Input data/payload for webhook, form fields, or execution input
`headers`	`object`	—	Custom HTTP headers
`timeout`	`number`	`120000`	Timeout in ms — HTTP trigger path only (method auto/trigger). The MCP-server methods use timeoutMs instead.
`waitForResponse`	`boolean`	`true`	Wait for completion
`pinData`	`object`	—	For method=pinned (required, non-empty): pinned trigger data keyed by node name. Each value is an array of items, each wrapped as {json: {...}} — e.g. {"Webhook": [{"json": {"id": "123"}}]}, never a flat object. Build it from method=prepare.
`triggerNodeName`	`string`	—	For method=pinned/direct: which trigger node to start from. Defaults to the detected trigger; n8n requires it whenever inputs are given.
`executionMode`	`string`	`manual`	For method=direct: "production" runs through the production execution path and is recorded as a production run. Both modes execute nodes for real — this only changes the execution context. Never chosen implicitly. `manualproduction`
`exposeToMcp`	`boolean`	—	For the MCP-server methods: when n8n refuses with WORKFLOW_NOT_EXPOSED, enable the workflow's persistent "Available in MCP" setting and retry once. A visible workflow setting — confirm before passing it.
`timeoutMs`	`number`	—	Client-side deadline for the MCP-server methods, 5000-600000 ms (default 30000 for prepare, 300000 for pinned/direct)

Auto-detect and trigger

javascript

n8n_test_workflow({workflowId: "123"})

Webhook with data

javascript

n8n_test_workflow({
  workflowId: "123",
  triggerType: "webhook",
  data: {name: "John", email: "john@example.com"}
})

Chat trigger

javascript

n8n_test_workflow({
  workflowId: "123",
  triggerType: "chat",
  message: "Hello AI assistant"
})

Run a workflow with no HTTP trigger

javascript

// 1. See which nodes need pinned data
n8n_test_workflow({workflowId: "123", method: "prepare"});

// 2. Run with pinned trigger data
n8n_test_workflow({
  workflowId: "123",
  method: "pinned",
  pinData: {"Webhook": [{"json": {"name": "John"}}]}
});

Schedule/manual workflows run through n8n's MCP server — pinData stands in for triggers, credentialed nodes, and HTTP Request nodes

Start a live run through n8n's MCP server

javascript

n8n_test_workflow({
  workflowId: "123",
  method: "direct",
  message: "Hello"
})

Returns once the run has started — poll n8n_executions for the result. Every node runs for real.

Use Cases

•Testing workflows during development
•Triggering workflows programmatically
•Testing chat/AI workflows
•Validating webhook integrations
•Running workflows with no HTTP trigger (schedule, manual, sub-workflow) via method=pinned or direct
•Exercising a workflow with pinned data instead of live external calls

✓Best Practices

•Use auto-detect for most cases
•Include test data matching expected input format
•Test with different input scenarios
•Run method=prepare before method=pinned so pinData matches the nodes n8n expects
•Keep method=direct on executionMode manual unless a production run is genuinely wanted
•Confirm before passing exposeToMcp: true — it flips a visible, persistent workflow setting

Common Pitfalls

•Workflow must be ACTIVE to be triggered over HTTP
•method=auto never falls through to n8n's MCP server — without an HTTP trigger it reports the workflow cannot be triggered and names the alternatives
•Both pinned and direct cause real side effects: direct runs every node; pinned pins only triggers, credentialed nodes, and HTTP Request nodes — Code, Set, and credential-free I/O still run
•method=direct reports success when the run starts, regardless of how it ends — check n8n_executions
•The MCP-server methods answer WORKFLOW_NOT_EXPOSED when the workflow's "Available in MCP" setting is off

`n8n_executions`

Unified tool for execution management: get details, list executions, or delete records. mode="error" is the purpose-built debugging path — it extracts the error, samples upstream input, traces the execution path, and suggests fixes at 80-90% fewer tokens than mode="full".

n8n API Key Required

Parameter	Type	Default	Description
`action`*	`string`	—	Action to perform `getlistdelete`
`id`	`string`	—	Execution ID (for get/delete)
`mode`	`string`	`summary`	For get: response detail. "error" is optimized for debugging failures. `previewsummaryfilteredfullerror`
`nodeNames`	`array`	—	For get+filtered: filter by nodes
`itemsLimit`	`number`	`2`	For get+filtered: items per node (0 = structure only, -1 = unlimited)
`includeInputData`	`boolean`	`false`	For get: include input data alongside output
`errorItemsLimit`	`number`	`2`	For get+error: how many upstream items to sample (max: 100)
`includeStackTrace`	`boolean`	`false`	For get+error: include the full stack trace instead of a truncated one
`includeExecutionPath`	`boolean`	`true`	For get+error: include the execution path leading to the error
`fetchWorkflow`	`boolean`	`true`	For get+error: fetch the workflow for accurate upstream detection. Set false to save ~50-100ms when you already know the structure.
`workflowId`	`string`	—	For list: filter by workflow
`status`	`string`	—	For list: filter by status `successerrorwaiting`
`projectId`	`string`	—	For list: filter by project (enterprise)
`includeData`	`boolean`	`false`	For list: include execution data in each entry
`limit`	`number`	`100`	For list: results per page (1-100)
`cursor`	`string`	—	For list: pagination cursor

Debug a failed execution (recommended)

javascript

n8n_executions({action: "get", id: "exec_456", mode: "error"})

Returns the error, the upstream data that caused it, the path taken, and fix suggestions — 80-90% smaller than mode: "full"

Debug with more upstream context

javascript

n8n_executions({
  action: "get",
  id: "exec_456",
  mode: "error",
  errorItemsLimit: 5,
  includeStackTrace: true
})

List recent executions

javascript

n8n_executions({
  action: "list",
  workflowId: "abc123",
  limit: 10
})

Get execution summary

javascript

n8n_executions({action: "get", id: "exec_456"})

Get specific nodes from execution

javascript

n8n_executions({
  action: "get",
  id: "exec_456",
  mode: "filtered",
  nodeNames: ["HTTP Request", "Slack"]
})

Use Cases

•Debugging workflow failures cheaply (mode=error)
•Getting AI-generated fix suggestions for common error patterns
•Inspecting the input data that triggered a failure
•Analyzing execution performance
•Cleaning up execution history
•Monitoring workflow runs

✓Best Practices

•Reach for mode="error" first on any failure — mode="full" is rarely worth its token cost
•Use status="error" to find failed executions
•Use mode="filtered" to focus on specific nodes in large workflows
•Set fetchWorkflow: false if you already know the workflow structure
•Delete old executions to save storage

Common Pitfalls

•mode="full" can return very large responses for complex workflows
•mode="error" fetches the workflow by default, adding ~50-100ms
•Deletion is permanent and cannot be undone

`n8n_workflow_versions`

Workflow version management over two independent histories. source: "local" (default) reads the snapshots n8n-mcp takes before it changes a workflow — any n8n version, scoped to your own credentials, pruned automatically (10 most recent per workflow plus an age window). source: "native" reads n8n's own workflow history — the same list the n8n UI shows, including edits people made in the UI — through n8n's instance-level MCP server (needs N8N_MCP_ACCESS_TOKEN and the workflow's "Available in MCP" setting). List, inspect, diff, roll back, and clean up.

n8n API Key Required

Instance-level MCP Token Optional

Parameter	Type	Default	Description
`mode`*	`string`	—	Operation mode. delete and prune are local-only (n8n owns native retention). `listgetrollbackdiffdeleteprune`
`source`	`string`	`local`	Which history to read: "local" (n8n-mcp snapshots) or "native" (n8n's own version history, including UI edits by people) `localnative`
`workflowId`	`string`	—	Workflow ID (required for list, rollback, diff, delete, and prune; required for every native mode)
`versionId`	`string \| number`	—	Version ID. Local: numeric snapshot id. Native: n8n's opaque version id string. Required for get and diff, for a single delete, and for native rollback; optional for local rollback.
`toVersionId`	`string \| number`	—	The second version to compare against in diff mode (same id format as versionId)
`limit`	`number`	`10`	Max versions to return in list mode (native: capped at 50)
`offset`	`number`	—	Skip this many versions in native list mode
`validateBefore`	`boolean`	`true`	Validate before rollback (local only — accepted and ignored for native, whose version payload lacks the fields the validator needs)
`deleteAll`	`boolean`	`false`	Delete all versions (delete mode, local only)
`maxVersions`	`number`	`10`	Versions to keep (prune mode, local only)
`exposeToMcp`	`boolean`	—	Native only: on a WORKFLOW_NOT_EXPOSED refusal, enable the workflow's "Available in MCP" setting and retry once. A visible, persistent workflow setting — confirm before passing it.
`timeoutMs`	`number`	`30000`	Client deadline for the native call (5000-600000 ms)

List version history

javascript

n8n_workflow_versions({mode: "list", workflowId: "abc123", limit: 5})

Rollback to latest saved version

javascript

n8n_workflow_versions({mode: "rollback", workflowId: "abc123"})

Compare two local snapshots

javascript

n8n_workflow_versions({
  mode: "diff",
  workflowId: "abc123",
  versionId: 41,
  toVersionId: 42
})

Read a diff before a rollback so you know what the restore will change

List n8n's own history, including UI edits

javascript

n8n_workflow_versions({
  mode: "list",
  source: "native",
  workflowId: "abc123",
  limit: 20
})

Needs N8N_MCP_ACCESS_TOKEN and the workflow's "Available in MCP" setting

Prune to keep only 5 most recent

javascript

n8n_workflow_versions({mode: "prune", workflowId: "abc123", maxVersions: 5})

Use Cases

•Recovering from an accidental or broken workflow change
•Viewing workflow history and maintaining an audit trail
•Comparing two versions before rolling back
•Auditing edits people made in the n8n UI (source: "native")
•Managing version storage

✓Best Practices

•Always list versions before rollback to pick the right one
•Use source: "native" when the workflow is also edited in the n8n UI — local snapshots miss those edits
•Read a diff before a rollback so you know what the restore will change
•Enable validateBefore for local rollback to catch structural issues first
•Use prune regularly to keep version history manageable
•Note why you rolled back — the version log is your audit trail

Common Pitfalls

•Rollback overwrites the current workflow, though a backup is created automatically first
•Deleted versions cannot be recovered
•Local and native are different id spaces — a native id will not resolve locally, and vice versa
•Native rollback is never pre-validated; n8n's version payload lacks the fields the validator needs
•Native delete and prune are refused with MODE_NOT_SUPPORTED_FOR_SOURCE — n8n owns that retention
•Diff payloads differ by source — branch on data.format, not on assumed field names
•Versions are scoped to your instance and credentials — versions from other instances are not visible

`n8n_deploy_template`

Deploy a workflow template from n8n.io directly to your n8n instance with auto-fixing of common issues.

n8n API Key Required

Parameter	Type	Default	Description
`templateId`*	`number`	—	Template ID from n8n.io
`name`	`string`	—	Custom workflow name
`autoUpgradeVersions`	`boolean`	`true`	Upgrade node typeVersions
`autoFix`	`boolean`	`true`	Auto-fix expression issues
`stripCredentials`	`boolean`	`true`	Remove credential references

Deploy with default settings

javascript

n8n_deploy_template({templateId: 2776})

Deploy with custom name

javascript

n8n_deploy_template({
  templateId: 2776,
  name: "My Google Drive to Airtable Sync"
})

Use Cases

•Quickly deploying popular templates
•Setting up common integrations
•Using templates as starting points

✓Best Practices

•Use search_templates to find template IDs
•Review required credentials in the response
•Configure credentials in n8n UI before activating
•Test workflow before connecting to production

`n8n_manage_datatable`

Unified tool for managing n8n data tables, rows, and columns. Supports table CRUD, row CRUD with filtering and pagination, upsert, dry-run previews, and column changes on an existing table (addColumn/deleteColumn/renameColumn — routed through n8n's instance-level MCP server because the public API cannot change columns after creation; they need N8N_MCP_ACCESS_TOKEN and n8n 2.34+).

n8n API Key Required

Instance-level MCP Token Optional

Parameter	Type	Default	Description
`action`*	`string`	—	Operation to perform. The column actions need N8N_MCP_ACCESS_TOKEN. `createTablelistTablesgetTableupdateTabledeleteTablegetRowsinsertRowsupdateRowsupsertRowsdeleteRowsaddColumndeleteColumnrenameColumn`
`tableId`	`string`	—	Required for all row actions and table get/update/delete
`name`	`string`	—	Table name (createTable / updateTable) or the new column name (renameColumn)
`columns`	`array`	—	Column definitions — each {name, type} where type is one of string\|number\|boolean\|date. Required for createTable (at least one).
`data`	`object`	—	Row payload (insertRows: array of rows; updateRows/upsertRows: object of column→value)
`filter`	`object`	—	{type?: 'and'\|'or', filters: [{columnName, condition, value}]} — conditions: eq, neq, like, ilike, gt, gte, lt, lte. Combinator defaults to 'and'.
`limit`	`number`	—	Max results for listTables/getRows (1-100)
`cursor`	`string`	—	Pagination cursor for listTables/getRows
`sortBy`	`string`	—	For getRows: "columnName:asc" or "columnName:desc". Use it for deterministic ordering.
`search`	`string`	—	For getRows: full-text search across string columns
`returnType`	`string`	`count`	For insertRows: how much to return `countidall`
`returnData`	`boolean`	`false`	For updateRows/upsertRows/deleteRows: return the affected rows
`dryRun`	`boolean`	`false`	For updateRows/upsertRows/deleteRows: preview changes without writing (recommended before bulk operations)
`column`	`object`	—	For addColumn: {name, type}. Name must start with a letter, contain only letters, digits, and underscores, and be at most 63 characters; type is string, number, boolean, or date.
`columnId`	`string`	—	For deleteColumn/renameColumn: ID of the column — read it from getTable first
`projectId`	`string`	—	For createTable: project to create the table in. For the column actions: the project owning the table — auto-resolved when exactly one project is accessible, otherwise the call returns PROJECT_REQUIRED and lists candidates. Find IDs with n8n_list_catalog({kind: "projects"}).
`timeoutMs`	`number`	`30000`	For the column actions: client timeout in ms (5000-600000)

Create a table

javascript

n8n_manage_datatable({
  action: "createTable",
  name: "Contacts",
  columns: [
    {name: "email", type: "string"},
    {name: "score", type: "number"}
  ]
})

Get rows with filter

javascript

n8n_manage_datatable({
  action: "getRows",
  tableId: "dt-123",
  filter: {filters: [{columnName: "status", condition: "eq", value: "active"}]},
  limit: 50
})

Bulk update with dry-run preview

javascript

n8n_manage_datatable({
  action: "updateRows",
  tableId: "dt-123",
  filter: {filters: [{columnName: "score", condition: "lt", value: 5}]},
  data: {status: "inactive"},
  dryRun: true
})

Upsert by email

javascript

n8n_manage_datatable({
  action: "upsertRows",
  tableId: "dt-123",
  filter: {filters: [{columnName: "email", condition: "eq", value: "a@b.com"}]},
  data: {score: 15}
})

Search and sort rows

javascript

n8n_manage_datatable({
  action: "getRows",
  tableId: "dt-123",
  search: "john",
  sortBy: "name:asc"
})

Full-text search across string columns, with deterministic ordering

Add a column to an existing table

javascript

n8n_manage_datatable({
  action: "addColumn",
  tableId: "dt-123",
  column: {name: "score", type: "number"}
})

Routed through n8n's MCP server — needs N8N_MCP_ACCESS_TOKEN and n8n 2.34+

Rename a column

javascript

n8n_manage_datatable({
  action: "renameColumn",
  tableId: "dt-123",
  columnId: "col-7",
  name: "total_score"
})

Read the columnId from getTable first. Renaming the table itself is updateTable, not a column action.

Use Cases

•Storing workflow state across executions
•Building lookup tables for routing/enrichment
•Managing user/contact records used by multiple workflows
•Bulk-updating records based on filter criteria
•Adjusting a table schema after creation — add, rename, or drop a column

✓Best Practices

•Always run dryRun: true before bulk updateRows/deleteRows to verify the filter
•Define column types upfront — a column's type cannot be changed after creation
•Use returnType: 'count' (default) for insertRows to keep responses small
•Read columnId from getTable before deleteColumn or renameColumn
•Pass projectId for column actions on instances with several projects

Common Pitfalls

•deleteRows requires a filter — there is no 'delete all' shortcut
•Filter conditions are case-sensitive for eq/neq; use ilike for case-insensitive matching
•Date values should be ISO 8601 strings
•createTable requires at least one column; a column's type can never be changed — drop and re-add the column instead
•deleteColumn drops the column's values along with the column, with no undo — read them out with getRows first if they matter
•The column actions return NOT_CONFIGURED without N8N_MCP_ACCESS_TOKEN, and OFFICIAL_MCP_TOOL_UNAVAILABLE on n8n below 2.34
•deleteTable permanently removes the table and all its rows

`n8n_manage_credentials`

Unified tool for managing n8n credentials. Full CRUD, schema discovery for any credential type, and reverse-lookup of which workflows reference each credential. Secrets are never returned in responses.

n8n API Key Required

Parameter	Type	Default	Description
`action`*	`string`	—	Operation to perform `listgetcreateupdatedeletegetSchema`
`id`	`string`	—	Credential ID (required for get/update/delete)
`name`	`string`	—	Credential display name (create/update)
`type`	`string`	—	Credential type slug (e.g., 'slackApi', 'httpHeaderAuth') — required for create and getSchema
`data`	`object`	—	Secret values for create/update. Stripped from responses.
`includeUsage`	`boolean`	`false`	On list/get: reverse-scan workflows and attach usedIn[{id, name, active}] and usageCount to each credential. On list, scans every page (up to 5,000 credentials) and ignores cursor/limit.
`cursor`	`string`	—	For list: pagination cursor from a previous response's nextCursor. Ignored when includeUsage is true.
`limit`	`number`	`100`	For list: credentials per page (1-100). Ignored when includeUsage is true.

Discover required fields for a type

javascript

n8n_manage_credentials({action: "getSchema", type: "httpHeaderAuth"})

Create a credential

javascript

n8n_manage_credentials({
  action: "create",
  name: "My Slack Token",
  type: "slackApi",
  data: {accessToken: "xoxb-..."}
})

Pre-deletion safety check

javascript

n8n_manage_credentials({action: "get", id: "cred-123", includeUsage: true})

Returns usedIn[] so you can see which workflows break if you delete the credential

Audit credential usage across the instance

javascript

n8n_manage_credentials({action: "list", includeUsage: true})

Use Cases

•Provisioning credentials for new integrations
•Rotating secrets and seeing which workflows are affected
•Auditing shared/over-privileged credentials
•Cleaning up unused credentials safely

✓Best Practices

•Call getSchema first when creating a credential of an unfamiliar type
•Use includeUsage: true before delete or rotation to see impact
•Verify creation with a follow-up list — n8n strips data on response by design

Common Pitfalls

•data field is stripped from get/create/update responses (defense-in-depth) — record the secret yourself before calling
•includeUsage triggers a full workflow scan client-side — slower on large instances (capped at 5,000 workflows)
•A 'no usages' result does not guarantee unused — verify before destructive actions
•Credential type slugs are case-sensitive and must match exactly — use getSchema to confirm
•OAuth2 credentials may need a browser-based authorization flow that cannot be completed via API alone
•delete is permanent, and workflows referencing the credential will break

`n8n_manage_folders`

Manage workflow folders (n8n 2.19+): create, list, get, rename, move, and delete. Note the split — this tool shapes the folder tree, but putting a workflow into a folder happens in the workflow tools (parentFolderId on n8n_create_workflow, the moveToFolder diff operation on n8n_update_partial_workflow).

n8n API Key Required

Parameter	Type	Default	Description
`action`*	`string`	—	Operation to perform `createlistgetrenamemovedelete`
`projectId`	`string`	`personal`	Project containing the folder(s). On enterprise instances pass an explicit ID rather than relying on the default.
`folderId`	`string`	—	Folder ID (required for get, rename, move, and delete)
`name`	`string`	—	For create: the folder name (required). For rename: the new name (required).
`parentFolderId`	`string \| null`	—	For create: parent folder to nest under. For move: the target parent, or null to move to the project root (required). For list: return only direct children of this folder.
`transferToFolderId`	`string`	—	For delete: folder that receives the contents ('0' = project root). Omitting it archives the folder's workflows.
`nameFilter`	`string`	—	For list: name contains-match filter
`sortBy`	`string`	`updatedAt:desc`	For list: sort order `name:ascname:desccreatedAt:asccreatedAt:descupdatedAt:ascupdatedAt:desc`
`skip`	`number`	`0`	For list: pagination offset
`take`	`number`	`50`	For list: page size (max 100)

Create a folder

javascript

n8n_manage_folders({action: "create", name: "Production"})

Creates at the project root. Pass parentFolderId to nest it under another folder.

List folders with counts and breadcrumbs

javascript

n8n_manage_folders({action: "list"})

Each entry carries workflowCount, subFolderCount, and a path breadcrumb. Do this before creating — folder names are not unique, so duplicates are easy to make by accident.

Move a folder to the project root

javascript

n8n_manage_folders({
  action: "move",
  folderId: "abc123",
  parentFolderId: null
})

Delete a folder without archiving its workflows

javascript

n8n_manage_folders({
  action: "delete",
  folderId: "abc123",
  transferToFolderId: "0"
})

Moves the contents to the project root first. Omit transferToFolderId and the workflows are archived — which deactivates them.

Place a workflow in a folder (n8n 2.32+)

javascript

// At creation
n8n_create_workflow({
  name: "My flow",
  nodes: [...],
  connections: {...},
  parentFolderId: "abc123"
});

// Or move an existing one
n8n_update_partial_workflow({
  id: "wf1",
  operations: [{type: "moveToFolder", parentFolderId: "abc123"}]
});

Placement lives in the workflow tools, not in n8n_manage_folders

Use Cases

•Organizing a grown instance into per-environment or per-team folders
•Setting up folder structure before deploying a batch of related workflows
•Finding empty folders via workflowCount/subFolderCount and cleaning them up
•Restructuring nested folder trees without touching the workflows inside

✓Best Practices

•List first to discover the existing structure — names are not unique, so it is easy to create duplicates
•Prefer delete with transferToFolderId ('0' for the root) unless archiving the contents is genuinely what you want
•On enterprise instances pass explicit projectId values rather than relying on the personal default

Common Pitfalls

•A workflow's folder cannot be read back through the n8n API — never build logic that needs to query folder membership, and note that workflow listings cannot filter by folder
•delete without transferToFolderId archives the folder's workflows, which deactivates them
•Folder names are not unique within a project, or even within the same parent folder
•Folders need a licensed instance: they unlock on the registered free Community tier (Settings → Usage and plan) and up, and your API key needs the folder:* scopes — a key issued before you registered will not have them
•Folder CRUD needs n8n 2.19+; placing workflows into folders needs 2.32+ (parentFolderId is rejected with a 400 on older instances)
•The 'personal' project alias is resolved server-side by n8n only for create — for other actions the tool resolves it itself, so on an empty Community instance with no workflows you must pass an explicit projectId or run create first

`n8n_manage_agents`

Create, configure, validate, run, and publish n8n Agents — persisted assistants with a model, instructions, tools, skills, tasks, memory, and channels — through n8n's instance-level MCP server. Not the AI Agent workflow node (use get_node for that). Requires N8N_MCP_ACCESS_TOKEN (MCP API key from n8n Settings → Instance-level MCP) and n8n 2.34+ with the agents module.

n8n API Key Required

Instance-level MCP Token Required

Parameter	Type	Default	Description
`action`*	`string`	—	Operation to perform. Start with "reference" — it returns the config schema and the exact mutate operations. `referencesearchgetcreatemutatevalidatecallpublishunpublishrevertversionsdeletediscover_assetsverify_mcp_serverupdate_integration`
`args`	`object`	—	Arguments for the action, forwarded to n8n verbatim. create: {projectId, name, config?}. mutate: {agentId, baseConfigHash, operation} — config.patch is RFC 6902 JSON Patch; skill/task/customTool have upsert/delete operations. call: {agentId, request: {type: "message", message, sessionId?} or {type: "approval", approved, continuation}}. discover_assets: {projectId, kind: models\|integrations\|workflows\|subagents\|mcpServers, provider?, ...}.
`timeoutMs`	`number`	`30000 (180000 for call)`	Request timeout, 5000-600000 ms — a top-level parameter, not part of args. On expiry the agent run continues in n8n.

Read the config schema first

javascript

n8n_manage_agents({action: "reference"})

Returns the agent config shape and the exact mutate operations — always the first call

Discover models, then create an agent

javascript

n8n_manage_agents({
  action: "discover_assets",
  args: {projectId: "p1", kind: "models", provider: "openai"}
});

n8n_manage_agents({
  action: "create",
  args: {
    projectId: "p1",
    name: "Support triage",
    config: {model: "openai/gpt-4o-mini", instructions: "..."}
  }
});

Add a skill (one mutate per resource)

javascript

n8n_manage_agents({
  action: "mutate",
  args: {
    agentId: "a1",
    baseConfigHash: "…",  // from the last get/create/mutate response
    operation: {type: "skill.upsert", skill: {name: "triage", instructions: "…"}}
  }
});

Every mutate needs the latest configHash — a stale one comes back as STALE_CONFIG

Test-run the agent

javascript

n8n_manage_agents({
  action: "call",
  args: {agentId: "a1", request: {type: "message", message: "Summarise yesterday's tickets"}},
  timeoutMs: 300000
});

Runs with real credentials and tools. May return approvals[] for a human to decide.

Use Cases

•Building a persisted n8n Agent from a spec
•Adding skills, tasks, and custom tools to an existing agent
•Validating and test-running an agent before publishing
•Inspecting agent versions and reverting
•Connecting integrations and MCP servers to an agent

✓Best Practices

•Always call action: "reference" first — it documents the config shape and mutate operations
•One mutate per resource, re-reading configHash between them
•Validate before call and before publish
•Publish only when explicitly asked — call runs with real credentials and tools
•Never approve an agent's pending approvals[] on someone's behalf

Common Pitfalls

•Needs N8N_MCP_ACCESS_TOKEN (separate from the Public API key) and n8n 2.34+ with the agents module
•A stale baseConfigHash returns STALE_CONFIG — re-read the agent and retry
•timeoutMs belongs at the top level, not inside args
•args are forwarded verbatim — a misspelled field is reported by n8n as INVALID_ARGS
•Custom tools are TypeScript with only @n8n/agents and zod imports; compile failures come back as AGENT_TOOL_ERROR
•On n8n 2.36.x the agents runtime rejects azureOpenAiApi and aws credentials as incompatible

`n8n_list_catalog`

List instance-level catalog entries: projects (with the personal project marked) or tags. These IDs are needed as inputs elsewhere — projectId for n8n_manage_agents and n8n_manage_datatable, tag IDs for workflow filtering. Reads the Public API first; when team projects are not licensed there, falls back to n8n's instance-level MCP server if N8N_MCP_ACCESS_TOKEN is set.

n8n API Key Required

Instance-level MCP Token Optional

Parameter	Type	Default	Description
`kind`*	`string`	—	Which catalog to list `projectstags`
`query`	`string`	—	Case-insensitive substring filter on name
`limit`	`number`	—	Max items to return after filtering (1-500)

List projects

javascript

n8n_list_catalog({kind: "projects"})

The personal project is marked with personal: true — use its id when a projectId is required and no team project applies

Find a tag by name

javascript

n8n_list_catalog({kind: "tags", query: "prod", limit: 20})

Use Cases

•Resolving a projectId before n8n_manage_agents create or n8n_manage_datatable create
•Finding the personal project on an instance without team projects
•Looking up a tag ID by name before filtering workflows

✓Best Practices

•Use personal: true to find the personal project rather than matching on name
•Check teamProjectsEnabled before assuming a returned team project is usable for writes

Common Pitfalls

•GET /projects is Enterprise-licensed on the Public API — unlicensed instances answer 403 (older ones 404), triggering the official-MCP fallback or a personal-project-only result
•tags never falls back — without Public API credentials it returns NOT_CONFIGURED
•On the official-MCP fallback only search_projects is available, so a project the Public API would show but the official server doesn't expose won't appear

`n8n_evaluations`

Run and read evaluation test runs for a workflow: trigger a run, cancel one, list runs, get a run with aggregated metrics, or fetch per-case results. This is how you catch prompt and model regressions in AI workflows before your users do.

n8n API Key Required

Parameter	Type	Default	Description
`action`*	`string`	—	Operation to perform `runcancellist_runsget_runlist_cases`
`workflowId`*	`string`	—	Workflow ID the test runs belong to
`runId`	`string`	—	Test run ID. Required for get_run, list_cases, and cancel.
`status`	`string`	—	For list_runs: filter by run status `newrunningcompletederrorcancelled`
`limit`	`number`	`100 (list_runs) / 20 (list_cases)`	Results per page (1-250)
`cursor`	`string`	—	Pagination cursor from a previous response

Trigger a run, then poll it

javascript

// Cases execute asynchronously — the response only
// confirms the run was created.
const {id} = n8n_evaluations({
  action: "run",
  workflowId: "abc123"
});

// Poll until status is completed / error / cancelled
n8n_evaluations({
  action: "get_run",
  workflowId: "abc123",
  runId: id
});

List completed runs

javascript

n8n_evaluations({
  action: "list_runs",
  workflowId: "abc123",
  status: "completed",
  limit: 10
})

Newest first. Compare metrics across runs to catch prompt or model regressions.

Inspect per-case results

javascript

n8n_evaluations({
  action: "list_cases",
  workflowId: "abc123",
  runId: "run456"
})

Each case carries its executionId — pass it to n8n_executions to inspect the full execution behind a failure

Cancel a run in progress

javascript

n8n_evaluations({
  action: "cancel",
  workflowId: "abc123",
  runId: "run456"
})

Accepted while the run winds down — confirm with get_run that it reached "cancelled"

Use Cases

•Triggering an evaluation run after changing a prompt, then polling it to completion
•Comparing metric aggregates across runs to catch prompt or model regressions
•Pulling per-case failures and inspecting the underlying executions
•Exporting evaluation results to an external dashboard
•Cancelling a long-running evaluation started by mistake

✓Best Practices

•Confirm the workflow has a configured evaluation trigger with a dataset before calling run — a missing trigger is a 409, not a silent no-op
•Poll get_run rather than assuming run completed; cases execute asynchronously
•Filter list_runs by status="completed" when you only need finished results
•Keep list_cases at the default limit of 20 and paginate — case payloads carry raw inputs and outputs
•Store run IDs rather than case payloads when tracking results over time

Common Pitfalls

•Reading requires n8n 2.30+; run and cancel require n8n 2.32+ (on 2.30/2.31 those routes answer 405 and 404)
•API keys created before those releases silently lack the testRun scopes — a 403 means re-create the key, not a bug
•run and cancel also need the key owner to hold the workflow:execute project scope
•Evaluations are license- and quota-gated in n8n: an unlicensed instance returns 403, an exhausted quota returns 402
•A successful run response means the run was created, not that any case finished