n8n Workflow Builder MCP Server

AI-Powered Workflow Automation Through Natural Language

Build, manage, and monitor n8n workflows using Claude AI and Cursor IDE via the Model Context Protocol

Features • Quick Start • Documentation • Examples • API Reference

🎯 What is This?

n8n Workflow Builder MCP Server transforms workflow automation by enabling you to create and manage n8n workflows through conversational AI. No more manual JSON editing or complex UI navigation—just describe what you need in natural language, and let AI build it for you.

The Problem It Solves

• ❌ Manual workflow building is time-consuming and error-prone

• ❌ Complex JSON editing requires deep technical knowledge

• ❌ Switching between IDE and n8n UI breaks your development flow

• ❌ Managing multiple n8n environments (dev, staging, prod) is tedious

The Solution

• ✅ Build workflows conversationally using Claude AI or Cursor IDE

• ✅ Natural language interface - describe workflows in plain English

• ✅ Multi-instance support - manage dev, staging, and production from one place

• ✅ 17 powerful tools - complete workflow lifecycle management

• ✅ Stay in your IDE - no context switching required

✨ Key Features

🤖 AI-Powered Workflow Creation

Create complex n8n workflows by simply describing what you need. Claude AI and Cursor IDE understand your intent and generate production-ready workflows.

🌍 Multi-Instance Management

Seamlessly manage multiple n8n environments (production, staging, development) from a single MCP server with intelligent instance routing.

🛠️ 17 Comprehensive Tools

Complete workflow lifecycle coverage:

• 8 Workflow Tools - Create, update, delete, activate, execute

• 4 Execution Tools - Monitor, retry, analyze runs

• 5 Tag Tools - Organize and categorize workflows

• 6 Credential Tools (Epic 2) - Secure credential management

💬 Natural Language Interface

No JSON editing required. Build workflows like this:

"Create a webhook workflow that validates customer emails, sends a Slack notification, and stores data in PostgreSQL"

🔒 Secure by Design

• Built-in credential protection

• API key encryption

• Secure multi-instance configuration

• Never exposes sensitive data in logs

📚 Comprehensive Documentation

• 38+ documentation pages with guides and tutorials

• Interactive examples and workflow patterns

• Troubleshooting guides and FAQs

• API reference with complete tool documentation

🚀 Quick Start

Prerequisites

• Node.js v14+ (v18+ recommended)

• npm v7+

• n8n instance with API access (tested with n8n v1.82.3+)

• Claude Desktop or Cursor IDE

Installation

Configuration

Option 1: Multi-Instance (Recommended)

Create .config.json in your project root:

Option 2: Single Instance (Backward Compatible)

Create .env file:

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Restart Claude Desktop and you're ready to go! 🎉

Cursor IDE Integration

Add to .cursor/mcp.json in your workspace:

📖 Complete Documentation

Explore our comprehensive documentation site:

🌐 Full Documentation

Quick Links

🎨 Examples

Example 1: Create a Webhook Workflow

You:

Create a webhook workflow in staging that:

• Receives POST requests at /customer-signup

• Validates email and name fields

• Sends welcome email via Gmail

• Stores customer in PostgreSQL

Claude: ✅ Creates complete workflow with validation, email, and database nodes

Example 2: Multi-Instance Workflow Management

You:

List all active workflows in production that haven't run in the last 7 days

Claude: 📊 Analyzes production environment and identifies stale workflows

Example 3: Debug Failed Executions

You:

Debug workflow 456 in production - it's been failing with errors

Claude: 🔍 Retrieves execution history, identifies root cause, and suggests fixes

Example 4: Credential Management

You:

Show me the schema for OAuth2 credentials, then help me create credentials for Google Sheets API

Claude: 🔐 Retrieves credential schema and guides you through secure credential creation

🛠️ MCP Tools Reference

Workflow Management (8 tools)

Execution Management (4 tools)

Tag Management (5 tools)

Credential Management (6 tools - Epic 2)

🏗️ Multi-Instance Architecture

Manage multiple n8n environments with intelligent routing:

Benefits:

• ✅ Single MCP server manages all environments

• ✅ Automatic instance routing based on context

• ✅ Separate API keys per environment

• ✅ Easy environment switching in conversations

🎯 Use Cases

🚀 Development Workflow

1. Build in Development: Create and test workflows locally

2. Deploy to Staging: Validate in QA environment

3. Promote to Production: Deploy with confidence

📊 Operations & Monitoring

• Monitor execution status across environments

• Debug failed workflows with detailed analysis

• Track workflow performance and reliability

🔄 Workflow Migration

• Export workflows from one instance

• Import to another with automatic adaptation

• Bulk operations across environments

📝 Documentation & Learning

• Generate workflow documentation automatically

• Learn n8n patterns through AI guidance

• Explore workflow examples and templates

🔒 Security & Best Practices

