Skip to main content
Glama

n8n MCP Server

by get2knowio

n8n-mcp

CI/CD Release Coverage Status npm version License: MIT

An MCP (Model Context Protocol) server for managing n8n workflows. This server allows AI agents to create, retrieve, update, and manage n8n workflows through the n8n API.

Features

Workflow Management

  • List Workflows: Get all workflows from your n8n instance

  • Get Workflow: Retrieve a specific workflow by ID

  • Create Workflow: Create new workflows with nodes and connections

  • Update Workflow: Modify existing workflows

  • Delete Workflow: Remove workflows

  • Activate/Deactivate: Control workflow execution state

  • Credential Management: List credentials and resolve credential aliases

  • Credential Aliasing: Use human-friendly names for credentials in workflows

  • Source Control: Pull changes from source control to sync with remote

  • Get Credential Schema: Fetch JSON schema for credential types to validate or drive UIs

  • Transfer Workflows: Move workflows across projects or owners

  • Transfer Credentials: Move credentials across projects or owners

  • List Executions: Get workflow executions with pagination support

  • Get Execution: Retrieve specific execution details by ID

  • Delete Execution: Remove execution records

Tags Management

  • Tags CRUD: Create, read, update, and delete tags with pagination support

  • List Tags: Get all tags with optional pagination

  • Create Tag: Create new tags with name and optional color

  • Update Tag: Update existing tag name and/or color

  • Delete Tag: Remove tags by ID

Variables Management

  • List Variables: Get all variables with pagination support

  • Create Variable: Create new key-value variables (enforces unique keys)

  • Update Variable: Modify existing variable values

  • Delete Variable: Remove variables

  • CLI & MCP Support: Full access via both command line and MCP tools

Installation

From npm (recommended)

npm install @get2knowio/n8n-mcp

From Source

git clone https://github.com/get2knowio/n8n-mcp.git cd n8n-mcp npm install // See CONTRIBUTING.md for the full local dev workflow and build steps

Configuration

Set the following environment variables:

Option 1: API Key Authentication

export N8N_BASE_URL=http://localhost:5678 export N8N_API_KEY=your_api_key_here

Option 2: Basic Authentication

export N8N_BASE_URL=http://localhost:5678 export N8N_USERNAME=your_username export N8N_PASSWORD=your_password

Usage

1) As an MCP Server (recommended)

Run the MCP server (recommended) — unified entrypoint:

# Global install npm i -g @get2knowio/n8n-mcp # Start server on stdio n8n-mcp # Or without global install npx @get2knowio/n8n-mcp

This starts the MCP server on stdio for integration with AI agents. Configure access via environment variables (see Configuration).

2) As a CLI Tool

The CLI binary is n8n-mcp. After a global install:

# Global install npm i -g @get2knowio/n8n-mcp # List workflows n8n-mcp list # With pagination n8n-mcp list --limit 25 --cursor NEXT_CURSOR # Get a workflow n8n-mcp get 1 # Create from JSON n8n-mcp create examples/example-workflow.json # Activate / Deactivate n8n-mcp activate 1 n8n-mcp deactivate 1 # Variables n8n-mcp variables list n8n-mcp variables create --key mykey --value myvalue n8n-mcp variables update var-123 --value newvalue n8n-mcp variables delete var-123 # Executions n8n-mcp executions list n8n-mcp executions get exec_123 n8n-mcp executions delete exec_123 # Tags n8n-mcp tags list n8n-mcp tags get 1 n8n-mcp tags create "My Tag" "#ff0000" n8n-mcp tags update 1 "Updated Tag" "#00ff00" n8n-mcp tags delete 1 # Webhook URLs n8n-mcp webhook-urls 1 webhook-node-id # Run once (optionally with input) n8n-mcp run-once 1 n8n-mcp run-once 1 input-data.json

