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
• List Executions: Get workflow executions with pagination support
• Get Execution: Retrieve specific execution details by ID
• Delete Execution: Remove execution records

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 GitHub Packages

npm install @get2knowio/n8n-mcp

From Source

git clone https://github.com/get2knowio/n8n-mcp.git
cd n8n-mcp
npm install
npm run build

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

As an MCP Server

npm start

The server runs on stdio and implements the MCP protocol for integration with AI agents.

As a CLI Tool

For testing and development, you can use the CLI interface:

# List all workflows
npm run cli list

# Get a specific workflow
npm run cli get 1

# Create a workflow from JSON file
npm run cli create examples/example-workflow.json

# Delete a workflow
npm run cli delete 1

# Activate/deactivate workflows
npm run cli activate 1
npm run cli deactivate 1

# Variables management
npm run cli variables list
npm run cli variables create --key mykey --value myvalue
npm run cli variables update var-123 --value newvalue
npm run cli variables delete var-123

# List executions
npm run cli executions list

# List executions with pagination and filtering
npm run cli executions list --limit 50 --workflow-id 1

# Get a specific execution
npm run cli executions get exec_123

# Delete an execution
npm run cli executions delete exec_123

# Get webhook URLs for a webhook node
npm run cli webhook-urls 1 webhook-node-id

# Execute a workflow manually once
npm run cli run-once 1

# Execute a workflow with input data
npm run cli run-once 1 input-data.json

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
5. delete_workflow - Delete a workflow
6. activate_workflow - Activate a workflow
7. deactivate_workflow - Deactivate a workflow
8. list_executions - List workflow executions with pagination
9. get_execution - Get execution by ID
10. delete_execution - Delete an execution
11. webhook_urls - Get webhook URLs for a webhook node
12. run_once - Execute a workflow manually once

Variables Tools

8. list_variables - List all variables with pagination support
9. create_variable - Create a new variable (requires unique key)
10. update_variable - Update an existing variable value
11. delete_variable - Delete a variable
12. list_executions - List workflow executions with pagination
13. get_execution - Get execution by ID
14. delete_execution - Delete an execution
15. webhook_urls - Get webhook URLs for a webhook node
16. run_once - Execute a workflow manually once

Example Workflow Creation

{
  "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"]
}

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
npm run cli variables create --key environment --value production

# List all variables
npm run cli variables list

# Update a variable value
npm run cli variables update var-123 --value "https://api.newdomain.com/v2"

# Delete a variable
npm run cli 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
npm run cli executions list

# List with pagination
npm run cli executions list --limit 20 --cursor next_page_cursor

# Filter by workflow
npm run cli 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

npm run cli 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

npm run cli 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.
}

Development

Setup

npm install
npm run build

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code (TypeScript type checking)
npm run lint

Scripts

npm run dev      # Watch mode for development
npm run build    # Build TypeScript
npm run test     # Run tests
npm run lint     # TypeScript type checking

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

All contributions are welcome! Please make sure to update tests as appropriate and follow the existing code style.

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 GitHub Packages
4. The package can then be installed using: npm install @get2knowio/n8n-mcp

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

License

MIT