MCP HubMCP Hub
salacoste

mcp-n8n-workflow-builder

by: salacoste

MCP server for Claude / Cursor building n8n workflow

15created 15/03/2025
Visit
n8n
workflow

📌Overview

Purpose: To provide a server for managing n8n workflows using the Model Context Protocol (MCP), allowing users to easily create, update, and manage workflows through AI interactions.

Overview: The n8n Workflow Builder MCP Server integrates with Claude AI and Cursor IDE, enabling users to manage n8n workflows with natural language commands and predefined workflow templates. It supports full workflow management, execution monitoring, and tag management, enhancing the user experience in workflow automation.

Key Features:

  • Full integration with Claude AI and Cursor IDE: Enables seamless communication and workflow management through the MCP protocol, allowing users to utilize AI for building workflows.

  • Natural Language Workflow Management: Users can create and manage workflows using conversational language, making it accessible even for those without technical expertise.

  • Predefined Workflow Templates: Offers a range of templates for quick workflow creation using a prompts system, streamlining the building process.

  • Interactive Workflow Building with Real-time Feedback: As users create workflows, they receive immediate feedback, allowing for a more intuitive and efficient development experience.

n8n Workflow Builder MCP Server

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

Requirements

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

Installation Guide

1. Install from npm (Recommended)

# Install globally
npm install -g @kernel.salacoste/n8n-workflow-builder

# Or as a local dependency
npm install @kernel.salacoste/n8n-workflow-builder

2. Clone the Repository

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

3. Install Dependencies

npm install

4. Configure Environment Variables

Create a .env file in the project root with:

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

5. Build and Run

If installed globally:

n8n-workflow-builder
n8n-workflow-builder --json-rpc

If cloned or installed locally:

npm run build
npm start
npm run start -- --json-rpc

6. Claude App Integration

Create a cline_mcp_settings.json by copying and editing:

cp cline_mcp_settings.example.json cline_mcp_settings.json

Example configuration:

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

Notes:

  • MCP_PORT is optional but recommended to avoid port conflicts.
  • Avoid committing cline_mcp_settings.json as it contains sensitive credentials.

Available Tools and Features

MCP Tools

Workflow Management

  • list_workflows: List all workflows
  • create_workflow: Create a new workflow
  • get_workflow: Get workflow details by ID
  • update_workflow: Update an existing workflow
  • delete_workflow: Delete a workflow by ID
  • activate_workflow: Activate a workflow by ID
  • deactivate_workflow: Deactivate a workflow by ID
  • execute_workflow: Manually execute a workflow by ID

Execution Management

  • list_executions: List all workflow executions with filtering
  • get_execution: Get details of a specific execution
  • delete_execution: Delete an execution record

Tag Management

  • create_tag: Create a new tag
  • get_tags: List all tags
  • get_tag: Get tag details by ID
  • update_tag: Update a tag
  • delete_tag: Delete a tag

All tools are optimized for n8n version 1.82.3.

Workflow Trigger Requirements (n8n v1.82.3)

  • At least one valid trigger node is required for workflow activation.
  • Valid triggers include scheduleTrigger, webhook, or service-specific triggers.
  • manualTrigger is NOT recognized as a valid trigger by the API.
  • The activate_workflow tool automatically adds a scheduleTrigger if no trigger is detected.

Known Limitations and API Issues

Trigger Node Activation Issue

  • The API returns a 400 error if no valid trigger node exists in a workflow.
  • manualTrigger nodes are unsupported for activation.
  • Solution: activate_workflow tool adds a proper scheduleTrigger when needed.

Tag Management Conflicts

  • Updating a tag to a name that already exists causes a 409 Conflict error.
  • Solution: UUIDs are generated for tag names and cleanup is performed before testing.

Execution Limitations

  • Webhook and manual triggers cannot be properly executed via API.
  • Schedule triggers can be run but may not execute immediately.
  • Recommendation: Use scheduleTrigger for API-driven workflow execution.

