### Install n8n using npm

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

Installs the n8n CLI globally using npm and starts the n8n service. This is a common method for users who prefer managing Node.js packages directly.

```bash
npm install n8n -g
n8n start
```

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

### Install n8n using Docker

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

Runs the official n8n Docker image, mapping port 5678 and persisting n8n configuration. This method is suitable for containerized environments and simplifies dependency management.

```bash
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n
```

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

### Workflow Creation with Manual Trigger

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This section describes the creation of workflows that are initiated manually. These workflows cannot be set up for automatic execution and require direct user interaction to start.

```n8n
Can you create a workflow with a manual trigger that fetches a random joke?
```

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

### n8n API Error Handling (JSON)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This JSON example demonstrates an error response from the n8n API, such as a 'Workflow not found' error, as handled and returned by the MCP server.

```json
{
	"error": "n8n API error (404): Workflow not found"
}
```

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

### Activating an n8n Workflow

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This code snippet illustrates the process of activating an n8n workflow. It specifically targets the 'API to Slack' workflow, enabling its automatic execution.

```n8n
Can you activate the "API to Slack" workflow?
```

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

### Configure n8n MCP Server for Claude Desktop App

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

Adds the n8n-workflow-builder to the Claude desktop application's MCP server configuration. It specifies the command to run, arguments, and environment variables for n8n host, API key, and output verbosity.

```json
"n8n-workflow-builder": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-n8n-builder"
  ],
  "env": {
    "N8N_HOST": "https://your-n8n-instance.com/api/v1",
    "N8N_API_KEY": "your-api-key",
    "OUTPUT_VERBOSITY": "concise"
  }
}
```

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

### Workflow Creation with Webhook Trigger

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This section covers the creation of workflows that are triggered by incoming HTTP requests, commonly used for integrating with external services via webhooks, such as GitHub events.

```n8n
Can you create a workflow that listens for GitHub webhook events?
```

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

### n8n API Client Initialization and Usage - TypeScript

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-client-implementation.md

Demonstrates how to instantiate the n8n API client with a base URL and API key, and provides examples of common operations. These include listing, creating, getting, updating, deleting, activating, and deactivating workflows, as well as managing executions.

```typescript
const client = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key',
});

// List all workflows
const workflows = await client.list_workflows();

// Create a new workflow
const workflow = await client.create_workflow({
  name: 'My Workflow',
  nodes: [...],
  connections: {...},
  settings: {...},
}, true);

// Get a workflow
const workflow = await client.get_workflow('workflow-id');

// Update a workflow
const workflow = await client.update_workflow('workflow-id', {
  name: 'My Updated Workflow',
  nodes: [...],
  connections: {...},
  settings: {...},
});

// Delete a workflow
const workflow = await client.delete_workflow('workflow-id');

// Activate a workflow
const workflow = await client.activate_workflow('workflow-id');

// Deactivate a workflow
const workflow = await client.deactivate_workflow('workflow-id');

// List executions
const executions = await client.list_executions({
  workflow_id: 'workflow-id',
  status: 'success',
  limit: 10,
});

// Get an execution
const execution = await client.get_execution('execution-id', true);

// Delete an execution
const execution = await client.delete_execution('execution-id');
```

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

### MCP Configuration for n8n Workflow Builder

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/plan.md

Example JSON configuration for the n8n-workflow-builder within an MCP settings file. This defines the command, arguments, and environment variables for running the builder, facilitating integration with AI assistants without manual installation.

```json
{
	"n8n-workflow-builder": {
		"command": "npx",
		"args": ["-y", "mcp-n8n-builder"],
		"env": {
			"N8N_HOST": "https://examplehost.com/api/v1",
			"N8N_API_KEY": "secretkey",
			"OUTPUT_VERBOSITY": "concise"
		}
	}
}
```

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

### Workflow Creation with Schedule Trigger

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This section details the creation of workflows that run automatically based on a defined schedule. These are suitable for tasks that need to be performed at regular intervals, such as fetching data hourly.

```n8n
Can you create a workflow that runs every hour to fetch weather data?
```

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

### Configure n8n MCP Server for WSL Users

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

Configures the n8n-workflow-builder for Windows Subsystem for Linux (WSL) users. It uses `wsl.exe` to execute the n8n builder command within the Linux environment, passing necessary environment variables.