Credential Protection

• ✅ .config.json automatically excluded from git via .gitignore

• ✅ API keys never logged (only first 20 characters shown)

• ✅ Credentials encrypted by n8n API

• ✅ No sensitive data in npm packages

Multi-Instance Security

• ✅ Separate API keys per environment

• ✅ Production keys isolated from development

• ✅ Instance validation before API calls

Safe Operations

🐛 Troubleshooting

Common Issues

Symptoms: Claude/Cursor can't find n8n tools

Solutions:

1. Restart Claude Desktop / Cursor IDE

2. Check claude_desktop_config.json / .cursor/mcp.json syntax

3. Verify n8n instance is accessible

4. Enable debug mode: DEBUG=true in environment

Full Debug Guide

Symptoms: "Request failed with status code 404"

Solutions:

1. Verify n8n_host uses base URL (e.g., https://n8n.example.com)

2. Do NOT include /api/v1 suffix (server adds it automatically)

3. Check n8n API key has correct permissions

4. Test connectivity: curl https://your-n8n-instance.com/api/v1/workflows

Configuration Guide

Symptoms: "Workflow cannot be activated without valid trigger"

Solutions:

1. Ensure workflow has at least one trigger node (webhook, schedule, etc.)

2. manualTrigger is NOT recognized by n8n API v1.82.3

3. Server automatically adds valid triggers if missing

Error Reference

Get Help

• 📚 Full Troubleshooting Guide

• 🐛 Report Issues

• 💬 GitHub Discussions

📊 What's New

Version 0.9.3 (Latest) - Security & Documentation

• 🔒 Security Fix: Prevented log files from being published to npm

• 📦 Package Optimization: Reduced size to 653KB (from 699KB)

• 📚 Documentation Enhancement: Added badges and improved npm metadata

• ✅ API Key Rotation: Updated security practices

Version 0.9.0 - MCP Protocol Compliance

• ✅ Full MCP notification handler support

• ✅ Fixed "Method 'notifications/initialized' not found" error

• 📦 Package size optimization: 1.3MB → 278KB

• 🏗️ Multi-instance architecture with intelligent routing

• 🔐 Enhanced credential management with schema validation

Epic 2 Complete (13/13 Stories) - Advanced API Implementation

• ✅ 17 MCP Tools implemented (8 workflows + 4 executions + 5 tags + 6 credentials)

• ✅ 100% test success rate across all implementations

• ✅ 12,000+ lines of documentation with comprehensive examples

• ✅ Production-ready quality with zero bugs

View Full Changelog

🗺️ Roadmap

✅ Completed

• Core workflow CRUD operations

• Execution management and monitoring

• Tag-based workflow organization

• Multi-instance architecture

• Credential lifecycle management

• Comprehensive documentation site (38+ pages)

• GitHub Pages deployment with CI/CD

🚧 In Progress

• Workflow templates library

• Enhanced error recovery patterns

• Performance optimization for large workflows

• Advanced filtering and search capabilities

🔮 Planned

• Visual workflow editor integration

• Workflow version control and rollback

• Collaborative workflow development

• Advanced analytics and insights

• Workflow marketplace and sharing

Suggest a Feature

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

• 🐛 Report Bugs: Create an issue

• 💡 Suggest Features: Open a discussion

• 📖 Improve Documentation: Submit documentation improvements

• 🔧 Submit Pull Requests: Fix bugs or add features

Development Setup

Code Standards

• ✅ TypeScript for type safety

• ✅ ESLint for code quality

• ✅ Prettier for formatting

• ✅ Jest for testing

• ✅ Conventional commits

Contributing Guide

📄 License

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

What This Means

• ✅ Commercial use allowed

• ✅ Modification allowed

• ✅ Distribution allowed

• ✅ Private use allowed

• ⚠️ No warranty provided

• ⚠️ No liability assumed

Full License Details

🙏 Acknowledgments

Built with:

• 🤖 Claude AI - AI-powered development assistance

• 🔧 n8n - Workflow automation platform

• 🔌 Model Context Protocol - AI integration standard

• 📝 TypeScript - Type-safe development

• 📚 MkDocs Material - Documentation framework

Special thanks to:

• The n8n team for building an amazing automation platform

• The Anthropic team for Claude AI and MCP

• All contributors and users providing feedback

📞 Get in Touch

• 🌐 Documentation: https://salacoste.github.io/mcp-n8n-workflow-builder/

• 📦 npm Package: https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder

• 💻 GitHub: https://github.com/salacoste/mcp-n8n-workflow-builder

• 🐛 Issues: https://github.com/salacoste/mcp-n8n-workflow-builder/issues

• 💬 Discussions: https://github.com/salacoste/mcp-n8n-workflow-builder/discussions

⬆ Back to Top

Made with ❤️ using Claude AI

⭐ If you find this useful, please star the repo!