MCP Resources

Static Resources

  • /workflows: List all workflows
  • /execution-stats: Summary statistics about executions

Dynamic Resource Templates

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

MCP Prompts

Predefined workflow templates include:

  • Schedule Triggered Workflow
  • HTTP Webhook Workflow
  • Data Transformation Workflow
  • External Service Integration Workflow
  • API Data Polling Workflow

Each prompt supports customizable variables such as name, schedule, or webhook path.

Usage Examples

Examples and instructions are included in the examples directory:

  • setup_with_claude.md: Setup with Claude App
  • workflow_examples.md: Simple workflow queries
  • complex_workflow.md: Creating/updating complex workflows
  • using_prompts.md: Using prompts for workflow creation

Testing the Server

Using test-mcp-tools.js

Run comprehensive tests of all MCP tools:

node test-mcp-tools.js

Tests cover health checks, workflow, tag, and execution management including cleanup.

Example configuration options:

const config = {
  mcpServerUrl: 'http://localhost:3456/mcp',
  healthCheckUrl: 'http://localhost:3456/health',
  testWorkflowName: 'Test Workflow MCP',
  // ...
};

const testFlags = {
  runWorkflowTests: true,
  runTagTests: true, 
  runExecutionTests: true,
  runCleanup: true
};

Additional Test Scripts

node test-claude.js
node test-prompts.js
node test-workflow.js

Troubleshooting

  • Use npm for dependency management.

  • If issues arise, clean and rebuild with:

    npm run clean && npm run build

  • Verify .env and cline_mcp_settings.json environment variable settings.

  • For Claude integration issues, check the location of cline_mcp_settings.json.

  • For debugging, run with --json-rpc flag and send test requests to port 3000 using curl.

Common Errors

Port Already in Use (EADDRINUSE)

Error example:

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

Fix by either:

  • Setting MCP_PORT environment variable to a different port (recommended):

    MCP_PORT=58921 npm start

  • Killing the process occupying the port:

    lsof -i :3456
kill -9 <PID>

Note: Version 0.7.2+ handles port conflicts gracefully.

Running Multiple Server Instances

  • Use different MCP_PORT values for each instance.
  • Create separate configurations in claude_desktop_config.json.
  • Restart Claude Desktop to see multiple servers.

Authentication Errors

Check:

  • API key validity and match to .env
  • n8n instance API access enabled

Set Node Parameter Error

node.parameters.values.map is not a function occurs with newer Set node parameter formats. Version 0.7.2+ fixes this for compatibility with both legacy and new formats.

Version Compatibility

Tested with:

  • n8n version 1.82.3
  • Node.js v14+
  • MCP protocol version compatible with Claude and Cursor

Report issues with other versions on GitHub.

Changelog

0.7.2 (Current)

  • Fix Set node parameter validation errors
  • Improved port conflict handling
  • Enhanced server startup reliability with multiple instances
  • Support for modern n8n node structures
  • Added support for MCP_PORT environment variable

0.7.1

  • Detailed documentation on n8n API limitations
  • Enhanced troubleshooting with specific error codes
  • Explanation of trigger node requirements
  • Improved UUID generation for tags
  • Updated testing documentation

0.7.0

  • Improved trigger node detection for n8n 1.82.3
  • Added proper handling for activation without trigger nodes
  • Support for different trigger types (schedule, webhook)
  • Tag conflict handling and UUID generation fixes
  • Enhanced workflow testing and error handling

0.6.1

  • Fixed NPM package configuration
  • Excluded tests and sensitive files from package

0.6.0

  • Added execute_workflow tool
  • New API Data Polling workflow template
  • Improved error handling and validation for workflows

0.5.0

  • Initial public release with core workflow management
  • Execution tracking and monitoring
  • Four workflow templates

License

Distributed under the MIT License.