```json
"n8n-workflow-builder": {
  "command": "wsl.exe",
  "args": [
    "bash",
    "-c",
    "N8N_HOST=https://your-n8n-instance.com/api/v1 N8N_API_KEY=your-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
  ]
}
```

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

### Viewing n8n Workflow Executions

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This code snippet shows how to view the recent executions of a specific n8n workflow. It queries for the execution history of the 'API to Slack' workflow.

```n8n
Can you show me the recent executions of the "API to Slack" workflow?
```

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

### Pagination Example

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-endpoints.md

This example demonstrates how to use the `cursor` query parameter to paginate through API results and how the response includes a `nextCursor` field.

```APIDOC
## GET /workflows

### Description
Retrieves a paginated list of workflows. Use the `cursor` query parameter to fetch subsequent pages of results.

### Method
GET

### Endpoint
/workflows

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - A cursor token provided in the `nextCursor` field of a previous response to retrieve the next page of results.

### Request Example
```
GET /workflows?cursor=MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
```

### Response
#### Success Response (200)
- **data** (array) - An array of workflow objects.
- **nextCursor** (string) - Optional - A cursor token to retrieve the next page of results. Omitted if there are no more results.

#### Response Example
```json
{
  "data": [...],
  "nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}
```
```

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

### n8n Validation Error Handling (JSON)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This JSON example illustrates a validation error returned by the MCP server when data sent to the n8n API is invalid, specifically when a workflow name is missing.

```json
{
	"error": "Validation error: Required at workflow.name"
}
```

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

### Updating an n8n Workflow

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This snippet demonstrates how to update an existing n8n workflow. It focuses on modifying a specific workflow, 'API to Slack', to incorporate error handling capabilities.

```n8n
Can you update the "API to Slack" workflow to add error handling?
```

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

### n8n API: GET Request with Pagination Cursor

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-endpoints.md

Demonstrates how to make a GET request to an n8n API endpoint with a cursor for paginated results. The `cursor` parameter is used to specify the starting point for retrieving the next set of data.

```http
GET /workflows?cursor=MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
```

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

### Deleting an n8n Workflow

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This code snippet demonstrates the deletion of an n8n workflow. It targets the workflow named 'Test Workflow' for removal.

```n8n
Can you delete the "Test Workflow" workflow?
```

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

### Get n8n Execution Details (TypeScript)

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Illustrates how to retrieve detailed information for a specific n8n workflow execution using its ID. It shows how to fetch either a lightweight summary or the full execution data, including payloads, which can be token-intensive. The N8nApiClient must be initialized with connection details.

```typescript
import { N8nApiClient } from './n8n-api-client.js';

const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key'
});

const executionId = '456';

// Get execution metadata only (lightweight)
const executionSummary = await apiClient.get_execution(executionId, false);
console.log(`Status: ${executionSummary.status}`);
console.log(`Duration: ${ 
  new Date(executionSummary.stoppedAt).getTime() -
  new Date(executionSummary.startedAt).getTime()
} ms`);

// Get full execution with all data payloads (token-heavy)
const executionFull = await apiClient.get_execution(executionId, true);
console.log('Execution data:');
executionFull.data.resultData.runData.forEach((nodeData, nodeName) => {
  console.log(`${nodeName}:`, nodeData);
});
```

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

### List Workflows (GET /workflows)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves a list of workflows. Supports filtering by `active` status, `tags`, and `name`. The response includes workflow data and a cursor for pagination.

```http
GET /workflows?active=true&tags=Production,Development
```

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

### GET /workflows

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Retrieve all workflows from your n8n instance with optional filtering by status, tags, or name.

```APIDOC
## GET /workflows

### Description
Retrieve all workflows from your n8n instance with optional filtering by status, tags, or name.

### Method
GET

### Endpoint
/workflows

### Query Parameters
- **active** (boolean) - Optional - Filter workflows by their active status.
- **tags** (string) - Optional - Filter workflows by a specific tag.
- **name** (string) - Optional - Filter workflows by their name.

### Request Example
```typescript
import { N8nApiClient } from './n8n-api-client.js';

const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key'
});

// List all workflows
const allWorkflows = await apiClient.list_workflows();

// Filter by active status
const activeWorkflows = await apiClient.list_workflows({ active: true });

// Filter by tags
const taggedWorkflows = await apiClient.list_workflows({ tags: 'production' });

