n8n Workflow Builder MCP Server

The ultimate AI assistant integration for n8n workflow automation - Connect Claude Desktop, ChatGPT, and other AI assistants directly to your n8n instance for seamless workflow management, creation, and execution through the Model Context Protocol (MCP).

A powerful Model Context Protocol (MCP) server that enables AI assistants to manage n8n workflows seamlessly. Connect your AI tools directly to n8n for automated workflow creation, execution, and management.

📖 Additional Documentation

🚀 Getting Started Guide - Quick setup in under 5 minutes
💼 Real-World Use Cases - E-commerce, data processing, API integrations, and more
🔍 Comparison with Alternatives - vs Zapier, Make.com, n8n Web UI, and CLI
🔧 Comprehensive Troubleshooting - Solutions for common issues and problems

🎯 What is this?

The n8n Workflow Builder MCP Server bridges the gap between AI assistants (like Claude Desktop, Cline, or any MCP-compatible client) and your n8n automation platform. It provides a comprehensive set of tools that allow AI assistants to:

List and browse your existing n8n workflows
Create new workflows with complex node configurations
Execute workflows on demand
Manage workflow lifecycle (activate, deactivate, update, delete)
Monitor workflow status and retrieve detailed information

Perfect for teams using n8n who want to leverage AI assistants for workflow automation and management.

✨ Key Features

🔧 Complete Workflow Management - Full CRUD operations for n8n workflows
🤖 AI-First Design - Built specifically for AI assistant integration
🚀 Zero Configuration - Works out of the box with NPX
🔒 Secure - Uses n8n's official API with proper authentication
📦 Modern Architecture - Built with TypeScript and latest MCP SDK
⚡ High Performance - Optimized for fast response times

📋 Requirements

Node.js v18.0.0 or higher
n8n instance (self-hosted or cloud)
n8n API key with appropriate permissions

🚀 Installation & Usage

Method 1: Smithery.ai (Hosted - Recommended)

Use the hosted version on Smithery.ai - no installation required:

Visit: smithery.ai
Search: "n8n-workflow-builder"
Connect: Configure with your n8n host and API key
Use: Access from any MCP-compatible AI assistant

Benefits: No local setup, automatic updates, professional hosting, tool playground.

Method 2: NPX (Local)

Run locally with NPX:

npx @makafeli/n8n-workflow-builder

Method 2: Manual Installation

For development or customization:

# Clone the repository
git clone https://github.com/makafeli/n8n-workflow-builder.git
cd n8n-workflow-builder

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

⚙️ Configuration

Environment Variables

Configure the following environment variables to connect to your n8n instance:

Variable	Description	Example
`N8N_HOST`	Your n8n instance URL	`http://localhost:5678` or `https://your-n8n.com/api/v1`
`N8N_API_KEY`	Your n8n API key	`n8n_api_1234567890abcdef...`

Getting Your n8n API Key

Open your n8n instance
Go to Settings → API Keys
Click Create API Key
Copy the generated key

Setting Environment Variables

# For local testing
export N8N_HOST="http://localhost:5678"
export N8N_API_KEY="your-api-key-here"

# Then run the server
npx @makafeli/n8n-workflow-builder

🔧 MCP Client Setup

Claude Desktop

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@makafeli/n8n-workflow-builder"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline (VS Code Extension)

Add this to your Cline MCP settings:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@makafeli/n8n-workflow-builder"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

The server works with any MCP-compatible client. Use the same configuration pattern with your client's specific setup method.

🛠️ Available Tools

The MCP server provides 15 comprehensive tools for complete n8n workflow and execution management:

Core Workflow Operations

Tool	Description	Parameters
`list_workflows`	List all workflows from your n8n instance	None
`get_workflow`	Retrieve detailed information about a specific workflow	`id`: Workflow ID (string)
`create_workflow`	Create a new workflow with nodes and connections	`workflow`: Workflow object
`execute_workflow`	Manually execute a workflow	`id`: Workflow ID (string)

Workflow Lifecycle Management

