n8n-mcp

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)

From Source

Configuration

Set the following environment variables:

Option 1: API Key Authentication

Option 2: Basic Authentication

Usage

1) As an MCP Server (recommended)

Run the MCP server (recommended) — unified entrypoint:

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:

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:

Use npx if you prefer not to install globally:

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):

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

Generic MCP client

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:

Alternatively, install globally and reference the binary directly:

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

21. list_variables - List all variables with pagination support

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

23. update_variable - Update an existing variable value

24. delete_variable - Delete a variable

Tag Tools

25. list_tags - List all tags with optional pagination

26. get_tag - Get tag by ID

27. create_tag - Create a new tag

28. update_tag - Update existing tag

29. delete_tag - Delete a tag

Optimistic Concurrency for Updates

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

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

Workflow with Credential Aliases

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

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:

Resolving Credential Aliases

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

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 Credential

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

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:

CLI Usage Examples

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

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

Returns complete execution data including:

• Execution status and timing

• Input/output data

• Error details (if failed)

• Node execution results

Deleting Executions

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

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:

Response Format

The tool returns execution details:

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:

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:

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:

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.