MCP server tools reference

This page describes all tools exposed by the instance-level MCP server.

---

Workflow management

search_workflows

Search for workflows with optional filters. Returns a preview of each workflow.

Parameters

Name	Type	Required	Default	Description
query	string	No		Filter by name or description
projectId	string	No		Filter by project ID
tags	string[]	No		Filter by tag names. Uses AND semantics — a workflow must have all the listed tags to match.
limit	integer	No	200	Limit the number of results (max 200)
sortBy	string	No	"updatedAt:desc"	Sort order for results. One of: "updatedAt:desc", "updatedAt:asc", "createdAt:desc", "createdAt:asc", "name:asc", "name:desc"

Output

Field	Type	Description
data	array	List of workflow previews
data[].id	string	The unique identifier of the workflow
data[].name	`string	null`
data[].description	`string	null`
data[].active	`boolean	null`
data[].createdAt	`string	null`
data[].updatedAt	`string	null`
data[].triggerCount	`number	null`
data[].scopes	string[]	User permissions for this workflow
data[].canExecute	boolean	Whether the user has permission to execute this workflow
data[].availableInMCP	boolean	Whether the workflow is visible to MCP tools
data[].tags	array	Tags assigned to the workflow, each with id and name
count	integer	Total number of workflows that match the filters

Notes

• Maximum result limit is 200.

• Results are sorted by most recently updated workflows first by default.

• Includes user permission scopes for each workflow so MCP clients can see what actions are available for the workflow.

• Filtering by tags, and the tags field in results, are available from n8n v2.27.0. Use list_tags to discover the available tag names.

• IMPORTANT: This tool can list all workflows a user has access to, regardless of their Available in MCP setting.

get_workflow_details

Get detailed information about a specific workflow, including trigger details.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to retrieve

Output

Field	Type	Description
workflow	object	Sanitized workflow data safe for MCP consumption
workflow.id	string	Workflow ID
workflow.name	`string	null`
workflow.active	boolean	Whether the workflow has a published active version
workflow.isArchived	boolean	Whether the workflow is archived
workflow.versionId	string	The current workflow version ID
workflow.activeVersionId	`string	null`
workflow.triggerCount	number	Number of triggers
workflow.createdAt	`string	null`
workflow.updatedAt	`string	null`
workflow.settings	`object	null`
workflow.connections	object	Workflow connections graph
workflow.nodes	array	List of workflow nodes. Credential references are stripped
workflow.activeVersion	`object	null`
workflow.activeVersion.nodes	array	Nodes from the active workflow version. Credential references are stripped
workflow.activeVersion.connections	object	Connections from the active workflow version
workflow.tags	array	Tags with id and name
workflow.meta	`object	null`
workflow.parentFolderId	`string	null`
workflow.description	string	Workflow description, if set
workflow.scopes	string[]	User permissions for this workflow
workflow.canExecute	boolean	Whether the user has permission to execute this workflow
triggerInfo	string	Human-readable instructions describing how to trigger the workflow

Notes

• Sensitive credential data is stripped from returned nodes.

• Includes active version details if the workflow is published.

• Includes user permission scopes and whether the workflow can be executed by the current user.

• Use triggerInfo to understand how supported trigger nodes can be invoked.

---

execute_workflow

Execute a workflow by ID. Returns the execution ID immediately without waiting for completion.

Parameters

Name	Type	Required	Default	Description
workflowId	string	Yes		The ID of the workflow to execute
executionMode	`"manual"	"production"`	No	"production"
inputs	object	No		Inputs to provide to the workflow (discriminated union, see below)

inputs variants (discriminated by type):

Type	Fields	Description
chat	chatInput: string	Input for chat-based workflows
form	formData: Record<string, unknown>	Input data for form-based workflows
webhook	webhookData: { method?, query?, body?, headers? }	Input data for webhook-based workflows

webhookData fields:

Field	Type	Required	Default	Description
method	`"GET"	"POST"	"PUT"	"DELETE"
query	Record<string, string>	No		Query string parameters
body	Record<string, unknown>	No		Request body data
headers	Record<string, string>	No		HTTP headers

Output

Field	Type	Description
executionId	`string	null`
status	`"started"	"error"`
error	string	Error message if the execution couldn't be started

Notes

• This tool starts the workflow and returns immediately. Use get_execution with the returned executionId to check the final execution status or fetch execution data.

• Production mode supports workflows with Webhook, Chat Trigger, Form Trigger, and Schedule Trigger nodes.

• Manual mode also supports Manual Trigger nodes.

• When executionMode is "production", the workflow must have a published (active) version.

• If there are multiple supported triggers in a workflow, MCP clients may only be able to use one (first one) of them to trigger the workflow when using workflow execution tools.

• Executing workflows with multi-step forms or any kind of human-in-the-loop interactions isn't supported.

---

test_workflow

Available from n8n v2.15.0

Test a workflow using pin data to bypass external services. Trigger nodes, nodes with credentials, and HTTP Request nodes are pinned (use simulated data). Other nodes (Set, If, Code, etc.) execute normally, including credential-free I/O nodes like Execute Command or file read/write nodes.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to test
pinData	Record<string, array>	Yes	Pin data for all workflow nodes.
triggerNodeName	string	No	Optional name of the trigger node to start execution from. Defaults to the first trigger node.

Output

Field	Type	Description
executionId	`string	null`
status	string	The status of the test execution. One of: "success", "error", "running", "waiting", "canceled", "crashed", "new", "unknown"
error	string	Error message if the execution failed

Notes

• Can be used to test workflow logic without setting up credentials or hitting external services.

• This tool executes workflows synchronously (waits for execution to finish).

• Has an enforced MCP execution timeout (5 minutes).

---

prepare_test_pin_data

Available from n8n v2.15.0

Prepare test pin data for a workflow. Trigger nodes, nodes with credentials, and HTTP Request nodes need pin data. Logic nodes (Set, If, Code, etc.) and credential-free I/O nodes (Execute Command, file read/write) execute normally without pin data. Returns JSON Schemas describing the expected output shape for each node that needs pin data.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to generate test pin data for

Output

Field	Type	Description
nodeSchemasToGenerate	Record<string, JsonSchema>	Nodes that need pin data. Keys are node names, values are JSON Schema objects describing the expected output shape.
nodesWithoutSchema	string[]	Node names that need pin data but have no output schema. Use empty defaults [{"json": {}}] for each.
nodesSkipped	string[]	Nodes that don't need pin data and will execute normally during the test.
coverage	object	Coverage statistics
coverage.withSchemaFromExecution	number	Nodes with schemas inferred from last successful execution output
coverage.withSchemaFromDefinition	number	Nodes with schemas from node type definitions
coverage.withoutSchema	number	Nodes with no data or schema
coverage.skipped	number	Nodes that will execute normally (no pin data needed)
coverage.total	number	Total number of enabled nodes

Notes

• Schemas should be used to generate realistic sample data for test_workflow.

---

publish_workflow

Available from n8n v2.12.0

Publish (activate) a workflow to make it available for production execution. This creates an active version from the current draft.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to publish
versionId	string	No	Optional version ID to publish. If not provided, publishes the current draft version.

Output

Field	Type	Description
success	boolean	Whether publishing succeeded
workflowId	string	The workflow ID
activeVersionId	`string	null`
error	string	Error message if publishing failed

---

unpublish_workflow

Available from n8n v2.12.0

Unpublish (deactivate) a workflow to stop it from being available for production execution.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to unpublish

Output

Field	Type	Description
success	boolean	Whether unpublishing succeeded
workflowId	string	The workflow ID
error	string	Error message if unpublishing failed

---

search_projects

Available from n8n v2.14.0

Search for projects accessible to the current user. Use this to resolve a project ID before creating workflows or data tables in a specific project.

Parameters

Name	Type	Required	Description
query	string	No	Filter projects by name. Results are ranked with exact case-insensitive matches first, then partial matches.
type	`"personal"	"team"`	No
limit	integer	No	Limit the number of results (max 100)

Output

Field	Type	Description
data	array	List of matching projects, sorted with exact case-insensitive matches first
data[].id	string	The unique identifier of the project
data[].name	string	The name of the project
data[].type	`"personal"	"team"`
data[].matchType	`"exact"	"partial"`
count	integer	Total number of matching projects
teamProjectsEnabled	boolean	Whether team projects are licensed on this instance. When false, projectId is omitted by default on create_workflow_from_code, so the workflow is created in the caller's personal project, unless the user explicitly selects one of the returned accessible projects. Omitted on error responses. Available from n8n v2.26.0.
hint	string	Guidance for picking a result. Present when the match is ambiguous (for example, no exact match but multiple partial matches), or when team projects aren't licensed on this instance

Notes

• Maximum result limit is 100.

• If a user names a project, call this tool first and pass the resolved project ID to create_workflow_from_code, update_workflow, or data table tools.

• If hint is present, follow it before acting. For example, ask the user to clarify instead of guessing between multiple partial matches.

---

search_folders

Available from n8n v2.14.0

Search for folders within a project.

Parameters

Name	Type	Required	Description
projectId	string	Yes	The ID of the project to search folders in
query	string	No	Filter folders by name (case-insensitive partial match)
limit	integer	No	Limit the number of results (max 100)

Output

Field	Type	Description
data	array	List of matching folders
data[].id	string	The unique identifier of the folder
data[].name	string	The name of the folder
data[].parentFolderId	`string	null`
count	integer	Total number of matching folders

Notes

• Maximum result limit is 100.

• This tool enables MCP clients to create workflows in a specific folder.

---

list_tags

Available from n8n v2.27.0

List all workflow tags in the instance. Tags are global (not project-scoped) and can be used with search_workflows to filter results.

Parameters

Name	Type	Required	Default	Description
limit	integer	No	500	Limit the number of results (max 500)

Output

Field	Type	Description
data	array	Workflow tags available in the instance
data[].id	string	The unique identifier of the tag
data[].name	string	The display name of the tag
data[].usageCount	integer	Number of non-archived workflows using this tag
data[].createdAt	string	ISO timestamp when the tag was created
data[].updatedAt	string	ISO timestamp when the tag was last updated
count	integer	Number of tags returned
totalCount	integer	Total number of tags before applying the limit

Notes

• Maximum result limit is 500.

• Tags are global and aren't scoped to a project.

• usageCount only counts non-archived workflows.

• Requires the tag:list global permission.

• Only available when workflow tags are enabled on the instance. If tags are disabled in the instance settings, this tool isn't exposed.

---

Execution management

get_execution

Available from n8n v2.12.0

Get execution details by execution ID and workflow ID. By default returns metadata only.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow the execution belongs to
executionId	string	Yes	The ID of the execution to retrieve
includeData	boolean	No	Whether to include full execution result data. Defaults to false (metadata only).
nodeNames	string[]	No	When includeData is true, return data only for these nodes. If omitted, data for all nodes is included.
truncateData	integer	No	When includeData is true, limit the number of data items returned per node output.

Output

Field	Type	Description
execution	`object	null`
execution.id	string	Execution ID
execution.workflowId	string	Workflow ID
execution.mode	string	Execution mode
execution.status	string	Execution status
execution.startedAt	`string	null`
execution.stoppedAt	`string	null`
execution.retryOf	`string	null`
execution.retrySuccessId	`string	null`
execution.waitTill	`string	null`
data	unknown	Execution result data (only present when includeData is true)
error	string	Error message if the request failed

Notes

• Use lightweight metadata queries (default) when full execution data isn't needed.

• Filtering by nodeNames and truncating via truncateData helps manage large result sets.

---

search_executions

Available from n8n v2.20.0

Search for workflow executions with optional filters. Returns execution metadata including status, timing, and workflow ID.

Parameters

Name	Type	Required	Description
workflowId	string	No	Filter executions by workflow ID
status	string[]	No	Filter by execution statuses. Values: "canceled", "crashed", "error", "new", "running", "success", "unknown", "waiting"
startedAfter	string	No	ISO 8601 timestamp. Only return executions that started after this time.
startedBefore	string	No	ISO 8601 timestamp. Only return executions that started before this time.
limit	integer	No	Limit the number of results (max 200)
lastId	string	No	Cursor for pagination. Pass the last execution ID from the previous page.

Output

Field	Type	Description
data	array	List of executions matching the query
data[].id	string	The unique identifier of the execution
data[].workflowId	string	The workflow this execution belongs to
data[].status	string	The execution status
data[].mode	string	How the execution was triggered. One of: "cli", "error", "integrated", "internal", "manual", "retry", "trigger", "webhook", "evaluation", "chat"
data[].startedAt	`string	null`
data[].stoppedAt	`string	null`
data[].waitTill	`string	null`
count	integer	Total matching executions, or -1 if the count is unavailable
estimated	boolean	Whether the count is an estimate for large datasets
error	string	Error message if the query failed

---

Credential management

list_credentials

Available from n8n v2.21.0

List credentials the current user can access. Use this to find a credential ID before referencing it from a workflow node. Never returns credential secret data.

Parameters

Name	Type	Required	Description
limit	integer	No	Limit the number of results (max 200)
query	string	No	Filter credentials by name (partial match)
type	string	No	Filter by credential type, for example "slackApi" or "httpHeaderAuth" (partial match)
projectId	string	No	Restrict results to credentials belonging to this project
onlySharedWithMe	boolean	No	Only return credentials shared directly with the current user. Defaults to false.

Output

Field	Type	Description
data	array	List of credentials accessible to the current user
data[].id	string	The unique identifier of the credential
data[].name	string	The name of the credential
data[].type	string	The credential type, for example "slackApi"
data[].scopes	string[]	User permissions for this credential, for example "credential:read"
data[].isManaged	boolean	Whether the credential is managed by n8n and can't be edited by the user
data[].isGlobal	boolean	Whether the credential is available to all users
data[].homeProject	`object	null`
data[].homeProject.id	string	The unique identifier of the project
data[].homeProject.name	string	The name of the project
data[].homeProject.type	string	The project type. "personal" is a user's private project; "team" is a shared project accessible to multiple users.
count	integer	Number of credentials returned
error	string	Error message if the request failed

Notes

• Maximum result limit is 200.

• Credential secret data is never returned.

• By default, global credentials are included. Set onlySharedWithMe to true to exclude global credentials and only return credentials shared directly with the current user.

---

Workflow builder

get_sdk_reference

Available from n8n v2.12.0

Get the n8n Workflow SDK reference documentation including patterns, expression syntax, functions, rules, import syntax, guidelines, and design guidance.

Parameters

Name	Type	Required	Default	Description
section	string	No	"all"	Documentation section to retrieve. One of: "patterns", "patterns_detailed", "expressions", "functions", "rules", "import", "guidelines", "design", "all"

Output

Field	Type	Description
reference	string	SDK reference documentation content for the requested section

Notes

• Should be called first before building any workflows.

• Omit section, or set it to "all", to retrieve the full reference.

• Use "patterns_detailed" for expanded workflow pattern examples.

---

search_nodes

Available from n8n v2.12.0

Search for n8n nodes by service name, trigger type, or utility function. Returns node IDs, discriminators (resource/operation/mode), and related nodes needed for get_node_types tool.

Parameters

Name	Type	Required	Description
queries	string[]	Yes (min 1)	Search queries -- service names (for example "gmail", "slack"), trigger types (for example "schedule trigger", "webhook"), or utility nodes (for example "set", "if", "merge", "code")

Output

Field	Type	Description
results	string	Search results with matching node IDs, discriminators, and related nodes

---

get_node_types

Available from n8n v2.12.0

Get TypeScript type definitions for n8n nodes. Returns exact parameter names and structures.

Parameters

Name	Type	Required	Description
nodeIds	array	Yes (min 1)	Array of node type request objects. Always pass objects (even for a single node), for example { "nodeId": "n8n-nodes-base.gmail" }. Include discriminators from search_nodes results when available.

Node ID object format:

Field	Type	Required	Description
nodeId	string	Yes	The node type ID (for example "n8n-nodes-base.gmail")
version	string	No	Specific version (for example "2.1")
resource	string	No	Resource discriminator (for example "message")
operation	string	No	Operation discriminator (for example "send")
mode	string	No	Mode discriminator

Output

Field	Type	Description
definitions	string	TypeScript type definitions for the requested nodes

Notes

• Critical for correct node configuration - MCP clients should always call before writing workflow code.

• From n8n v2.27.0, every nodeIds entry must be an object. Plain string node IDs are no longer accepted - wrap them as { "nodeId": "..." }.

• Use the resource, operation, and mode discriminators for multi-variant nodes.

---

get_workflow_best_practices

Available from n8n v2.26.0

Get best-practices guidance for a workflow technique. Useful this before searching for nodes or writing workflow code.

Parameters

Name	Type	Required	Description
technique	string	Yes	Workflow technique key to fetch guidance for. Pass "list" to discover all available techniques. Values include: "scheduling", "chatbot", "form_input", "scraping_and_research", "monitoring", "enrichment", "triage", "content_generation", "document_processing", "data_extraction", "data_analysis", "data_transformation", "data_persistence", "notification", "knowledge_base", "human_in_the_loop", "web_app"

Output

Field	Type	Description
technique	string	The requested technique key, or "list" when listing all available techniques
message	string	Human-readable summary of the response
documentation	string	Best-practices documentation for the requested technique, when available
availableTechniques	array	List of available techniques, returned when technique is "list"
availableTechniques[].technique	string	Technique key
availableTechniques[].description	string	Description of the technique
availableTechniques[].hasDocumentation	boolean	Whether detailed best-practices documentation is available for this technique

Notes

• When called with technique: "list", will list all available techniques

• Some known techniques may not have detailed documentation yet. In that case, the tool returns a message without documentation.

• This replaces the previous get_suggested_nodes workflow-planning guidance.

---

explore_node_resources

Available from n8n v2.27.0

Resolve the real values behind a node's resource locator or load-options dropdown (for example Slack channels, Google Sheets tabs, or available AI models). Requires a credential to be set for the desired service.

Parameters

Name	Type	Required	Description
nodeType	string	Yes	Fully-qualified node type ID from search_nodes / get_node_types, for example "n8n-nodes-base.slack"
version	number	Yes	Node version, for example 4.7. Must match a version returned by search_nodes.
methodName	string	Yes	The exact method name from the node's @searchListMethod or @loadOptionsMethod annotation in the type definition. Call get_node_types first to read the real method name — don't guess.
methodType	`"listSearch"	"loadOptions"`	Yes
credentialType	string	Yes	Credential type key for the node, for example "slackApi" or "googleSheetsOAuth2Api"
credentialId	string	Yes	ID of a credential the user can access, obtained from list_credentials
filter	string	No	Optional search/filter text to narrow results
paginationToken	string	No	Pagination token from a previous call to fetch the next page (listSearch only)
currentNodeParameters	object	No	Current node parameters for dependent lookups. Some methods require prior selections — for example, listing sheets within a spreadsheet needs { documentId: { __rl: true, mode: "id", value: "<spreadsheetId>" } }. Check the type definition's displayOptions to know which parameters a method depends on.

Output

Field	Type	Description
results	array	Resources returned by the node method
results[].name	string	The display label of the resource
results[].value	`string	number
results[].url	string	URL for the resource, when available
results[].description	string	Description of the resource, when available
paginationToken	string	Pass back as paginationToken to fetch the next page. Absent when there are no more results.
builderHint	string	Selection guidance from the node's @builderHint annotation, when present

