Repository files navigation

This project provides an MCP (Model Context Protocol) server for managing n8n workflows. It allows you to create, update, delete, activate, and deactivate workflows through a set of tools available in Claude AI and Cursor IDE.

Key Features:

• Full integration with Claude AI and Cursor IDE via MCP protocol
• Create and manage n8n workflows via natural language
• Predefined workflow templates through prompts system
• Interactive workflow building with real-time feedback

• Node.js (v14+ recommended)
• npm
• n8n instance with API access (tested and compatible with n8n version 1.82.3)
• Claude App or Cursor IDE for AI interaction

You can install the package directly from npm:

# Install globallynpm install -g @kernel.salacoste/n8n-workflow-builder# Or as a local dependencynpm install @kernel.salacoste/n8n-workflow-builder

After installation, you need to configure the environment variables (see step 3).

Alternatively, you can clone the repository from GitHub:

git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git

Then navigate to the project directory:

cd mcp-n8n-workflow-builder

Install the necessary dependencies using npm:

npm install

Create an.env file in the project root with the following variables:

N8N_HOST=https://your-n8n-instance.com/api/v1/N8N_API_KEY=your_api_key_here

If you installed via npm globally, you can run the server using the command:

n8n-workflow-builder

Or with JSON-RPC mode:

n8n-workflow-builder --json-rpc

If you cloned the repository or installed as a local dependency, use the following commands:

• Build the project:

  npm run build

• Start the MCP Server in standalone mode:

  npm start

• Start with JSON-RPC mode for testing:

  npm run start -- --json-rpc

The server will start and accept requests via stdio or JSON-RPC depending on the mode.

For integration with Claude App, you need to create a configuration filecline_mcp_settings.json. You can copy the example fromcline_mcp_settings.example.json and edit it:

cp cline_mcp_settings.example.json cline_mcp_settings.json

Then edit the file, providing the correct environment variable values:

{"n8n-workflow-builder": {"command":"node","args": ["path/to/your/project/build/index.js"],"env": {"N8N_HOST":"https://your-n8n-instance.com/api/v1/","N8N_API_KEY":"your_api_key_here","MCP_PORT":"58921"    },"disabled":false,"alwaysAllow": ["list_workflows","get_workflow","list_executions","get_execution"    ],"autoApprove": ["create_workflow","update_workflow","activate_workflow","deactivate_workflow","delete_workflow","delete_execution"    ]  }}

Important Notes:

• TheMCP_PORT parameter is optional but recommended to avoid port conflicts
• Use a non-standard high port (like 58921) if you encounter conflicts
• Starting with version 0.7.2, the server gracefully handles port conflicts
• Do not addcline_mcp_settings.json to the repository as it contains your personal access credentials

The following tools are available through the MCP protocol:

• list_workflows: Displays a list of all workflows from n8n.
• create_workflow: Creates a new workflow in n8n.
• get_workflow: Gets workflow details by its ID.
• update_workflow: Updates an existing workflow.
• delete_workflow: Deletes a workflow by its ID.
• activate_workflow: Activates a workflow by its ID.
• deactivate_workflow: Deactivates a workflow by its ID.
• execute_workflow: Manually executes a workflow by its ID.

• list_executions: Displays a list of all workflow executions with filtering capabilities.
• get_execution: Gets details of a specific execution by its ID.
• delete_execution: Deletes an execution record by its ID.

• create_tag: Creates a new tag.
• get_tags: Gets a list of all tags.
• get_tag: Gets tag details by its ID.
• update_tag: Updates an existing tag.
• delete_tag: Deletes a tag by its ID.

All tools have been tested and optimized for n8n version 1.82.3. The node types and API structures used are compatible with this version.

When working with n8n version 1.82.3, please note the following important requirements:

• Trigger nodes are required for activation: n8n requires at least one valid trigger node to successfully activate a workflow.
• Valid trigger node types include:
  • scheduleTrigger (recommended for automation)
  • webhook (for HTTP-triggered workflows)
  • Service-specific trigger nodes
• Automatic trigger addition: Theactivate_workflow tool automatically adds ascheduleTrigger node when no trigger is detected
• Manual trigger limitation: ThemanualTrigger node type is NOT recognized as a valid trigger by n8n API v1.82

