n8n Advanced AI

https://docs.n8n.io/advanced-ai/
Admin
n8n Advanced AI enables building AI-powered workflows including chatbots, document processing, and...
Tokens:20,998
Snippets:367
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Advanced $fromAI() parameter configuration

Source: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function

Examples showing how to use optional parameters like description, type, and default values to guide the AI model.

```javascript
$fromAI("name", "The commenter's name", "string", "Jane Doe")
```

```javascript
$fromAI("name")
```

```javascript
$fromAI("numItemsInStock", "Number of items in stock", "number", 5)
```

--------------------------------

### Example Human Review Message Configuration

Source: https://docs.n8n.io/advanced-ai/human-in-the-loop-tools

Use the `$tool.name` and `$tool.parameters` variables to construct a message for human reviewers, providing context about the AI's intended tool call and its parameters. This helps reviewers understand the action before approving or denying.

```handlebars
The AI wants to use {{ $tool.name }} with the following parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}
```

--------------------------------

### GET /get_sdk_reference

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Retrieves the n8n Workflow SDK reference documentation.

```APIDOC
## GET /get_sdk_reference

### Description
Get the n8n Workflow SDK reference documentation including patterns, expression syntax, and functions.

### Method
GET

### Endpoint
/get_sdk_reference

### Parameters
#### Query Parameters
- **section** (string) - Optional - Documentation section to retrieve. One of: "patterns", "expressions", "functions", "rules", "import", "guidelines", "design", "all". Default: "all"

### Response
#### Success Response (200)
- **reference** (string) - SDK reference documentation content for the requested section
```

--------------------------------

### GET /search_projects

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Search for projects accessible to the current user.

```APIDOC
## GET /search_projects

### Description
Search for projects accessible to the current user.

### Method
GET

### Endpoint
/search_projects

### Parameters
#### Query Parameters
- **query** (string) - Optional - Filter projects by name (case-insensitive partial match)
- **type** ("personal" | "team") - Optional - Filter by project type
- **limit** (integer) - Optional - Limit the number of results (max 100)

### Response
#### Success Response (200)
- **data** (array) - List of matching projects
- **data[].id** (string) - The unique identifier of the project
- **data[].name** (string) - The name of the project
- **data[].type** ("personal" | "team") - The project type
- **count** (integer) - Total number of matching projects
```

--------------------------------

### GET /search_folders

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Search for folders within a specific project.

```APIDOC
## GET /search_folders

### Description
Search for folders within a project.

### Method
GET

### Endpoint
/search_folders

### Parameters
#### Query Parameters
- **projectId** (string) - Required - The ID of the project to search folders in
- **query** (string) - Optional - Filter folders by name (case-insensitive partial match)
- **limit** (integer) - Optional - Limit the number of results (max 100)

### Response
#### Success Response (200)
- **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) - The ID of the parent folder, or null if at project root
- **count** (integer) - Total number of matching folders
```

--------------------------------

### Get Suggested Nodes API

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Get curated node recommendations for workflow technique categories. Returns recommended nodes with pattern hints and configuration guidance.

```APIDOC
## POST /get_suggested_nodes

### Description
Get curated node recommendations for workflow technique categories. Returns recommended nodes with pattern hints and configuration guidance. Use after analyzing what kind of workflow to build.

### Method
POST

### Endpoint
/get_suggested_nodes

### Parameters
#### Request Body
- **categories** (string[]) - Required - Workflow technique categories. Available values: `chatbot`, `notification`, `scheduling`, `data_transformation`, `data_persistence`, `data_extraction`, `document_processing`, `form_input`, `content_generation`, `triage`, `find_research`

### Response
#### Success Response (200)
- **suggestions** (string) - Curated node recommendations with pattern hints and configuration guidance

### Request Example
```json
{
  "categories": ["chatbot", "content_generation"]
}
```

### Response Example
```json
{
  "suggestions": "[\"n8n-nodes-base.openai\", \"n8n-nodes-base.slack_message\"]"
}
```
```

--------------------------------