Notes

• Requires a credentialId from list_credentials; the lookup runs as the current user using that credential.

• listSearch methods support filter and pagination via paginationToken; loadOptions methods don't.

• This tool reaches out to external services, unlike most other read-only tools.

---

validate_workflow

Available from n8n v2.12.0

Validate n8n Workflow SDK code. Parses the code into a workflow and checks for errors. Always validate before creating or updating a workflow.

Parameters

Name	Type	Required	Description
code	string	Yes	Full TypeScript/JavaScript workflow code using the n8n Workflow SDK. Must include the workflow export.

Output

Field	Type	Description
valid	boolean	Whether the workflow code is valid
nodeCount	number	The number of nodes in the workflow. Only present when valid
warnings	array	Validation warnings, if any
warnings[].code	string	The warning code identifying the type of warning
warnings[].message	string	The warning message
warnings[].nodeName	string	The node that triggered the warning, if applicable
warnings[].parameterPath	string	The parameter path that triggered the warning, if applicable
errors	string[]	Validation errors. Only present when invalid
hint	string	Actionable recovery hint, if available

Notes

• Must be called before create_workflow_from_code or update_workflow.

• Warnings may be present even when the code is valid.

• If valid is false and hint is present, follow the hint before retrying.

---

validate_node_config

Available from n8n v2.25.1