// Filter by name
const namedWorkflows = await apiClient.list_workflows({ name: 'Daily Report' });
```

### Response
#### Success Response (200)
- **workflows** (array) - An array of workflow objects.
  - **id** (string) - The unique identifier of the workflow.
  - **name** (string) - The name of the workflow.
  - **active** (boolean) - The active status of the workflow.
  - **created_at** (string) - The timestamp when the workflow was created.
  - **updated_at** (string) - The timestamp when the workflow was last updated.
  - **tags** (array) - An array of tag objects associated with the workflow.
    - **name** (string) - The name of the tag.
  - **nodes** (array) - An array of node objects within the workflow.
  - **connections** (object) - An object representing the connections between nodes.

#### Response Example
```json
[
  {
    "id": "123",
    "name": "My Workflow",
    "active": true,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-02T00:00:00.000Z",
    "tags": [{"name": "production"}],
    "nodes": [...],
    "connections": {}
  }
]
```
```

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

### Get Workflow (GET /workflows/{id})

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves details of a specific workflow by its ID. The response includes the workflow's configuration, including its name, nodes, connections, and settings.

```http
GET /workflows/2tUt1wbLX592XDdX
```

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

### List Executions (GET /executions)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves a list of workflow executions. Supports filtering by `workflowId`, `status`, and `limit`. The response includes execution data and a cursor for pagination.

```http
GET /executions?workflowId=2tUt1wbLX592XDdX&status=success&limit=10
```

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

### GET /workflows

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves a list of workflows. Can be filtered by active status, tags, or name.

```APIDOC
## GET /workflows

### Description
Retrieves a list of workflows. Can be filtered by active status, tags, or name.

### Method
GET

### Endpoint
/workflows

### Query Parameters
- **active** (boolean) - Optional - Filter by active status
- **tags** (string) - Optional - Filter by tags (comma-separated)
- **name** (string) - Optional - Filter by workflow name

### Response
#### Success Response (200)
- **data** (array) - An array of workflow objects.
  - **id** (string) - The unique identifier of the workflow.
  - **name** (string) - The name of the workflow.
  - **active** (boolean) - Indicates if the workflow is active.
  - **createdAt** (string) - The timestamp when the workflow was created.
  - **updatedAt** (string) - The timestamp when the workflow was last updated.
  - **tags** (array) - An array of tag objects associated with the workflow.
- **nextCursor** (string) - A cursor for paginating through results.

#### Response Example
```json
{
	"data": [
		{
			"id": "2tUt1wbLX592XDdX",
			"name": "Workflow 1",
			"active": true,
			"createdAt": "2019-08-24T14:15:22Z",
			"updatedAt": "2019-08-24T14:15:22Z",
			"tags": [
				{
					"id": "2tUt1wbLX592XDdX",
					"name": "Production"
				}
			]
		}
	],
	"nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}
```
```

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

### GET /workflows/{workflowId}

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Retrieve complete details of a specific workflow including all nodes, connections, and metadata.

```APIDOC
## GET /workflows/{workflowId}

### Description
Retrieve complete details of a specific workflow including all nodes, connections, and metadata.

### Method
GET

### Endpoint
/workflows/{workflowId}

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

### Request Example
```typescript
import { N8nApiClient } from './n8n-api-client.js';

const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key'
});

