n8n-workflow-builder-mcp

n8n Workflow Builder MCP

This project provides a Model Context Protocol (MCP) server for building and manipulating n8n workflows JSON in Cursor IDE. It's a way to build n8n workflows just by prompting with AI in chat.

DEMO VIDEO:

Cursor rules:

• file with rules is in rules/n8n-mcp-server-rules.mdc

Current status of implementation

Basically, it's working - MCP server creates JSON file with n8n workflow that you can copy and paste to workflow editor in n8n UI.
Current problems:

• sometimes llm agents put wrong parameters in the request. I plan to find a way to fix this.
• not all types of node are checked working. I'm working to resolve it.

Key Features

• Workflow Management: Create, update, and execute n8n workflows programmatically (execute is not implemented yet)
• Node Discovery: Explore available n8n nodes and their capabilities
• Connection Management: Create connections between workflow nodes
• AI Integration: Special tools for connecting AI components in workflows
• AI-Friendly Interface: Designed specifically for interaction with AI agents
• N8N Version Management: Automatic version detection and compatibility handling - supports 123+ N8N versions with dynamic node filtering and "closest lower version" matching for backward compatibility

Prerequisites

• Node.js (v14 or higher)
• Cursor IDE (v0.48 or newer)
• npm (for npx command)

Installation & Setup

Recommended: Using npx in mcp.json (Easiest)

The recommended way to install this MCP server is using npx directly in your .cursor/mcp.json file:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": [
        "-y",
        "n8n-workflow-builder-mcp"
      ],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-n8n-api-key-here",
       // "N8N_VERSION": "1.76.1" // optional, if not set, the server will try to detect the version automatically
      }
    }
  }
}

This approach:

• ✅ Automatically installs the latest version
• ✅ Does not require global installation
• ✅ Works reliably across different environments
• ✅ No manual building or path configuration needed

Setup Steps:

1. Create the .cursor directory in your project root (if it doesn't exist):

   mkdir -p .cursor
   

2. Create or update .cursor/mcp.json with the configuration above, replacing:

   • N8N_API_URL: Your n8n instance URL (default: http://localhost:5678)
   • N8N_API_KEY: Your n8n API key from the n8n settings
   • N8N_VERSION: (Optional) Override N8N version - if not set, auto-detects from API

3. Restart Cursor IDE for changes to take effect

Getting your n8n API Key:

1. Open your n8n instance in a browser
2. Go to Settings > API Keys
3. Click "Create API Key"
4. Copy the generated key and use it in your configuration

Alternative: Development Installation

For development or local testing, you can clone and build from source:

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Build the TypeScript project:

   npm run build
   

4. Configure in .cursor/mcp.json:

   {
     "mcpServers": {
       "n8n-workflow-builder": {
         "command": "node",
         "args": ["/absolute/path/to/n8n-workflow-builder-mcp/dist/index.js"],
         "env": {
           "N8N_API_URL": "http://localhost:5678",
           "N8N_API_KEY": "your-n8n-api-key-here",
           //"N8N_VERSION": "1.76.1" - optional
         }
       }
     }
   }
   

5. For development with auto-rebuild:

   npm run dev
   

Cursor IDE Integration

Using Cursor Settings UI (Optional)

Alternatively, you can set up the MCP server through Cursor's interface:

1. Start Cursor IDE
2. Go to Settings > Features > MCP Servers
3. Click "Add Server"
4. For npx method: Use command npx with args ["-y", "n8n-workflow-builder-mcp"]
5. Add environment variables:
   • N8N_API_URL: http://localhost:5678
   • N8N_API_KEY: your-n8n-api-key-here
   • N8N_VERSION: 1.76.1 (optional - auto-detects if not set)
6. Make sure the server is enabled
7. Restart Cursor IDE for changes to take effect

Available MCP Tools

The server provides the following tools for working with n8n workflows:

Tool Name	Description	Key Parameters
create_workflow	Create a new n8n workflow	workflow_name, workspace_dir
list_workflows	List workflows in the workspace	limit (optional), cursor (optional)
get_workflow_details	Get detailed information about a specific workflow	workflow_name, workflow_path (optional)
add_node	Add a new node to a workflow	workflow_name, node_type, position (optional), parameters (optional), node_name (optional), typeVersion (optional), webhookId (optional), workflow_path (optional), connect_from (optional), connect_to (optional)
edit_node	Edit an existing node in a workflow	workflow_name, node_id, node_type (optional), node_name (optional), position (optional), parameters (optional), typeVersion (optional), webhookId (optional), workflow_path (optional), connect_from (optional), connect_to (optional)
delete_node	Delete a node from a workflow	workflow_name, node_id, workflow_path (optional)
add_connection	Create a connection between two nodes	workflow_name, source_node_id, source_node_output_name, target_node_id, target_node_input_name, target_node_input_index (optional), workflow_path (optional)
add_ai_connections	Wire AI model, tools, and memory to an agent	workflow_name, agent_node_id, model_node_id (optional), tool_node_ids (optional), memory_node_id (optional), embeddings_node_id (optional), vector_store_node_id (optional), vector_insert_node_id (optional), vector_tool_node_id (optional), workflow_path (optional)
compose_ai_workflow	Compose a complex AI workflow (agent + model + memory + embeddings + vector + tools + trigger) in one call, including wiring and basic validation	workflow_name, plan, n8n_version (optional)
list_available_nodes	List available node types with optional filtering. Supports tag-style synonyms and multi-token OR/AND logic	search_term (optional), n8n_version (optional), limit (optional), cursor (optional), tags (optional, default: true), token_logic (optional: 'or' default, or 'and')
get_n8n_version_info	Get current N8N version and capabilities	random_string
validate_workflow	Validate a workflow file against node schemas and connectivity	workflow_name, workflow_path (optional)

Validation behavior

validate_workflow promotes warnings to errors and additionally fails when any enabled node is not connected (directly or via AI ports) to the main chain starting at the inferred startNode. Use connect_from/connect_to or add_ai_connections to fix connectivity.

Troubleshooting Cursor Integration

If you're having trouble getting the MCP server to work with Cursor, try these steps:

For npx installation (Recommended method):

Make sure your .cursor/mcp.json file is properly formatted:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["-y", "n8n-workflow-builder-mcp"]
    }
  }
}