Validate one or more node configurations independently against their generated node schemas. Useful while composing nodes, before assembling workflow code or calling update_workflow.

Parameters

Name	Type	Required	Description
nodes	array	Yes (min 1, max 50)	One or more node configurations to validate independently
nodes[].name	string	No	Optional node name. Returned in the result to help correlate responses
nodes[].type	string	Yes	Full node type, for example "n8n-nodes-base.set" or "@n8n/n8n-nodes-langchain.agent"
nodes[].typeVersion	number	No	Node type version. Defaults to 1
nodes[].parameters	object	No	Node parameters object, using the same shape as workflow JSON. Defaults to {}
nodes[].subnodes	unknown	No	Optional subnode configuration for AI parent nodes, for example LangChain agent model, memory, or tool references
nodes[].isToolNode	boolean	No	Set to true when validating a node wired as an AI tool subnode through an ai_tool connection

Output

Field	Type	Description
valid	boolean	Whether every node configuration is valid
results	array	Per-node validation results, in input order
results[].index	number	Position of this node in the input array
results[].name	string	Echo of the input node name, if provided
results[].type	string	Echo of the input node type
results[].valid	boolean	Whether this node configuration is valid
results[].errors	array	Validation errors for this node. Omitted when the node is valid
results[].errors[].path	string	Parameter path of the error
results[].errors[].message	string	Human-readable error message
error	string	Top-level error message if validation couldn't run

