README.md•22.4 kB
# 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.