General troubleshooting:

1. Check Cursor MCP settings:

   • Open Cursor Settings
   • Go to Features > MCP Servers
   • Make sure your server is listed and enabled
   • If it's listed but not working, try clicking the refresh button

2. Check server logs: Look for errors in the Cursor Output panel. Select "Cursor MCP" from the dropdown in the Output panel to see MCP-specific logs.

3. Try manual installation: If npx fails, try the global installation method as an alternative:

   npm install -g n8n-workflow-builder-mcp
   

Common Issues and Solutions

"Failed to create client" or "Module not found"

This usually happens when:

• Internet connection issues prevent npx from downloading the package
• Node.js/npm version compatibility issues
• Cursor MCP service is not running properly

Try:

1. Check your internet connection
2. Update Node.js to the latest LTS version
3. Restart Cursor completely
4. Try the global installation method as fallback

MCP Server is not showing up in Cursor

This can happen if:

• The .cursor/mcp.json file is not properly formatted
• Cursor hasn't detected the configuration change
• File permissions on the .cursor directory

Try:

1. Validating the JSON format of your .cursor/mcp.json file
2. Restarting Cursor
3. Manually selecting the server in Cursor settings (if it appears there)
4. Check file permissions: chmod 755 .cursor

MCP Server shows up but tools aren't available

This can happen if:

• The server isn't properly registering its tools
• Package installation is incomplete
• Version compatibility issues

Try:

1. Check the package was downloaded correctly by npx
2. Clicking the refresh button in the MCP server settings in Cursor
3. Try clearing npm cache: npm cache clean --force
4. Use the development installation method for debugging

Project Structure

• /src: Main source code
• /src/tools: MCP tools implementation
• /src/models: Data models
• /src/utils: Utility functions
• /src/middleware: Authentication and middleware
• /config: Configuration files
• /tests: Test files
• /workflow_nodes: n8n node definitions
• /docs: Additional documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

License

MIT License