CLI Output Format

  • All commands emit structured JSON to stdout by default.

  • Success shape: { "ok": true, "data": <payload>, "meta"?: { ... } }

  • Error shape: { "ok": false, "error": { "message": string, "code"?: string, "details"?: any } } with non-zero exit.

  • Flags:

    • --compact prints single-line JSON (pretty is default).

    • --verbose enables debug logging to stderr without affecting stdout JSON.

  • IDs: Workflow IDs may be strings or numbers; the CLI accepts either.

Examples:

# List (pretty JSON) n8n-mcp list --limit 1 # => { "ok": true, "data": { "data": [ ... ], "nextCursor": "..." } } # Get (compact JSON) n8n-mcp --compact get i47DndfezvDVfrVx # => {"ok":true,"data":{"id":"i47DndfezvDVfrVx", ...}} # Errors return ok:false and exit 1 n8n-mcp get # => { "ok": false, "error": { "message": "Workflow ID required", "code": "BAD_INPUT" } }

Use npx if you prefer not to install globally:

npx @get2knowio/n8n-mcp list

For local development (npm scripts, running from source), see CONTRIBUTING.md.

MCP client configuration examples

You can point any MCP-capable client at the n8n-mcp command. Two ready-to-copy examples are provided in the examples/ folder.

Claude Desktop (macOS/Windows/Linux)

Place this in your Claude Desktop config (see Anthropic docs for the exact path):

{ "mcpServers": { "n8n-mcp": { "command": "npx", "args": ["-y", "-p", "@get2knowio/n8n-mcp"], "env": { "N8N_BASE_URL": "http://localhost:5678", "N8N_API_KEY": "your_api_key_here" } } } }

Example file: examples/mcp-client-claude-desktop.json

Generic MCP client

{ "servers": [ { "name": "n8n-mcp", "command": "npx", "args": ["-y", "-p", "@get2knowio/n8n-mcp"], "env": { "N8N_BASE_URL": "http://localhost:5678", "N8N_API_KEY": "your_api_key_here" } } ] }

Example file: examples/mcp-client-generic.json

VS Code MCP (Troubleshooting)

Some environments require an explicit npx invocation so the package is available on PATH at startup. If you see errors like sh: 1: n8n-mcp: not found, configure VS Code MCP to use the following form which installs the package on-demand and runs the server:

{ "servers": { "n8n-mcp": { "type": "stdio", "command": "npx", "args": [ "-y", "-p", "@get2knowio/n8n-mcp@<version>" ], "env": { "N8N_BASE_URL": "${input:n8n_base_url}", "N8N_API_KEY": "${input:n8n_api_key}" } } } }

Alternatively, install globally and reference the binary directly:

npm i -g @get2knowio/n8n-mcp@<version>

Then set command to npx with args ["-y", "-p", "@get2knowio/n8n-mcp@<version>"] or, after global install, use n8n-mcp.

Available Tools

Workflow Tools

  1. list_workflows - List all workflows

  2. get_workflow - Get workflow by ID

  3. create_workflow - Create a new workflow

  4. update_workflow - Update existing workflow (supports optional optimistic concurrency)

  5. delete_workflow - Delete a workflow

  6. activate_workflow - Activate a workflow

  7. deactivate_workflow - Deactivate a workflow

  8. deactivate_workflow - Deactivate a workflow

  9. list_credentials - List all credentials

  10. resolve_credential_alias - Resolve a credential alias to its ID

  11. source_control_pull - Pull changes from source control

  12. get_credential_schema - Get JSON schema for a credential type

  13. list_workflow_tags - List tags for a specific workflow

  14. set_workflow_tags - Set tags for a specific workflow

  15. transfer_workflow - Transfer a workflow to a different project or owner

  16. transfer_credential - Transfer a credential to a different project or owner

  17. list_executions - List workflow executions with pagination

  18. get_execution - Get execution by ID

  19. delete_execution - Delete an execution

  20. webhook_urls - Get webhook URLs for a webhook node

  21. run_once - Execute a workflow manually once