Notes

• This validates node parameter schemas only.

• It doesn't check workflow-level concerns such as connections, required inputs, triggers, disconnected nodes, or credential existence.

• For LangChain or AI tool subnodes, set isToolNode to true so the schema evaluates the correct display options branch.

---

create_workflow_from_code

Available from n8n v2.12.0

Create a workflow in n8n from validated SDK code. Parses the code into a workflow and saves it.

Parameters

Name	Type	Required	Description
code	string	Yes	Full TypeScript/JavaScript workflow code using the n8n Workflow SDK. Must be validated first with validate_workflow.
skillsUsed	string[]	No	Names of n8n skills used by the MCP client to produce this workflow. Values are normalized server-side.
name	string	No	Optional workflow name (max 128 chars). If not provided, uses the name from the code.
description	string	No	Workflow description. Text longer than 255 characters is shortened to 255 before saving.
projectId	string	No	Project ID to create the workflow in. Defaults to the user's personal project. Use search_projects first if the user names a project.
folderId	string	No	Folder ID to create the workflow in. Requires projectId to be set. Use search_folders to find a folder by name within a project.

Output

Field	Type	Description
workflowId	string	The ID of the created workflow
name	string	The name of the created workflow
nodeCount	number	The number of nodes in the workflow
url	string	The URL to open the workflow in n8n
autoAssignedCredentials	array	List of credentials that were automatically assigned to nodes
autoAssignedCredentials[].nodeName	string	The name of the node that had credentials auto-assigned
autoAssignedCredentials[].credentialName	string	The name of the credential that was auto-assigned
autoAssignedCredentials[].credentialType	string	The credential type that was auto-assigned
targetProject	object	The project the workflow was created in
targetProject.id	string	The ID of the project
targetProject.name	string	The display name of the project
targetProject.type	`"personal"	"team"`
note	string	Additional notes about workflow creation, for example nodes skipped during credential auto-assignment or a description that was shortened to 255 characters
hint	string	Actionable recovery hint, if available after an error