### GET get_execution

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Retrieves execution details by execution ID and workflow ID, with options to include full result data.

```APIDOC
## GET get_execution

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

### Parameters
#### Query Parameters
- **workflowId** (string) - Required - The ID of the workflow the execution belongs to
- **executionId** (string) - Required - The ID of the execution to retrieve
- **includeData** (boolean) - Optional - Whether to include full execution result data. Defaults to false (metadata only).
- **nodeNames** (string[]) - Optional - When includeData is true, return data only for these nodes.
- **truncateData** (integer) - Optional - When includeData is true, limit the number of data items returned per node output.

### Response
#### Success Response (200)
- **execution** (object | null) - Execution metadata
- **data** (unknown) - Execution result data (only present when includeData is true)
- **error** (string) - Error message if the request failed
```

--------------------------------

### Get Node Types API

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

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

```APIDOC
## POST /get_node_types

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

### Method
POST

### Endpoint
/get_node_types

### Parameters
#### Request Body
- **nodeIds** (array) - Required - Array of node IDs. Each element can be a plain string (for example `"n8n-nodes-base.gmail"`) or an object with discriminators.
  - **nodeId** (string) - Required - The node type ID (for example `"n8n-nodes-base.gmail"`)
  - **version** (string) - Optional - Specific version (for example `"2.1"`)
  - **resource** (string) - Optional - Resource discriminator (for example `"message"`)
  - **operation** (string) - Optional - Operation discriminator (for example `"send"`)
  - **mode** (string) - Optional - Mode discriminator

### Response
#### Success Response (200)
- **definitions** (string) - TypeScript type definitions for the requested nodes

### Request Example
```json
{
  "nodeIds": ["n8n-nodes-base.gmail", {"nodeId": "n8n-nodes-base.slack", "resource": "message", "operation": "send"}]
}
```

### Response Example
```json
{
  "definitions": "// TypeScript definitions..."
}
```
```

--------------------------------

### Initialize Google ADK Agent with n8n MCP Toolset

Source: https://docs.n8n.io/advanced-ai/mcp/accessing-n8n-mcp-server

Configures an agent using the McpToolset to connect to an n8n instance via HTTP. Requires a valid N8N_MCP_TOKEN for authorization.

```python
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams

N8N_INSTANCE_URL = "https://localhost:5678"
N8N_MCP_TOKEN = "YOUR_N8N_MCP_TOKEN"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="n8n_agent",
    instruction="Help users manage and execute workflows in n8n",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPServerParams(
                url=f"{N8N_INSTANCE_URL}/mcp-server/http",
                headers={
                    "Authorization": f"Bearer {N8N_MCP_TOKEN}",
                },
            ),
        )
    ],
)
```

--------------------------------

### Configure Claude Desktop with Access Token

Source: https://docs.n8n.io/advanced-ai/mcp/accessing-n8n-mcp-server

Add this configuration to your claude_desktop_config.json file to enable HTTP-based MCP access.

```json
"mcpServers": {
  "n8n-local": {
    "type": "http",
    "url": "https://<your-n8n-domain>/mcp-server/http",
    "headers": {
      "Authorization": "Bearer <YOUR_N8N_MCP_TOKEN>"
    }
  }
}
```

--------------------------------

### Using the $fromAI() Function

Source: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function

The $fromAI() function allows AI to dynamically fill in parameters for tools connected to the AI Agent node. It is not compatible with the Code tool or other non-tool cluster sub-nodes.

