n8n MCP Server

# n8n-mcp [](https://github.com/get2knowio/n8n-mcp/actions/workflows/ci.yml) [](https://github.com/get2knowio/n8n-mcp/actions/workflows/release.yml) [](https://coveralls.io/github/get2knowio/n8n-mcp?branch=main) [](https://www.npmjs.com/package/@get2knowio/n8n-mcp) [](https://opensource.org/licenses/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 ### n8n Endpoint Compatibility & Fallback This MCP server supports multiple n8n API versions and automatically falls back between endpoints for maximum compatibility: #### ID Support - **UUID Support**: All tools accept both numeric IDs (e.g., `1`, `2`) and string UUIDs (e.g., `"tag-uuid-123"`, `"workflow-abc-def"`) - Works with n8n Cloud (UUID-based) and self-hosted instances (numeric or UUID-based) #### Tag Operations Fallback Strategy **Listing Tags:** 1. Primary: `GET /api/v1/tags` 2. Fallback: `GET /rest/tags` (when v1 returns 404/401) **Updating Tag Color:** 1. Try: `PATCH /rest/tags/{id}` with `{ color: "#ff0000" }` 2. Fallback: `PUT /api/v1/tags/{id}` with `{ name, color }` 3. If both fail: Returns helpful error message explaining color may need to be set via UI **Setting Workflow Tags:** 1. Try: `PATCH /rest/workflows/{id}` with `{ tags: ["tag1", "tag2"] }` (tag names) 2. Try: `PATCH /rest/workflows/{id}` with `{ tags: [{ id: "uuid1" }, { id: "uuid2" }] }` (tag IDs as objects) 3. Fallback: `PUT /api/v1/workflows/{id}/tags` with `{ tagIds: ["uuid1", "uuid2"] }` 4. If all fail: Returns detailed error with attempted endpoints and status codes This multi-endpoint approach ensures the MCP server works across: - n8n Cloud (typically `/api/v1` endpoints) - Self-hosted n8n v1.x+ (typically `/api/v1` endpoints) - Older self-hosted versions (typically `/rest` endpoints) #### Error Messages When operations fail due to endpoint limitations, error responses include: - List of attempted endpoints with HTTP methods and status codes - Helpful hints (e.g., "Tag color may need to be set via the n8n web UI") - Suggestions for alternative approaches ## Installation ### From npm (recommended) ```bash npm install @get2knowio/n8n-mcp ``` ### From Source ```bash 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 ``` ### Devcontainer (Docker Compose) This repo includes a VS Code devcontainer powered by Docker Compose that launches: - `dev`: your development container (this repo mounted at `/workspaces/n8n-mcp`) - `n8n`: a local n8n instance on the same Docker network, reachable via `http://n8n:5678` Open the folder in VS Code and “Reopen in Container”. The dev container sets these env vars so the CLI and smoke tests talk to the sidecar by default: - `N8N_BASE_URL=http://n8n:5678` - `N8N_USERNAME=test`, `N8N_PASSWORD=test` You can still override these with a local `.env` if needed. ## Configuration Set the following environment variables: ### Option 1: API Key Authentication ```bash export N8N_BASE_URL=http://localhost:5678 export N8N_API_KEY=your_api_key_here ``` ### Option 2: Basic Authentication ```bash 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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash npx @get2knowio/n8n-mcp list ``` For local development (npm scripts, running from source), see [CONTRIBUTING.md](./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): ```json { "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 ```json { "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: ```jsonc { "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: ```bash 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 7. **deactivate_workflow** - Deactivate a workflow 8. **list_credentials** - List all credentials 9. **resolve_credential_alias** - Resolve a credential alias to its ID 10. **source_control_pull** - Pull changes from source control 11. **get_credential_schema** - Get JSON schema for a credential type 12. **list_workflow_tags** - List tags for a specific workflow 13. **set_workflow_tags** - Set tags for a specific workflow 14. **transfer_workflow** - Transfer a workflow to a different project or owner 15. **transfer_credential** - Transfer a credential to a different project or owner 16. **list_executions** - List workflow executions with pagination 17. **get_execution** - Get execution by ID 18. **delete_execution** - Delete an execution 19. **webhook_urls** - Get webhook URLs for a webhook node 20. **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: ```json { "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 ```json { "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: ```json { "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: ```bash # Through MCP tools { "tool": "list_credentials", "arguments": {} } ``` ### Resolving Credential Aliases Use the `resolve_credential_alias` tool to resolve a credential name to its ID: ```bash # 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 ```javascript // 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 ```javascript // 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 ```json { "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: ```json { "id": "var-123", "key": "api_endpoint", "value": "https://api.example.com/v1" } ``` ### CLI Usage Examples ```bash # 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 ```bash # 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 ```bash 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 ```bash 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 ```javascript // 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: ```javascript // 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: ```javascript { "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: ```bash # 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](./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: ```bash 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: ```bash # 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.