Notes

• Automatically assigns available credentials to nodes.

• HTTP Request nodes are skipped during credential auto-assignment and must be configured manually.

• Sets availableInMCP flag to true on the created workflow.

• Marks the workflow with aiBuilderAssisted metadata and builderVariant: mcp.

• Resolves webhook node IDs automatically.

• folderId requires projectId to also be provided.

• If the user names a target project, call search_projects first and pass the resolved projectId; don't guess.

• After creation, tell the user which project the workflow was created in using the targetProject field.

• From n8n v2.27.0, a description longer than 255 characters is truncated (not rejected); the response note mentions when this happens.

---

update_workflow

Available from n8n v2.12.0. Starting from v2.20.0, this tool switched to performing partial updates instead of re-writing the full workflow on every update.

Update an existing workflow in n8n by applying an ordered batch of targeted partial updates. The batch is atomic: if any operation fails, no changes are saved.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to update
skillsUsed	string[]	No	Names of n8n skills used by the MCP client to produce this workflow update. Values are normalized server-side.
operations	array	Yes	Ordered list of operations to apply. Must contain 1-100 operations.

Supported operations

Operation	Required fields	Optional fields	Description
updateNodeParameters	nodeName, parameters	replace	Deep-merges parameters into an existing node's parameters. If replace is true, replaces the full parameters object.
setNodeParameter	nodeName, path, value		Sets one parameter using an RFC 6901 JSON Pointer path, for example /jsonSchema or /options/systemMessage. Creates intermediate objects as needed. Array indices aren't supported; set the whole array instead.
addNode	node.name, node.type, node.typeVersion	node.id, node.parameters, node.position, node.credentials, node.disabled, node.notes	Adds a node. position is [x, y]. id is generated if omitted. Node names must be unique.
removeNode	nodeName		Removes a node and all inbound and outbound connections. Connected sub-nodes remain in the workflow but become disconnected.
renameNode	oldName, newName		Renames a node and rewrites connection references. The new name must be unique.
addConnection	source, target	sourceIndex, targetIndex, connectionType	Adds a connection. sourceIndex and targetIndex default to 0; connectionType defaults to main. Existing identical connections aren't duplicated.
removeConnection	source, target	sourceIndex, targetIndex, connectionType	Removes a matching connection. sourceIndex and targetIndex default to 0; connectionType defaults to main.
setNodeCredential	nodeName, credentialKey, credentialId, credentialName		Sets or replaces a node credential reference. The credential must be accessible and match the node type's accepted credential key.
setNodePosition	nodeName, position		Updates a node's canvas position as [x, y].
setNodeDisabled	nodeName, disabled		Enables or disables a node.
setNodeSettings	nodeName, settings		Updates node-level execution settings. settings must include at least one supported setting.
setWorkflowMetadata		name, description	Updates workflow metadata. name has a maximum length of 128 characters; description has a maximum length of 255 characters.