```APIDOC
## Using the $fromAI() Function

### Description
The `$fromAI()` function uses AI to dynamically fill in parameters for tools connected to the Tools AI agent. It is only available for tools connected to the AI Agent node and does not work with the Code tool or other non-tool cluster sub-nodes.

### Parameters

#### Function Parameters
- **key** (string) - Required - A string representing the key or name of the argument. This must be between 1 and 64 characters in length and can only contain lowercase letters, uppercase letters, numbers, underscores, and hyphens.
- **description** (string) - Optional - A string describing the argument.
- **type** (string) - Optional - A string specifying the data type. Can be string, number, boolean, or json (defaults to string).
- **defaultValue** (any) - Optional - The default value to use for the argument.

### Examples

#### Basic Usage
```apidoc
{{ $fromAI('email') }}
```

#### With Optional Parameters
```apidoc
$fromAI("name", "The commenter's name", "string", "Jane Doe")
```

#### Simplified Usage (without optional parameters)
```apidoc
$fromAI("name")
```

#### Example with Number Type and Default Value
```apidoc
$fromAI("numItemsInStock", "Number of items in stock", "number", 5)
```

#### Using $fromAI() within a larger expression
```apidoc
Generated by AI: {{ $fromAI("subject") }}
```
```

--------------------------------

### POST prepare_test_pin_data

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Generates JSON schemas describing the expected output shape for nodes requiring pin data.

```APIDOC
## POST prepare_test_pin_data

### Description
Prepare test pin data for a workflow. Returns JSON Schemas describing the expected output shape for each node that needs pin data.

### Parameters
#### Request Body
- **workflowId** (string) - Required - The ID of the workflow to generate test pin data for
```

--------------------------------

### Create Workflow From Code API

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

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

```APIDOC
## POST /create_workflow_from_code

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

### Method
POST

### Endpoint
/create_workflow_from_code

### Parameters
#### Request Body
- **code** (string) - Required - Full TypeScript/JavaScript workflow code using the n8n Workflow SDK. Must be validated first with `validate_workflow`.
- **name** (string) - Optional - Optional workflow name (max 128 chars). If not provided, uses the name from the code.
- **description** (string) - Optional - Short workflow description (max 255 chars, 1-2 sentences).
- **projectId** (string) - Optional - Project ID to create the workflow in. Defaults to the user's personal project.
- **folderId** (string) - Optional - Folder ID to create the workflow in. Requires `projectId` to be set.

### Response
#### Success Response (200)
- **workflowId** (string) - The ID of the created workflow

### Request Example
```json
{
  "code": "export default {
    name: 'My New Workflow',
    nodes: [
      {
        id: '1',
        type: 'start',
        typeVersion: 1,
        position: [80, 300]
      }
    ]
  };",
  "name": "My API Created Workflow",
  "description": "A workflow created via the API."
}
```

### Response Example
```json
{
  "workflowId": "wf_abc123xyz"
}
```
```

--------------------------------

### Configure Codex CLI MCP Server

Source: https://docs.n8n.io/advanced-ai/mcp/accessing-n8n-mcp-server

Add the n8n MCP server definition to your ~/.codex/config.toml file.

```toml
[mcp_servers.n8n_mcp]
url = "https://<your-n8n-domain>/mcp-server/http"
http_headers = { "authorization" = "Bearer <YOUR_N8N_MCP_TOKEN>" }
```

--------------------------------

### POST test_workflow

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Tests a workflow using pin data to bypass external services and credentials.

```APIDOC
## POST test_workflow

### Description
Test a workflow using pin data to bypass external services. Trigger nodes, nodes with credentials, and HTTP Request nodes are pinned.

### Parameters
#### Request Body
- **workflowId** (string) - Required - The ID of the workflow to test
- **pinData** (Record<string, array>) - Required - Pin data for all workflow nodes.
- **triggerNodeName** (string) - Optional - Optional name of the trigger node to start execution from.

### Response
#### Success Response (200)
- **executionId** (string | null) - The test execution ID
- **status** (string) - The status of the test execution
- **error** (string) - Error message if the execution failed
```

--------------------------------

### Configure Claude Code with JSON file

Source: https://docs.n8n.io/advanced-ai/mcp/accessing-n8n-mcp-server

Alternatively, define the n8n MCP server directly in your claude.json configuration file.

```json
{
    "mcpServers": {
        "n8n-local": {
            "type": "http",
            "url": "https://<your-n8n-domain>/mcp-server/http",
            "headers": {
                "Authorization": "Bearer <YOUR_N8N_MCP_TOKEN>"
            }
        }
    }
}
```

--------------------------------

### Basic $fromAI() usage