try {
  const workflowId = '123';
  const workflow = await apiClient.get_workflow(workflowId);

  console.log(`Workflow: ${workflow.name}`);
  console.log(`Status: ${workflow.active ? 'Active' : 'Inactive'}`);
  console.log(`Nodes: ${workflow.nodes.length}`);
  console.log(`Created: ${workflow.created_at}`);

  // Access nodes and connections
  workflow.nodes.forEach(node => {
    console.log(`- ${node.name} (${node.type})`);
  });

} catch (error) {
  console.error('Failed to retrieve workflow:', error.message);
}
```

### Response
#### Success Response (200)
- **workflow** (object) - The detailed workflow object.
  - **id** (string) - The unique identifier of the workflow.
  - **name** (string) - The name of the workflow.
  - **active** (boolean) - The active status of the workflow.
  - **created_at** (string) - The timestamp when the workflow was created.
  - **updated_at** (string) - The timestamp when the workflow was last updated.
  - **tags** (array) - An array of tag objects associated with the workflow.
  - **nodes** (array) - An array of node objects within the workflow.
    - **id** (string) - Unique identifier for the node.
    - **name** (string) - The name of the node.
    - **type** (string) - The type of the node.
    - **position** (array) - The position of the node on the canvas [x, y].
    - **parameters** (object) - Parameters for the node.
  - **connections** (object) - An object representing the connections between nodes.

#### Response Example
```json
{
  "id": "123",
  "name": "My Workflow",
  "active": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-02T00:00:00.000Z",
  "tags": [{"name": "production"}],
  "nodes": [
    {
      "id": "trigger-1",
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300],
      "parameters": {}
    },
    {
      "id": "http-1",
      "name": "Fetch Data",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300],
      "parameters": {
        "url": "https://api.example.com/data",
        "method": "GET",
        "responseFormat": "json"
      }
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [
        [
          {
            "node": "Fetch Data",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}
```

#### Error Response (404)
- **message** (string) - Error message indicating the workflow was not found.
```

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

### GET /executions

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves a list of workflow executions. Can be filtered by workflow ID, status, and a limit on the number of results.

```APIDOC
## GET /executions

### Description
Retrieves a list of workflow executions. Can be filtered by workflow ID, status, and a limit on the number of results.

### Method
GET

### Endpoint
/executions

### Query Parameters
- **workflowId** (string) - Optional - Filter by workflow ID.
- **status** (string) - Optional - Filter by status (e.g., 'error', 'success', 'waiting').
- **limit** (number) - Optional - Maximum number of executions to return.

### Response
#### Success Response (200)
- **data** (array) - An array of execution objects.
  - **id** (number) - The unique identifier of the execution.
  - **finished** (boolean) - Indicates if the execution has finished.
  - **mode** (string) - The mode of execution (e.g., 'manual').
  - **startedAt** (string) - The timestamp when the execution started.
  - **stoppedAt** (string) - The timestamp when the execution stopped.
  - **workflowId** (string) - The ID of the workflow associated with the execution.
  - **workflowData** (object) - Data about the workflow.
    - **id** (string) - The workflow ID.
    - **name** (string) - The workflow name.
- **nextCursor** (string) - A cursor for paginating through results.

#### Response Example
```json
{
	"data": [
		{
			"id": 1000,
			"finished": true,
			"mode": "manual",
			"startedAt": "2019-08-24T14:15:22Z",
			"stoppedAt": "2019-08-24T14:15:22Z",
			"workflowId": "2tUt1wbLX592XDdX",
			"workflowData": {
				"id": "2tUt1wbLX592XDdX",
				"name": "Workflow 1"
			}
		}
	],
	"nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}
```
```

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

### Get Workflow Details (TypeScript)

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Retrieves detailed information for a specific n8n workflow using its ID via the N8nApiClient. Includes all nodes, connections, and metadata such as name, status, creation date, and node types.

```typescript
import { N8nApiClient } from './n8n-api-client.js';

const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key'
});

try {
  const workflowId = '123';
  const workflow = await apiClient.get_workflow(workflowId);

  console.log(`Workflow: ${workflow.name}`);
  console.log(`Status: ${workflow.active ? 'Active' : 'Inactive'}`);
  console.log(`Nodes: ${workflow.nodes.length}`);
  console.log(`Created: ${workflow.created_at}`);

  // Access nodes and connections
  workflow.nodes.forEach(node => {
    console.log(`- ${node.name} (${node.type})`);
  });

} catch (error) {
  console.error('Failed to retrieve workflow:', error.message);
}
```

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

### List Executions with Options - TypeScript

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-client-implementation.md

Retrieves a list of workflow executions from n8n. This method supports filtering by workflow ID, status, and limit via an optional options object. It constructs a query string for the GET request to the /executions endpoint.

```typescript
async list_executions(options?: ListExecutionsOptions): Promise<any> {
  let endpoint = '/executions';

  if (options) {
    const params = new URLSearchParams();

    if (options.workflow_id) {
      params.append('workflowId', options.workflow_id);
    }

    if (options.status) {
      params.append('status', options.status);
    }

    if (options.limit) {
      params.append('limit', String(options.limit));
    }

    const query_string = params.toString();
    if (query_string) {
      endpoint += `?${query_string}`;
    }
  }

  const response = await this.request<any>('GET', endpoint);
  return response.data || response;
}
```

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

### Control n8n Output Verbosity for Token Management (TypeScript)

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Explains how to manage token consumption by controlling the verbosity of n8n API responses. It shows setting global verbosity via environment variables and overriding it per tool call for specific functions like listing or getting workflows. Supports 'concise' and 'full' modes.

```typescript
// Configure global verbosity via environment variable
process.env.OUTPUT_VERBOSITY = 'concise'; // or 'full'

// Override verbosity per tool call
const workflows = await handle_list_workflows(apiClient, {
  verbosity: 'concise' // Returns summary only
});

const workflowFull = await handle_get_workflow(apiClient, {
  id: '123',
  verbosity: 'full' // Returns complete JSON
});

// Concise mode returns:
// - Workflow summaries (ID, name, status, node count, tags)
// - Execution summaries (ID, status, duration, workflow name)
// - Essential metadata only

// Full mode returns:
// - Complete JSON structures
// - All nodes with parameters
// - All connections
// - Complete execution data
```

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

### Validate n8n Nodes and Get Suggestions

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Validates single node types or entire workflows against available n8n instances. It provides smart suggestions for invalid node types and can retrieve lists of all available node types and detailed node information. This utility helps ensure the integrity of n8n configurations.

```typescript
import { node_validator } from './node-validator.js';

// Validate a single node type
const validation = await node_validator.validate_node_type(
  'n8n-nodes-base.httpRequest'
);

if (validation.valid) {
  console.log('Node type is valid');
} else {
  console.log('Invalid node type');
  if (validation.suggestion) {
    console.log(`Did you mean: ${validation.suggestion}?`);
  }
}

// Validate all nodes in a workflow
const workflowNodes = [
  { type: 'n8n-nodes-base.manualTrigger' },
  { type: 'n8n-nodes-base.httpReques' }, // Typo
  { type: 'n8n-nodes-base.set' }
];

const invalidNodes = await node_validator.validate_workflow_nodes(workflowNodes);

if (invalidNodes.length > 0) {
  console.log('Invalid nodes found:');
  invalidNodes.forEach(node => {
    console.log(`- ${node.node_type}`);
    if (node.suggestion) {
      console.log(`  Suggestion: ${node.suggestion}`);
    }
  });
}

// Get list of all available node types
const availableTypes = await node_validator.get_available_node_types();
console.log(`Available nodes: ${availableTypes.length}`);

// Get detailed node information
const availableNodes = await node_validator.get_available_nodes();
availableNodes.forEach(node => {
  console.log(`${node.name}: ${node.display_name}`);
  if (node.description) {
    console.log(`  ${node.description}`);
  }
});
```

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

### Deactivating an n8n Workflow

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/setup-guide.md

This code snippet shows how to deactivate an n8n workflow. It targets the 'API to Slack' workflow, disabling its automatic execution.

```n8n
Can you deactivate the "API to Slack" workflow?
```

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

### POST /workflows

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Create a new workflow with nodes and connections, optionally activating it immediately.

```APIDOC
## POST /workflows

### Description
Create a new workflow with nodes and connections, optionally activating it immediately.

### Method
POST

### Endpoint
/workflows

### Parameters
#### Request Body
- **workflow** (object) - Required - The structure of the workflow to create.
  - **name** (string) - Required - The name of the workflow.
  - **nodes** (array) - Required - An array of node objects for the workflow.
    - **id** (string) - Required - Unique identifier for the node.
    - **name** (string) - Required - The name of the node.
    - **type** (string) - Required - The type of the node (e.g., 'n8n-nodes-base.manualTrigger').
    - **position** (array) - Required - The position of the node on the canvas [x, y].
    - **parameters** (object) - Optional - Parameters for the node.
  - **connections** (object) - Required - An object defining the connections between nodes.
  - **settings** (object) - Optional - Settings for the workflow.
    - **saveExecutionProgress** (boolean) - Optional - Whether to save execution progress.
    - **saveManualExecutions** (boolean) - Optional - Whether to save manual executions.
- **activate** (boolean) - Optional - Whether to activate the workflow immediately after creation. Defaults to false.

### Request Example
```typescript
import { N8nApiClient } from './n8n-api-client.js';

const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-api-key'
});

// Define workflow structure
const workflow = {
  name: 'HTTP Request Example',
  nodes: [
    {
      id: 'trigger-1',
      name: 'Manual Trigger',
      type: 'n8n-nodes-base.manualTrigger',
      position: [250, 300],
      parameters: {}
    },
    {
      id: 'http-1',
      name: 'Fetch Data',
      type: 'n8n-nodes-base.httpRequest',
      position: [450, 300],
      parameters: {
        url: 'https://api.example.com/data',
        method: 'GET',
        responseFormat: 'json'
      }
    }
  ],
  connections: {
    'Manual Trigger': {
      main: [
        [
          {
            node: 'Fetch Data',
            type: 'main',
            index: 0
          }
        ]
      ]
    }
  },
  settings: {
    saveExecutionProgress: true,
    saveManualExecutions: true
  }
};

// Create workflow without activation
const createdWorkflow = await apiClient.create_workflow(workflow);
console.log(`Created workflow ID: ${createdWorkflow.id}`);

// Create and activate workflow
const activeWorkflow = await apiClient.create_workflow(workflow, true);
console.log(`Created and activated workflow ID: ${activeWorkflow.id}`);
```

### Response
#### Success Response (200 or 201)
- **workflow** (object) - The created workflow object.
  - **id** (string) - The unique identifier of the newly created workflow.
  - **name** (string) - The name of the workflow.
  - **active** (boolean) - The active status of the workflow.
  - **created_at** (string) - The timestamp when the workflow was created.
  - **updated_at** (string) - The timestamp when the workflow was last updated.
  - **tags** (array) - An array of tag objects associated with the workflow.
  - **nodes** (array) - An array of node objects within the workflow.
  - **connections** (object) - An object representing the connections between nodes.

#### Response Example
```json
{
  "id": "new-workflow-id",
  "name": "HTTP Request Example",
  "active": false,
  "created_at": "2025-01-03T10:00:00.000Z",
  "updated_at": "2025-01-03T10:00:00.000Z",
  "tags": [],
  "nodes": [...],
  "connections": {}
}
```
```

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

### N8nApiClient Configuration

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Initializes the n8n API client to connect to your n8n instance with authentication.

```APIDOC
## N8nApiClient Configuration

### Description
Initialize the n8n API client to connect to your n8n instance with authentication.

### Method
Initialization (Not an HTTP endpoint, but a client setup)

### Endpoint
N/A

### Parameters
#### Initialization Parameters
- **base_url** (string) - Required - The base URL of your n8n instance.
- **api_key** (string) - Required - Your n8n API key for authentication.

### Request Example
```typescript
import { N8nApiClient } from './n8n-api-client.js';

// Create API client instance
const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-n8n-api-key-here'
});