Theactivate_workflow tool implements intelligent detection of trigger nodes and adds necessary attributes to ensure compatibility with the n8n API.

During testing with n8n version 1.82.3, we've identified several API limitations that users should be aware of:

The n8n API enforces strict requirements for workflow activation that aren't clearly documented:

Status: 400Error: Workflow has no node to start the workflow - at least one trigger, poller or webhook node is required

Impact:

• Workflows without a recognized trigger node cannot be activated via API
• ThemanualTrigger node is NOT recognized as a valid trigger despite being usable in the UI
• Even adding attributes likegroup: ['trigger'] tomanualTrigger does not solve the issue

Our solution:

• Theactivate_workflow function automatically detects missing trigger nodes
• Adds a properly configuredscheduleTrigger when needed
• Preserves all your existing nodes and connections

When updating tags that already exist, the API returns a409 Conflict Error:

Status: 409Error: Tag with this name already exists

Impact:

• Tag updates may fail if a tag with the requested name already exists
• This happens even when updating a tag to the same name

Our solution:

• The test script now implements UUID generation for tag names
• Performs cleanup of existing tags before testing
• Implements proper error handling for tag conflicts

The execution API has limitations with certain trigger types:

• Webhook triggers: Return 404 errors when executed via API (expected behavior)
• Manual triggers: Cannot be properly executed through the API in version 1.82.3
• Schedule triggers: Can be activated but may not execute immediately

Recommendation:For workflows that need to be executed via API, use thescheduleTrigger with your desired interval settings.

The server provides the following resources for more efficient context access:

• /workflows: List of all available workflows in the n8n instance
• /execution-stats: Summary statistics about workflow executions

• /workflows/{id}: Detailed information about a specific workflow
• /executions/{id}: Detailed information about a specific execution

The server offers predefined workflow templates through the prompts system:

• Schedule Triggered Workflow: Create a workflow that runs on a schedule
• HTTP Webhook Workflow: Create a workflow that responds to HTTP webhook requests
• Data Transformation Workflow: Create a workflow for processing and transforming data
• External Service Integration Workflow: Create a workflow that integrates with external services
• API Data Polling Workflow: Create a workflow that polls an API and processes data with filtering

Each prompt has variables that can be customized when generating a workflow, such as workflow name, schedule expression, webhook path, and more.

In theexamples directory, you'll find examples and instructions for setting up and using n8n Workflow Builder with Claude App:

1. setup_with_claude.md - Step-by-step instructions for setting up integration with Claude App
2. workflow_examples.md - Simple query examples for working with n8n workflows
3. complex_workflow.md - Examples of creating and updating complex workflows
4. using_prompts.md - Guide to using the prompts feature for quick workflow creation

You can use the provided test scripts to verify the functionality:

Thetest-mcp-tools.js script provides comprehensive testing of all MCP tools against your n8n instance. This is the recommended way to validate your setup and ensure all functionality works correctly.

# Run all testsnode test-mcp-tools.js

The script performs the following tests:

1. Health check and tools availability
2. Workflow management (create, read, update, activate)
3. Tag management (create, read, update, delete)
4. Execution management (execute, list, get, delete)

The test script creates temporary test workflows and tags which are automatically cleaned up after testing. You can customize the test behavior by modifying the test configuration variables at the top of the script.

// Configuration options in test-mcp-tools.jsconstconfig={mcpServerUrl:'http://localhost:3456/mcp',healthCheckUrl:'http://localhost:3456/health',testWorkflowName:'Test Workflow MCP',// ... other options};// Test flags to enable/disable specific test suitesconsttestFlags={runWorkflowTests:true,runTagTests:true,runExecutionTests:true,runCleanup:true};

# Test basic functionality with Claudenode test-claude.js# Test prompts functionalitynode test-prompts.js# Test workflow creation and managementnode test-workflow.js

• Make sure you are using npm.
• If you encounter problems, try cleaning the build directory and rebuilding the project:

  npm run clean&& npm run build

• Check that your environment variables in.env andcline_mcp_settings.json are set correctly.
• If you have problems with Claude integration, check the location of thecline_mcp_settings.json file.
• For debugging, run with the--json-rpc flag and use curl to send test requests to port 3000.

If you see the following error in logs:

Error: listen EADDRINUSE: address already in use :::3456

This means that port 3456 (default for the MCP server) is already in use by another process. To fix:

Option 1: Use a Different Port with Environment Variable

Starting from version 0.7.2, you can specify a custom port using theMCP_PORT environment variable:

# In your codeMCP_PORT=58921 npm start# Or when running directlyMCP_PORT=58921 node build/index.js

If using Claude Desktop, update yourcline_mcp_settings.json to include the new port:

{"n8n-workflow-builder": {"command":"node","args": ["path/to/your/project/build/index.js"],"env": {"N8N_HOST":"https://your-n8n-instance.com/api/v1/","N8N_API_KEY":"your_api_key_here","MCP_PORT":"58921"    },// ...  }}

Option 2: Find and kill the process using the port

# On macOS/Linuxlsof -i :3456kill -9<PID># On Windowsnetstat -ano| findstr :3456taskkill /PID<PID> /F

Note on Version 0.7.2+: Starting with version 0.7.2, the server includes improved handling for port conflicts, automatically detecting when a port is already in use and gracefully continuing operation without throwing errors. This is especially helpful when Claude Desktop attempts to start multiple instances of the same server.

If you need to run multiple instances of the n8n workflow builder server (for example, for different n8n installations), you can do this by configuring separate ports:

1. Configure different ports for each instance:

   # First instanceMCP_PORT=58921 node build/index.js# Second instanceMCP_PORT=58922 node build/index.js

2. Create separate Claude Desktop configurations:For each instance, create a separate entry in yourclaude_desktop_config.json file:

   {"mcpServers": {"n8n-workflow-builder-prod": {"command":"node","args": ["path/to/build/index.js"],"env": {"N8N_HOST":"https://production-n8n.example.com/api/v1/","N8N_API_KEY":"your_prod_api_key","MCP_PORT":"58921"      }    },"n8n-workflow-builder-dev": {"command":"node","args": ["path/to/build/index.js"],"env": {"N8N_HOST":"https://dev-n8n.example.com/api/v1/","N8N_API_KEY":"your_dev_api_key","MCP_PORT":"58922"      }    }  }}

3. Access each instance in Claude:After restarting Claude Desktop, you'll see both servers available in your tools list.

If you see errors related to API authentication:

Error: Request failed with status code 401

Check that:

1. Your API key is correct and hasn't expired
2. The N8N_API_KEY in your.env file matches your n8n instance
3. Your n8n instance has API access enabled

If you encounter the errornode.parameters.values.map is not a function when creating workflows:

This usually happens when creating workflows with Set nodes that use the newer n8n parameter structure. Version 0.7.2+ includes a fix that supports both the legacy array format and the newer object-based format for Set node parameters.

This MCP server has been specifically tested and validated with:

• n8n version: 1.82.3
• Node.js: v14 and above
• MCP Protocol: Latest version compatible with Claude and Cursor

If you're using a different version of n8n, some API endpoints or node types may differ. Please report any compatibility issues in the GitHub repository.

• Fixed validation error when handling Set node parameters in workflow creation
• Added improved error handling for port conflicts
• Enhanced server startup reliability with multiple running instances
• Fixednode.parameters.values.map is not a function error for modern n8n node structure
• Added MCP_PORT environment variable support for custom port configuration

• Added detailed documentation about n8n API limitations and known issues
• Enhanced troubleshooting section with specific error codes and solutions
• Added comprehensive explanation of trigger node requirements
• Improved UUID generation for tag management to prevent conflicts
• Updated testing documentation with detailed examples

• Enhanced trigger node detection and compatibility with n8n 1.82.3
• Improved handling of workflow activation when no trigger node exists
• Added proper handling of different trigger node types (schedule, webhook)
• Fixed tag management with proper conflict handling and UUID generation
• Updated documentation with trigger node requirements and compatibility notes
• Improved test-mcp-tools.js with enhanced workflow testing and error handling

• Fixed NPM package configuration
• Excluded test scripts and sensitive files from NPM package

• Addedexecute_workflow tool to manually run workflows by ID
• Added newAPI Data Polling Workflow template for efficient API data retrieval and filtering
• Improved error handling for workflow creation and validation
• Added validation checks for typical workflow configuration issues
• Better error messages with suggestions for common problems

• Initial public release
• Basic workflow management functionality
• Execution tracking and monitoring
• Four workflow templates

This project is distributed under the MIT License.