Tool	Description	Parameters
`update_workflow`	Update an existing workflow's configuration	`id`: Workflow ID, `workflow`: Updated workflow object
`activate_workflow`	Activate a workflow to enable automatic execution	`id`: Workflow ID (string)
`deactivate_workflow`	Deactivate a workflow to stop automatic execution	`id`: Workflow ID (string)
`delete_workflow`	Permanently delete a workflow	`id`: Workflow ID (string)

Advanced Operations

Tool	Description	Parameters
`create_workflow_and_activate`	Create a new workflow and immediately activate it	`workflow`: Workflow object

Execution Management ⭐ NEW

Tool	Description	Parameters
`list_executions`	List workflow executions with filtering and pagination	`includeData`, `status`, `workflowId`, `projectId`, `limit`, `cursor`
`get_execution`	Get detailed information about a specific execution	`id`: Execution ID, `includeData`: Include detailed data
`delete_execution`	Delete a workflow execution record	`id`: Execution ID

Tag Management ⭐ NEW

Tool	Description	Parameters
`list_tags`	List all workflow tags with pagination	`limit`, `cursor`
`create_tag`	Create a new workflow tag for organization	`name`: Tag name

Security & Compliance ⭐ NEW

Tool	Description	Parameters
`generate_audit`	Generate comprehensive security audit report	`additionalOptions`: Audit configuration

💡 Usage Examples

Basic Operations

// List all workflows
await callTool("list_workflows", {});

// Get detailed information about a workflow
await callTool("get_workflow", { id: "workflow-123" });

// Execute a workflow manually
await callTool("execute_workflow", { id: "workflow-123" });

Creating Workflows

// Create a simple workflow
await callTool("create_workflow", {
  workflow: {
    name: "My Automation Workflow",
    nodes: [
      {
        id: "trigger",
        name: "Schedule Trigger",
        type: "n8n-nodes-base.scheduleTrigger",
        typeVersion: 1,
        position: [240, 300],
        parameters: {
          interval: [{ field: "unit", value: "hours" }]
        }
      },
      {
        id: "action",
        name: "HTTP Request",
        type: "n8n-nodes-base.httpRequest",
        typeVersion: 4,
        position: [460, 300],
        parameters: {
          url: "https://api.example.com/webhook",
          method: "POST"
        }
      }
    ],
    connections: {
      "Schedule Trigger": {
        "main": [[{ "node": "HTTP Request", "type": "main", "index": 0 }]]
      }
    }
  }
});

Workflow Management

// Activate a workflow
await callTool("activate_workflow", { id: "workflow-123" });

// Update a workflow
await callTool("update_workflow", {
  id: "workflow-123",
  workflow: { name: "Updated Workflow Name" }
});

// Deactivate a workflow
await callTool("deactivate_workflow", { id: "workflow-123" });

// Create and immediately activate
await callTool("create_workflow_and_activate", {
  workflow: { /* workflow configuration */ }
});

Execution Management ⭐ NEW

// List recent executions
await callTool("list_executions", {
  limit: 10,
  status: "error"
});

// Get detailed execution information
await callTool("get_execution", {
  id: "execution-123",
  includeData: true
});

// Clean up old execution records
await callTool("delete_execution", { id: "execution-123" });

Tag Management ⭐ NEW

// List all workflow tags
await callTool("list_tags", { limit: 50 });

// Create a new tag for organization
await callTool("create_tag", { name: "production" });

Security Audit ⭐ NEW

// Generate comprehensive security audit
await callTool("generate_audit", {
  additionalOptions: {
    daysAbandonedWorkflow: 30,
    categories: ["credentials", "database", "nodes"]
  }
});

🔧 Troubleshooting

Common Issues

"Connection refused" or "ECONNREFUSED"

Cause: Cannot connect to your n8n instance
Solution: Verify your N8N_HOST is correct and n8n is running
Check: Try accessing your n8n instance in a browser first

"Unauthorized" or "401 Error"

Cause: Invalid or missing API key
Solution:
1. Verify your N8N_API_KEY is correct
2. Ensure the API key has proper permissions
3. Check if the API key hasn't expired