Source: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function

A simple implementation of the $fromAI function to retrieve an email address.

```javascript
{{ $fromAI('email') }}
```

--------------------------------

### Create Data Table API

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Creates a new data table within a specified project. Requires a name and at least one column definition.

```APIDOC
## POST /api/data-tables

### Description
Creates a new data table within a specified project.

### Method
POST

### Endpoint
/api/data-tables

### Parameters
#### Request Body
- **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"

### Request Example
{
  "projectId": "your_project_id",
  "name": "my_new_table",
  "columns": [
    {
      "name": "user_id",
      "type": "string"
    },
    {
      "name": "signup_date",
      "type": "date"
    }
  ]
}

### Response
#### Success Response (200)
- **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

#### Response Example
{
  "id": "dt_abc123",
  "name": "my_new_table",
  "projectId": "your_project_id"
}

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

--------------------------------

### Combining $fromAI() with static strings

Source: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function

Use the $fromAI function within a larger expression to combine AI-generated content with static text.

```javascript
Generated by AI: {{ $fromAI("subject") }}
```

--------------------------------

### Add n8n MCP to Claude Code via CLI

Source: https://docs.n8n.io/advanced-ai/mcp/accessing-n8n-mcp-server

Use the Claude CLI to register the n8n MCP server using an HTTP transport.

```bash
claude mcp add --transport http n8n-mcp https://<your-n8n-domain>/mcp-server/http \
  --header "Authorization: Bearer <YOUR_N8N_MCP_TOKEN>"
```

--------------------------------

### execute_workflow

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Execute a workflow by ID by mapping data from user prompt to trigger inputs.

```APIDOC
## execute_workflow

### Description
Execute a workflow by ID by mapping data from user prompt to trigger inputs. Returns execution ID and status. This will perform 'full' workflow execution, without mocking or skipping any nodes.

### Parameters
#### Request Body
- **workflowId** (string) - Required - The ID of the workflow to execute
- **executionMode** ("manual" | "production") - Optional - "manual" tests the current version, "production" executes the published (active) version
- **inputs** (object) - Optional - Inputs to provide to the workflow (chat, form, or webhook types)
```

--------------------------------

### POST /publish_workflow

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Publishes (activates) a workflow to make it available for production execution.

```APIDOC
## POST /publish_workflow

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

### Method
POST

### Endpoint
/publish_workflow

### Parameters
#### Request Body
- **workflowId** (string) - Required - The ID of the workflow to publish
- **versionId** (string) - Optional - Optional version ID to publish. If not provided, publishes the current draft version.

### Response
#### Success Response (200)
- **success** (boolean) - Whether publishing succeeded
- **workflowId** (string) - The workflow ID
- **activeVersionId** (string | null) - The active version ID after publishing
- **error** (string) - Error message if publishing failed
```

--------------------------------

### search_workflows

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Search for workflows with optional filters and retrieve a list of workflow previews.

```APIDOC
## search_workflows

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

### Parameters
#### Query Parameters
- **query** (string) - Optional - Filter by name or description
- **projectId** (string) - Optional - Filter by project ID
- **limit** (integer) - Optional - Limit the number of results (max 200)

### Response
#### Success Response (200)
- **data** (array) - List of workflow previews
- **count** (integer) - Total number of workflows that match the filters
```

--------------------------------

### AI Fill Option for Tool Parameters

Source: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function

Each appropriate parameter field in the tool's editing dialog has an extra button that, when activated, allows the AI Agent to fill in the expression automatically.

```APIDOC
## Let the model fill in the parameter

### Description
Each appropriate parameter field in the tool's editing dialog has an extra button at the end. Activating this button allows the AI Agent to fill in the expression for you automatically. The field will display a message indicating it has been defined by the model. To revert to user-defined values, click the 'X' button. The 'expression' field will retain the AI-generated expression, which can then be manually edited.

### Warning
Activating this feature will overwrite any manual definitions previously added to the field.
```

--------------------------------

### get_workflow_details

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

Retrieve detailed information about a specific workflow, including trigger details and sanitized node data.

```APIDOC
## get_workflow_details