// The client automatically handles authentication headers
// and provides typed methods for all n8n API operations
```
```

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

### Set up MCP Server with n8n Integration

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Initializes and runs the Model Context Protocol (MCP) server, integrating it with an n8n instance. It configures API clients, sets up resource and tool handlers, and implements error handling for server operations. The server listens on stdio for communication.

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { N8nApiClient } from './n8n-api-client.js';
import { setup_resource_handlers } from './resource-handlers.js';
import { setup_tool_handlers } from './tool-handlers/index.js';

// Configuration
const config = {
  n8n_host: process.env.N8N_HOST || 'http://localhost:5678/api/v1',
  n8n_api_key: process.env.N8N_API_KEY || '',
  server_name: 'n8n-workflow-builder',
  server_version: '0.0.4',
  output_verbosity: process.env.OUTPUT_VERBOSITY || 'concise'
};

// Create server
const server = new Server(
  {
    name: config.server_name,
    version: config.server_version
  },
  {
    capabilities: {
      resources: {},
      tools: {}
    }
  }
);

// Create API client
const apiClient = new N8nApiClient({
  base_url: config.n8n_host,
  api_key: config.n8n_api_key
});

// Setup handlers
setup_resource_handlers(server, apiClient);
setup_tool_handlers(server, apiClient);