setNodeSettings fields

Field	Type	Required	Description
onError	`"stopWorkflow"	"continueRegularOutput"	"continueErrorOutput"`
retryOnFail	boolean	No	Whether to retry the node when it fails
maxTries	integer	No	Number of attempts when retryOnFail is true. Must be 2-5
waitBetweenTries	integer	No	Milliseconds to wait between retry attempts. Must be 0-5000
alwaysOutputData	boolean	No	Whether the node should always output data
executeOnce	boolean	No	Whether the node should execute only once

Output

Field	Type	Description
workflowId	string	The ID of the updated workflow
name	string	The name of the updated workflow
nodeCount	number	The number of nodes in the workflow
url	string	The URL to open the workflow in n8n
appliedOperations	number	The number of operations applied
autoAssignedCredentials	array	Credentials automatically assigned to nodes added in this update
autoAssignedCredentials[].nodeName	string	The node that had credentials auto-assigned
autoAssignedCredentials[].credentialName	string	The credential that was auto-assigned
autoAssignedCredentials[].credentialType	string	The credential type that was auto-assigned
validationWarnings	array	Graph and JSON validation warnings for the resulting workflow. These warnings don't block saving
validationWarnings[].code	string	Warning code
validationWarnings[].message	string	Warning message
validationWarnings[].nodeName	string	Optional node associated with the warning
note	string	Additional notes about the workflow update, for example HTTP Request nodes skipped during credential auto-assignment
error	string	Error message if the update failed

Notes

• Operations are applied in order and saved atomically.

• Existing credentials are preserved unless explicitly changed.

• Credential auto-assignment runs only for nodes added in the current call.

• HTTP Request nodes are skipped during credential auto-assignment and must be configured manually.

• The resulting workflow is validated before saving. Validation warnings are returned in validationWarnings.

• Marks the workflow with aiBuilderAssisted metadata and builderVariant: mcp.

---

archive_workflow

Available from n8n v2.12.0

Archive a workflow in n8n by its ID.

Parameters

Name	Type	Required	Description
workflowId	string	Yes	The ID of the workflow to archive

Output

Field	Type	Description
archived	boolean	Whether the workflow was archived
workflowId	string	The ID of the archived workflow
name	string	The name of the archived workflow

Notes

• Idempotent - skips already-archived workflows.

---

Data tables

search_data_tables

Available from n8n v2.16.0

Search for data tables accessible to the current user. Use this to find a data table ID before modifying or adding data to it.

Parameters

Name	Type	Required	Description
query	string	No	Filter data tables by name (case-insensitive partial match)
projectId	string	No	Filter by project ID
limit	integer	No	Limit the number of results (max 100)

Output