Variables Tools

  1. list_variables - List all variables with pagination support

  2. create_variable - Create a new variable (requires unique key)

  3. update_variable - Update an existing variable value

  4. delete_variable - Delete a variable

Tag Tools

  1. list_tags - List all tags with optional pagination

  2. get_tag - Get tag by ID

  3. create_tag - Create a new tag

  4. update_tag - Update existing tag

  5. delete_tag - Delete a tag

Optimistic Concurrency for Updates

The update_workflow tool supports optional optimistic concurrency control via the ifMatch parameter:

{ "id": 1, "name": "Updated Workflow Name", "ifMatch": "W/\"1234567890\"" }

When ifMatch is provided:

  • The request includes an If-Match header with the provided value

  • If the workflow has been modified by another user (412 Precondition Failed), you'll receive a clear error message

  • This helps prevent conflicting updates in multi-user environments

Example Workflow Creation

Basic Workflow with Credential IDs

{ "name": "Example Workflow", "nodes": [ { "id": "webhook", "name": "Webhook", "type": "n8n-nodes-base.webhook", "typeVersion": 1, "position": [250, 300], "parameters": { "httpMethod": "GET", "path": "example" } } ], "connections": {}, "active": false, "tags": ["example"] }

Workflow with Credential Aliases

You can now use human-friendly credential names instead of IDs:

{ "name": "HTTP Request Workflow", "nodes": [ { "id": "http-request", "name": "HTTP Request", "type": "n8n-nodes-base.httpRequest", "typeVersion": 1, "position": [250, 300], "parameters": { "url": "https://api.example.com/data", "method": "GET" }, "credentials": { "httpBasicAuth": "my-api-credentials" } } ], "connections": {}, "active": false, "tags": ["example", "api"] }

The system will automatically resolve "my-api-credentials" to the appropriate credential ID before creating or updating the workflow.

Credential Management

Listing Credentials

Use the list_credentials tool to see all available credentials in your n8n instance:

# Through MCP tools { "tool": "list_credentials", "arguments": {} }

Resolving Credential Aliases

Use the resolve_credential_alias tool to resolve a credential name to its ID:

# Through MCP tools { "tool": "resolve_credential_alias", "arguments": { "alias": "my-api-credentials" } }

Alias Resolution Rules

  • Unique Match: If exactly one credential matches the alias, it returns the credential ID

  • No Match: Throws an error if no credentials match the alias

  • Multiple Matches: Throws an error if multiple credentials have the same name

  • Numeric Values: Credential values that are all digits are treated as IDs and left unchanged

Transfer Operations (Enterprise)

The transfer tools allow moving workflows and credentials across projects and owners in enterprise n8n setups:

Transfer Workflow

// Transfer to a different project { "id": 1, "projectId": "project-123" } // Transfer to a different owner { "id": 1, "newOwnerId": "user-456" } // Transfer to both different project and owner { "id": 1, "projectId": "project-123", "newOwnerId": "user-456" }

Transfer Credential

// Same structure as workflow transfer { "id": 2, "projectId": "project-789", "newOwnerId": "user-123" }

Note: Transfer operations require:

  • Enterprise n8n installation with project/ownership features enabled

  • Appropriate permissions for the user performing the transfer

  • Valid target project IDs and user IDs

Permission errors will be returned with clear error messages if the operation is not allowed.

Tag Management

Tags are used to organize and group workflows in n8n. The MCP server provides comprehensive tag management capabilities:

Tag Operations

  • List Tags: Get all tags with optional pagination

  • Get Tag: Retrieve a specific tag by ID

  • Create Tag: Create a new tag with name and optional color

  • Update Tag: Modify tag name and/or color

  • Delete Tag: Remove a tag

Tag Examples

{ "id": 1, "name": "Production", "color": "#ff0000", "createdAt": "2023-01-01T00:00:00.000Z", "updatedAt": "2023-01-01T00:00:00.000Z" }

