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.

📚 Table of Contents

• What is this?

• Key Features

• Requirements

• Installation & Usage

• Configuration

• MCP Client Setup

• Available Tools

• Usage Examples

• Troubleshooting

• FAQ

• Contributing

• License

• Useful Links

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

1. Visit: smithery.ai

2. Search: "n8n-workflow-builder"

3. Connect: Configure with your n8n host and API key

4. 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:

Method 2: Manual Installation

For development or customization:

⚙️ Configuration

Environment Variables

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

Getting Your n8n API Key

1. Open your n8n instance

2. Go to Settings → API Keys

3. Click Create API Key

4. Copy the generated key

Setting Environment Variables

🔧 MCP Client Setup

Claude Desktop

Add this configuration to your claude_desktop_config.json:

Cline (VS Code Extension)

Add this to your Cline MCP settings:

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

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"

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

Getting Help

1. Check the GitHub Issues

2. Review n8n's API documentation

3. 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:

1. Install the MCP server: npx @makafeli/n8n-workflow-builder

2. Configure your AI assistant's MCP settings with your n8n credentials

3. 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:

1. Check your n8n API key - ensure it's valid and has proper permissions

2. Verify n8n instance URL - make sure it's accessible and correct

3. Review the troubleshooting section above for specific error messages

4. Check GitHub Issues for known problems and solutions

5. 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:

1. Use Smithery.ai hosted version (no installation): smithery.ai

2. Or run locally: npx @makafeli/n8n-workflow-builder

3. Configure your AI assistant with your n8n credentials

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