// Error handling
server.onerror = (error) => console.error('[MCP Error]', error);
process.on('SIGINT', async () => {
  await server.close();
  process.exit(0);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error(`${config.server_name} MCP server running on stdio`);
```

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

### POST /workflows

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Creates a new workflow with the provided name, nodes, connections, and settings.

```APIDOC
## POST /workflows

### Description
Creates a new workflow with the provided name, nodes, connections, and settings.

### Method
POST

### Endpoint
/workflows

### Request Body
- **name** (string) - Required - The name of the workflow.
- **nodes** (array) - Required - An array of node objects defining the workflow structure.
- **connections** (object) - Required - An object defining the connections between nodes.
- **settings** (object) - Optional - An object for workflow settings.
  - **saveExecutionProgress** (boolean) - Whether to save execution progress.
  - **saveManualExecutions** (boolean) - Whether to save manual executions.
  - **saveDataErrorExecution** (string) - How to save data for error executions (e.g., 'all').
  - **saveDataSuccessExecution** (string) - How to save data for successful executions (e.g., 'all').
  - **executionTimeout** (number) - The timeout for workflow execution in seconds.
  - **timezone** (string) - The timezone for the workflow.

### Request Example
```json
{
	"name": "Workflow 1",
	"nodes": [
		{
			"id": "1",
			"name": "Start",
			"type": "n8n-nodes-base.start",
			"position": [100, 100],
			"parameters": {}
		}
	],
	"connections": {
		"Start": {
			"main": [
				[
					{
						"node": "End",
						"type": "main",
						"index": 0
					}
				]
			]
		}
	},
	"settings": {
		"saveExecutionProgress": true,
		"saveManualExecutions": true,
		"saveDataErrorExecution": "all",
		"saveDataSuccessExecution": "all",
		"executionTimeout": 3600,
		"timezone": "America/New_York"
	}
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created workflow.
- **name** (string) - The name of the workflow.
- **active** (boolean) - Indicates if the workflow is active.
- **createdAt** (string) - The timestamp when the workflow was created.
- **updatedAt** (string) - The timestamp when the workflow was last updated.
- **nodes** (array) - An array of node objects.
- **connections** (object) - An object defining the connections between nodes.
- **settings** (object) - An object for workflow settings.
- **tags** (array) - An array of tag objects.

#### Response Example
```json
{
  "id": "2tUt1wbLX592XDdX",
  "name": "Workflow 1",
  "active": false,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "nodes": [...],
  "connections": {...},
  "settings": {...},
  "tags": []
}
```
```

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

### Configure MCP Client with npm

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Configures the MCP server for the 'n8n-workflow-builder' in environments like Claude Desktop or Cline using npm. This JSON configuration specifies the command to run, arguments, and environment variables, including n8n connection details.

```json
{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["-y", "mcp-n8n-builder"],
      "env": {
        "N8N_HOST": "http://localhost:5678/api/v1",
        "N8N_API_KEY": "your-n8n-api-key",
        "OUTPUT_VERBOSITY": "concise"
      }
    }
  }
}
```

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

### Configure n8n MCP Server in Claude Desktop

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/using-with-claude.md

This JSON configuration snippet is added to the Claude desktop configuration file to enable the n8n Workflow Builder MCP server. It specifies the command to run the Node.js script, its arguments, and environment variables for connecting to the n8n API.

```json
{
  "n8n-workflow-builder": {
    "command": "node",
    "args": ["/path/to/mcp-n8n-builder/dist/index.js"],
    "env": {
      "N8N_HOST": "http://localhost:5678/api/v1",
      "N8N_API_KEY": "your-api-key"
    }
  }
}
```

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

### Get Workflow Endpoint (GET /workflows/{id})

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-endpoints.md

Retrieves a specific workflow by its ID. Returns a JSON object representing the workflow details.

```http
GET /workflows/{id}
```

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

### Access n8n Resources via MCP URIs (TypeScript)

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Demonstrates how to use the MCP client to read n8n workflow and execution data using standardized resource URIs. It covers listing all workflows, retrieving specific workflow details, and fetching execution data. No external dependencies beyond the MCP client are explicitly shown.

```typescript
// Resource URIs available:
// - n8n://workflows - List all workflows
// - n8n://workflows/{id} - Get specific workflow details
// - n8n://executions/{id} - Get specific execution details

// Example: Reading workflows resource
const workflowsResource = await mcpClient.readResource({
  uri: 'n8n://workflows'
});
// Returns JSON array of all workflows

// Example: Reading specific workflow
const workflowResource = await mcpClient.readResource({
  uri: 'n8n://workflows/123'
});
// Returns JSON object with complete workflow data

// Example: Reading execution details
const executionResource = await mcpClient.readResource({
  uri: 'n8n://executions/456'
});
// Returns JSON object with execution data
```

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

### Get Execution (GET /executions/{id})

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves details of a specific workflow execution by its ID. An optional `includeData` query parameter can be used to include execution data in the response.

```http
GET /executions/1000?includeData=true
```

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

### Configure n8n API Client (TypeScript)

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Initializes the N8nApiClient to connect to an n8n instance using a base URL and API key. The client handles authentication headers and provides typed methods for API operations.

```typescript
import { N8nApiClient } from './n8n-api-client.js';

// Create API client instance
const apiClient = new N8nApiClient({
  base_url: 'http://localhost:5678/api/v1',
  api_key: 'your-n8n-api-key-here'
});

// The client automatically handles authentication headers
// and provides typed methods for all n8n API operations
```

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

### Configure MCP Client with WSL

Source: https://context7.com/spences10/mcp-n8n-builder/llms.txt

Configures the MCP server for the 'n8n-workflow-builder' using Windows Subsystem for Linux (WSL). This JSON configuration details the command to execute within WSL, including setting environment variables for n8n connection and output verbosity.

```json
{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "N8N_HOST=http://localhost:5678/api/v1 N8N_API_KEY=your-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
      ]
    }
  }
}
```

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

### Get Workflow Method (TypeScript)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-client-implementation.md

Retrieves a specific n8n workflow by its unique ID. This method makes a GET request to the /workflows/{id} endpoint.

```typescript
async get_workflow(id: string): Promise<any> {
  return this.request<any>('GET', `/workflows/${id}`);
}
```

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

### Get Execution Endpoint (GET /executions/{id})

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-endpoints.md

Retrieves a specific workflow execution by its ID. Supports an `includeData` query parameter to optionally include execution data. Returns a JSON object representing the execution details.

```http
GET /executions/{id}
```

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

### Get Execution by ID with Data Option - TypeScript

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/n8n-api-client-implementation.md

Retrieves a specific workflow execution by its ID. An optional boolean parameter `include_data` can be provided to determine if the execution's data should be returned. It constructs the GET request endpoint accordingly.

```typescript
async get_execution(id: string, include_data?: boolean): Promise<any> {
  let endpoint = `/executions/${id}`;

  if (include_data !== undefined) {
    endpoint += `?includeData=${include_data}`;
  }

  return this.request<any>('GET', endpoint);
}
```

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

### Create Workflow (POST /workflows)

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Creates a new workflow with specified nodes, connections, and settings. The request body must be a JSON object containing the workflow's name, nodes, connections, and settings. The response returns the created workflow object.

```json
{
	"name": "Workflow 1",
	"nodes": [
		{
			"id": "1",
			"name": "Start",
			"type": "n8n-nodes-base.start",
			"position": [100, 100],
			"parameters": {}
		}
	],
	"connections": {
		"Start": {
			"main": [
				[
					{
						"node": "End",
						"type": "main",
						"index": 0
					}
				]
			]
		}
	},
	"settings": {
		"saveExecutionProgress": true,
		"saveManualExecutions": true,
		"saveDataErrorExecution": "all",
		"saveDataSuccessExecution": "all",
		"executionTimeout": 3600,
		"timezone": "America/New_York"
	}
}
```

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

### GET /workflows/{id}

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/docs/api-reference.md

Retrieves details of a specific workflow by its ID.

```APIDOC
## GET /workflows/{id}

### Description
Retrieves details of a specific workflow by its ID.

### Method
GET

### Endpoint
/workflows/{id}

#### Path Parameters
- **id** (string) - Required - The unique identifier of the workflow.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the workflow.
- **name** (string) - The name of the workflow.
- **active** (boolean) - Indicates if the workflow is active.
- **createdAt** (string) - The timestamp when the workflow was created.
- **updatedAt** (string) - The timestamp when the workflow was last updated.
- **nodes** (array) - An array of node objects.
- **connections** (object) - An object defining the connections between nodes.
- **settings** (object) - An object for workflow settings.
- **tags** (array) - An array of tag objects.

#### Response Example
```json
{
  "id": "2tUt1wbLX592XDdX",
  "name": "Workflow 1",
  "active": true,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "nodes": [...],
  "connections": {...},
  "settings": {...},
  "tags": [...] 
}
```
```

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

### Configure n8n-workflow-builder for Claude Desktop with WSL

Source: https://github.com/spences10/mcp-n8n-builder/blob/main/README.md

This JSON configuration snippet illustrates how to integrate the n8n-workflow-builder with Claude Desktop when using a Windows Subsystem for Linux (WSL) environment. It defines the execution command, including setting n8n API credentials and output verbosity via environment variables within the bash command.

```json
{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"N8N_HOST=http://localhost:5678/api/v1 N8N_API_KEY=your-n8n-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
			]
		}
	}
}
```