### Description
Get detailed information about a specific workflow including trigger details.

### Parameters
#### Query Parameters
- **workflowId** (string) - Required - The ID of the workflow to retrieve

### Response
#### Success Response (200)
- **workflow** (object) - Sanitized workflow data safe for MCP consumption
- **triggerInfo** (string) - Human-readable instructions describing how to trigger the workflow
```

--------------------------------

### Workflow Management API

Source: https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference

APIs for creating, updating, and archiving workflows in n8n.

```APIDOC
## POST /create_workflow

### Description
Creates a new workflow in n8n. Automatically assigns available credentials to nodes, skips HTTP Request nodes, sets `availableInMCP` to true, and marks the workflow with `aiBuilderAssisted` metadata. Resolves webhook node IDs automatically.

### Method
POST

### Endpoint
/create_workflow

### Parameters
#### Query Parameters
- **name** (string) - Optional - The name of the workflow.
- **folderId** (string) - Optional - The ID of the folder to create the workflow in. Requires `projectId` to also be provided.
- **projectId** (string) - Optional - The ID of the project to create the workflow in. Requires `folderId` to also be provided.

### Request Body
- **code** (string) - Required - Full TypeScript/JavaScript workflow code using the n8n Workflow SDK.

### Request Example
```json
{
  "code": "// Your workflow code here"
}
```

### Response
#### Success Response (200)
- **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
  - **nodeName** (string) - The name of the node that had credentials auto-assigned
  - **credentialName** (string) - The name of the credential that was auto-assigned
- **note** (string) - Additional notes about the workflow creation

#### Response Example
```json
{
  "workflowId": "wf_123",
  "name": "My New Workflow",
  "nodeCount": 5,
  "url": "https://n8n.io/workflows/wf_123",
  "autoAssignedCredentials": [
    {
      "nodeName": "getNode",
      "credentialName": "myCredential"
    }
  ],
  "note": "HTTP Request nodes skipped."
}
```

## PUT /update_workflow

### Description
Updates an existing workflow in n8n from validated SDK code. Parses the code into a workflow and saves the changes. Preserves user-configured credentials by matching nodes by name and type. Marks the workflow with `aiBuilderAssisted` metadata.

### Method
PUT

### Endpoint
/update_workflow

### Parameters
#### Path Parameters
- **workflowId** (string) - Required - The ID of the workflow to update

#### Request Body
- **code** (string) - Required - Full TypeScript/JavaScript workflow code using the n8n Workflow SDK. Must be validated first with `validate_workflow`.
- **name** (string) - Optional - Optional workflow name (max 128 chars). If not provided, uses the name from the code.
- **description** (string) - Optional - Short workflow description (max 255 chars, 1-2 sentences).

### Response
#### Success Response (200)
- **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
- **autoAssignedCredentials** (array) - List of credentials that were automatically assigned to nodes
  - **nodeName** (string) - The name of the node that had credentials auto-assigned
  - **credentialName** (string) - The name of the credential that was auto-assigned
- **note** (string) - Additional notes about the workflow update

#### Response Example
```json
{
  "workflowId": "wf_123",
  "name": "Updated Workflow Name",
  "nodeCount": 6,
  "url": "https://n8n.io/workflows/wf_123",
  "autoAssignedCredentials": [],
  "note": "Credentials preserved."
}
```

## DELETE /archive_workflow

### Description
Archives a workflow in n8n by its ID. This operation is idempotent, meaning it will skip already-archived workflows.

### Method
DELETE

### Endpoint
/archive_workflow

### Parameters
#### Query Parameters
- **workflowId** (string) - Required - The ID of the workflow to archive

### Response
#### Success Response (200)
- **archived** (boolean) - Whether the workflow was archived
- **workflowId** (string) - The ID of the archived workflow
- **name** (string) - The name of the archived workflow

#### Response Example
```json
{
  "archived": true,
  "workflowId": "wf_123",
  "name": "Workflow To Archive"
}
```
```
Tokens:
Raw