Field	Type	Description
data	array	List of data tables matching the query
data[].id	string	Unique identifier of the data table
data[].name	string	The name of the data table
data[].projectId	string	The project this data table belongs to
data[].createdAt	string	ISO timestamp when the data table was created
data[].updatedAt	string	ISO timestamp when the data table was last updated
data[].columns	array	The columns defined in this data table
data[].columns[].id	string	Column unique identifier
data[].columns[].name	string	Column name
data[].columns[].type	string	Column data type. One of: "string", "number", "boolean", "date"
data[].columns[].index	integer	Column position in the table
count	integer	Total number of matching data tables

Notes

• Maximum result limit is 100.

---

create_data_table

Available from n8n v2.16.0

Create a new data table with the specified columns.

Parameters

Name	Type	Required	Description
projectId	string	Yes	The project ID where the data table will be created
name	string	Yes	The name of the data table (min 1, max 128 chars, must be unique within the project)
columns	array	Yes (min 1)	The columns to create in the data table
columns[].name	string	Yes	Column name. Must start with a letter, contain only letters, numbers, and underscores (max 63 chars).
columns[].type	string	Yes	The data type of the column. One of: "string", "number", "boolean", "date"

Output

Field	Type	Description
id	string	The unique identifier of the created data table
name	string	The name of the created data table
projectId	string	The project ID of the created data table

Notes

• At least one column is required.

• Table name must be unique within the project.

• Column names must match the pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ (max 63 chars).

---

add_data_table_column

Available from n8n v2.16.0

Add a new column to an existing data table.

Parameters

Name	Type	Required	Description
dataTableId	string	Yes	The ID of the data table to add a column to
projectId	string	Yes	The project ID the data table belongs to
name	string	Yes	Column name. Must start with a letter, contain only letters, numbers, and underscores (max 63 chars).
type	string	Yes	The data type of the new column. One of: "string", "number", "boolean", "date"

Output

Field	Type	Description
success	boolean	Whether the operation succeeded
message	string	Description of the result
column	object	The created column
column.id	string	Column unique identifier
column.name	string	Column name
column.type	string	Column data type

Notes

• Column names must match the pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ (max 63 chars).

• Column type is immutable (through MCP) after creation.

---

rename_data_table_column

Available from n8n v2.16.0

Rename a column in a data table.

Parameters

Name	Type	Required	Description
dataTableId	string	Yes	The ID of the data table containing the column
projectId	string	Yes	The project ID the data table belongs to
columnId	string	Yes	The ID of the column to rename
name	string	Yes	The new column name. Must follow column naming rules.

Output

Field	Type	Description
success	boolean	Whether the operation succeeded
message	string	Description of the result
column	object	The renamed column
column.id	string	Column unique identifier
column.name	string	New column name
column.type	string	Column data type

Notes

• New name must follow column naming rules: ^[a-zA-Z][a-zA-Z0-9_]*$ (max 63 chars).

---

delete_data_table_column

Available from n8n v2.16.0

Delete a column from a data table. This permanently removes the column and all its data.

Parameters

Name	Type	Required	Description
dataTableId	string	Yes	The ID of the data table containing the column
projectId	string	Yes	The project ID the data table belongs to
columnId	string	Yes	The ID of the column to delete

Output

Field	Type	Description
success	boolean	Whether the operation succeeded
message	string	Description of the result

Notes

• Deleting a column through MCP can't be undone.

---

rename_data_table

Available from n8n v2.16.0

Rename an existing data table.

Parameters

Name	Type	Required	Description
dataTableId	string	Yes	The ID of the data table to rename
projectId	string	Yes	The project ID the data table belongs to
name	string	Yes	The new name for the data table (min 1, max 128 chars)

Output

Field	Type	Description
success	boolean	Whether the operation succeeded
message	string	Description of the result

Notes

• Name must be unique within the project.

---

add_data_table_rows

Available from n8n v2.16.0

Insert rows into an existing data table. Each row is an object mapping column names to values.

Parameters

Name	Type	Required	Description
dataTableId	string	Yes	The ID of the data table to insert rows into
projectId	string	Yes	The project ID the data table belongs to
rows	array	Yes (min 1, max 1000)	Array of row objects. Each object maps column names to values (string, number, boolean, or null).

Output

Field	Type	Description
success	boolean	Whether the insert operation succeeded
insertedCount	integer	Number of rows successfully inserted

Notes

• Maximum 1000 rows per call.

• Row values must be string, number, boolean, or null.

• Column names in row objects must match existing column names in the data table.