"Workflow not found" or "404 Error"

Cause: Workflow ID doesn't exist
Solution: Use list_workflows to get valid workflow IDs

Server won't start

Cause: Missing Node.js or dependencies
Solution:
1. Ensure Node.js v18+ is installed: node --version
2. Try clearing npm cache: npm cache clean --force
3. For manual installation, run: npm install && npm run build

Debug Mode

For detailed logging, set the debug environment variable:

DEBUG=n8n-workflow-builder npx @makafeli/n8n-workflow-builder

Getting Help

Check the GitHub Issues
Review n8n's API documentation
Verify your MCP client configuration

❓ Frequently Asked Questions

What is an MCP Server?

A Model Context Protocol (MCP) server is a standardized way for AI assistants to access external tools and data sources. This MCP server specifically provides AI assistants with the ability to interact with n8n workflows, enabling automated workflow management through natural language commands.

How do I connect AI assistants to n8n workflows?

This MCP server acts as a bridge between AI assistants (like Claude Desktop, Cline, or ChatGPT) and your n8n instance. Simply:

Install the MCP server: npx @makafeli/n8n-workflow-builder
Configure your AI assistant's MCP settings with your n8n credentials
Start using natural language to manage your n8n workflows

Which AI assistants work with this MCP server?

The server works with any MCP-compatible AI assistant, including:

Claude Desktop (Anthropic)
Cline (VS Code extension)
Continue (VS Code extension)
Any custom MCP client implementation
Future MCP-compatible AI assistants

Can I use this with n8n Cloud or only self-hosted?

This MCP server works with both n8n Cloud and self-hosted instances. You just need:

Your n8n instance URL (cloud or self-hosted)
A valid n8n API key with appropriate permissions
Network access from where you're running the MCP server

What can AI assistants do with my n8n workflows?

AI assistants can perform complete workflow management including:

List and browse existing workflows
Create new workflows with complex node configurations
Execute workflows manually or on-demand
Activate/deactivate workflows
Update and modify existing workflows
Monitor execution status and retrieve detailed logs
Manage workflow tags and organization
Generate security audits and compliance reports

Is this secure? What permissions does it need?

The MCP server uses n8n's official API with proper authentication:

Requires a valid n8n API key (you control the permissions)
No data is stored by the MCP server
All communication is direct between your AI assistant and n8n
Follows n8n's security model and access controls
You can revoke access anytime by disabling the API key

How is this different from using n8n's web interface?

This MCP server enables AI-powered workflow management:

Natural language commands instead of clicking through UI
Automated workflow creation based on descriptions
Bulk operations across multiple workflows
Integration with AI assistant workflows and automation
Voice commands through AI assistants
Contextual help and suggestions from AI

🔍 Detailed Comparison: See our Comparison Guide for detailed comparisons with n8n Web UI, CLI, Zapier, and Make.com.

Can I automate workflow creation with AI?

Yes! This is one of the key features. You can:

Describe workflows in natural language and have AI create them
Generate workflows from requirements or use cases
Modify existing workflows through conversational commands
Create workflow templates and variations automatically
Batch create similar workflows with different parameters

💼 Real Examples: Check out our Use Cases Guide for specific automation examples across different industries.

What if I encounter issues or errors?

Common solutions:

Check your n8n API key - ensure it's valid and has proper permissions
Verify n8n instance URL - make sure it's accessible and correct
Review the troubleshooting section above for specific error messages
Check GitHub Issues for known problems and solutions
Enable debug mode with DEBUG=n8n-workflow-builder for detailed logs

🔧 Comprehensive Help: See our Troubleshooting Guide for detailed solutions to common issues.

How do I get started quickly?

Fastest setup:

Use Smithery.ai hosted version (no installation): smithery.ai
Or run locally: npx @makafeli/n8n-workflow-builder
Configure your AI assistant with your n8n credentials
Start with simple commands like "list my workflows" or "show me workflow details"

📖 Detailed Guide: See our Getting Started Guide for step-by-step setup instructions.

Can I contribute or customize this MCP server?

Absolutely! This is an open-source project:

Fork the repository for customizations
Submit pull requests for improvements
Report issues or request features on GitHub
Extend functionality by adding new MCP tools
Share use cases and examples with the community

🤝 Contributing

We welcome contributions!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Useful Links

n8n Documentation - Official n8n docs
Model Context Protocol - MCP specification
Claude Desktop - AI assistant with MCP support
Cline - VS Code AI assistant
GitHub Repository - Source code and issues

Built with ❤️ for the n8n and MCP community

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "n8n Workflow Builder MCP Server",
  "description": "AI assistant integration for n8n workflow automation through the Model Context Protocol (MCP). Connect Claude Desktop, ChatGPT, and other AI assistants to n8n for natural language workflow management.",
  "url": "https://github.com/makafeli/n8n-workflow-builder",
  "downloadUrl": "https://www.npmjs.com/package/@makafeli/n8n-workflow-builder",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Cross-platform",
  "programmingLanguage": "TypeScript",
  "author": {
    "@type": "Person",
    "name": "makafeli",
    "url": "https://github.com/makafeli"
  },
  "license": "https://github.com/makafeli/n8n-workflow-builder/blob/main/LICENSE",
  "keywords": [
    "n8n",
    "MCP",
    "AI assistant",
    "workflow automation",
    "Claude Desktop",
    "ChatGPT",
    "Model Context Protocol"
  ],
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "softwareRequirements": "Node.js 18.0.0 or higher",
  "releaseNotes": "https://github.com/makafeli/n8n-workflow-builder/releases",
  "codeRepository": "https://github.com/makafeli/n8n-workflow-builder"
}

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.github		.github
.vscode		.vscode
dist		dist
scripts		scripts
src		src
test-results		test-results
tests		tests
.gitignore		.gitignore
COMPARISON.md		COMPARISON.md
GETTING_STARTED.md		GETTING_STARTED.md
LICENSE		LICENSE
README.md		README.md
RELEASE_SETUP.md		RELEASE_SETUP.md
SMITHERY_DEPLOYMENT.md		SMITHERY_DEPLOYMENT.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
USE_CASES.md		USE_CASES.md
jest.config.ci.cjs		jest.config.ci.cjs
jest.config.cjs		jest.config.cjs
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json
tsconfig.smithery.json		tsconfig.smithery.json

License

makafeli/n8n-workflow-builder

Folders and files

Latest commit

History

Repository files navigation

n8n Workflow Builder MCP Server

📚 Table of Contents

📖 Additional Documentation

🎯 What is this?

✨ Key Features

📋 Requirements

🚀 Installation & Usage

Method 1: Smithery.ai (Hosted - Recommended)

Method 2: NPX (Local)

Method 2: Manual Installation

⚙️ Configuration

Environment Variables

Getting Your n8n API Key

Setting Environment Variables

🔧 MCP Client Setup

Claude Desktop

Cline (VS Code Extension)

Other MCP Clients

🛠️ Available Tools

Core Workflow Operations

Workflow Lifecycle Management

Advanced Operations

Execution Management ⭐ NEW

Tag Management ⭐ NEW

Security & Compliance ⭐ NEW

💡 Usage Examples

Basic Operations

Creating Workflows

Workflow Management

Execution Management ⭐ NEW

Tag Management ⭐ NEW

Security Audit ⭐ NEW

🔧 Troubleshooting

Common Issues

"Connection refused" or "ECONNREFUSED"

"Unauthorized" or "401 Error"

"Workflow not found" or "404 Error"

Server won't start

Debug Mode

Getting Help

❓ Frequently Asked Questions

What is an MCP Server?

How do I connect AI assistants to n8n workflows?

Which AI assistants work with this MCP server?

Can I use this with n8n Cloud or only self-hosted?

What can AI assistants do with my n8n workflows?

Is this secure? What permissions does it need?

How is this different from using n8n's web interface?

Can I automate workflow creation with AI?

What if I encounter issues or errors?

How do I get started quickly?

Can I contribute or customize this MCP server?

🤝 Contributing

📄 License

🔗 Useful Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 6

Languages

Packages