The tag API supports:

  • Pagination: Use limit and cursor parameters when listing tags

  • Color Support: Optional hex color codes for visual organization

  • Error Handling: Proper 409 responses for duplicate names, 404 for missing tags

Example Variable Management

Variables in n8n are simple key-value pairs that can be used for configuration and state management:

{ "id": "var-123", "key": "api_endpoint", "value": "https://api.example.com/v1" }

CLI Usage Examples

# Create a variable n8n-mcp variables create --key environment --value production # List all variables n8n-mcp variables list # Update a variable value n8n-mcp variables update var-123 --value "https://api.newdomain.com/v2" # Delete a variable n8n-mcp variables delete var-123

MCP Tool Usage

Variables can be managed through MCP tools for integration with AI agents:

  • list_variables() - Returns paginated list of all variables

  • create_variable({ key: "config_mode", value: "advanced" }) - Creates new variable

  • update_variable({ id: "var-123", value: "new_value" }) - Updates existing variable

  • delete_variable({ id: "var-123" }) - Removes variable

Execution Management

The server provides comprehensive execution management capabilities:

Listing Executions

# List recent executions n8n-mcp executions list # List with pagination n8n-mcp executions list --limit 20 --cursor next_page_cursor # Filter by workflow n8n-mcp executions list --workflow-id 1

The list_executions tool supports:

  • limit: Maximum number of executions to return (pagination)

  • cursor: Pagination cursor for getting next/previous pages

  • workflowId: Filter executions by specific workflow ID

Getting Execution Details

n8n-mcp executions get exec_12345

Returns complete execution data including:

  • Execution status and timing

  • Input/output data

  • Error details (if failed)

  • Node execution results

Deleting Executions

n8n-mcp executions delete exec_12345

Permanently removes execution records to help manage storage.

Pagination Notes

When listing executions:

  • Use limit parameter to control page size

  • Use nextCursor from response to get the next page

  • Cursors are opaque strings - store and use them as-is

  • Empty nextCursor indicates no more pages available

Webhook URLs

The webhook_urls tool helps you get the correct webhook URLs for webhook nodes in your workflows. This is useful for:

  • Getting URLs to configure external systems that need to call your webhooks

  • Testing webhook endpoints during development

  • Documentation and integration guides

Prerequisites for Webhook Nodes

For the webhook_urls tool to work correctly, your webhook node must:

  1. Be of type n8n-nodes-base.webhook

  2. Have a path parameter configured

  3. Be part of an existing workflow

URL Format

The tool returns URLs in n8n's standard format:

  • Test URL: ${baseUrl}/webhook-test/${path} - Used for testing during workflow development

  • Production URL: ${baseUrl}/webhook/${path} - Used when the workflow is active

Example Usage

// Get webhook URLs for a node const urls = await client.getWebhookUrls(1, 'webhook-node-id'); console.log(urls); // Output: // { // "testUrl": "http://localhost:5678/webhook-test/my-webhook", // "productionUrl": "http://localhost:5678/webhook/my-webhook" // }

Manual Workflow Execution

The run_once tool allows you to manually execute workflows, which is useful for:

  • Testing workflows during development

  • Triggering workflows programmatically

  • Running workflows with specific input data

  • Debugging workflow issues

Workflow Types

The tool handles different workflow types gracefully:

  1. Manual Workflows: Workflows that start with manual triggers (e.g., Start node)

  2. Trigger Workflows: Workflows with automatic triggers (e.g., Webhook, Cron, etc.)

Input Data

You can optionally provide input data when executing a workflow:

// Execute without input const execution = await client.runOnce(1); // Execute with input data const execution = await client.runOnce(1, { name: "John Doe", email: "john@example.com" });

Response Format

The tool returns execution details:

{ "executionId": "uuid-execution-id", "status": "running" // or "completed", "failed", etc. }

Releases

This project uses automated releases. When a new release is published on GitHub:

  1. The release workflow automatically triggers

  2. The package is built and tested

  3. If all tests pass, the package is published to the public npm registry

  4. A post-publish smoke test installs the package from npm and validates both module import and CLI wiring

  5. The package can then be installed using: npm install @get2knowio/n8n-mcp

Required GitHub Secret

  • NPM_TOKEN: An npm Automation token with publish rights for the @get2knowio scope

Cut a Release

You can cut a release from the GitHub UI or the CLI. CLI example:

# Bump the version in package.json (patch bump shown) git add package.json README.md .github/workflows/ git commit -m "chore(release): v0.1.1" git tag v0.1.1 git push origin main --tags # Create the GitHub release (requires gh CLI auth) gh release create v0.1.1 -t "v0.1.1" -n "Automated release to npm"

This triggers the Release workflow which builds, tests, publishes to npm, and then runs a smoke test against the published artifact.

Coverage Reporting

Coverage is collected with Jest and uploaded in CI via Coveralls. See CONTRIBUTING.md for local coverage commands.

To create a new release:

  1. Update the version in package.json

  2. Create a new release on GitHub with a tag matching the version

  3. The automated workflow will handle the rest

Smoke Tests (real n8n)

You can validate CLI wiring against a live n8n instance using:

npm run build npm run smoke

The smoke runner loads .env (N8N_BASE_URL + credentials) and enables source maps for readable stacks.

License

MIT

Debugging and traceable errors

To get structured, traceable errors with correlation IDs and source-mapped stacks while developing or troubleshooting:

  • Enable debug logs by setting MCP_DEBUG=debug

  • Enable source maps by setting MCP_ENABLE_SOURCE_MAPS=1 (Node 18+ also supports the --enable-source-maps flag)

Examples:

# Start MCP server with debug logging and write logs to a file (stderr) MCP_DEBUG=debug MCP_ENABLE_SOURCE_MAPS=1 npm start 2>server.log # Use CLI with verbose output N8N_BASE_URL=http://localhost:5678 N8N_API_KEY=xxx \ node dist/cli.js --verbose list

Notes:

  • All logs are written to stderr in JSON to avoid interfering with MCP stdout.

  • Each tool call includes a correlationId you can grep across logs.

  • Axios request/response traces are included in debug mode with sensitive fields redacted.

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI agents to create, retrieve, update, and manage n8n workflows through the n8n API. Supports full workflow lifecycle management including activation, deactivation, and deletion operations.

  1. Features
    1. Workflow Management
    2. Tags Management
    3. Variables Management
  2. Installation
    1. From npm (recommended)
    2. From Source
  3. Configuration
    1. Option 1: API Key Authentication
    2. Option 2: Basic Authentication
  4. Usage
    1. 1) As an MCP Server (recommended)
    2. 2) As a CLI Tool
  5. MCP client configuration examples
    1. Claude Desktop (macOS/Windows/Linux)
    2. Generic MCP client
    3. VS Code MCP (Troubleshooting)
    4. Available Tools
  6. Example Workflow Creation
    1. Basic Workflow with Credential IDs
    2. Workflow with Credential Aliases
  7. Credential Management
    1. Listing Credentials
    2. Resolving Credential Aliases
    3. Alias Resolution Rules
  8. Transfer Operations (Enterprise)
    1. Transfer Workflow
    2. Transfer Credential
  9. Tag Management
    1. Tag Operations
    2. Tag Examples
  10. Example Variable Management
    1. CLI Usage Examples
    2. MCP Tool Usage
  11. Execution Management
    1. Listing Executions
    2. Getting Execution Details
    3. Deleting Executions
    4. Pagination Notes
  12. Webhook URLs
    1. Prerequisites for Webhook Nodes
    2. URL Format
    3. Example Usage
  13. Manual Workflow Execution
    1. Workflow Types
    2. Input Data
    3. Response Format
  14. Releases
    1. Required GitHub Secret
    2. Cut a Release
  15. Coverage Reporting
    1. Smoke Tests (real n8n)
  16. License
    1. Debugging and traceable errors

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/get2knowio/n8n-mcp'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server