n8n MCP Server

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

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

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

# 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

list_workflows - List all workflows
get_workflow - Get workflow by ID
create_workflow - Create a new workflow
update_workflow - Update existing workflow
delete_workflow - Delete a workflow
activate_workflow - Activate a workflow
deactivate_workflow - Deactivate a workflow
webhook_urls - Get webhook URLs for a webhook node
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"]
}

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:

Be of type n8n-nodes-base.webhook
Have a path parameter configured
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:

Manual Workflows: Workflows that start with manual triggers (e.g., Start node)
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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

The release workflow automatically triggers
The package is built and tested
If all tests pass, the package is published to GitHub Packages
The package can then be installed using: npm install @get2knowio/n8n-mcp

To create a new release:

Update the version in package.json
Create a new release on GitHub with a tag matching the version
The automated workflow will handle the rest

License

MIT