# 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** [![Documentation](https://img.shields.io/badge/docs-latest-blue?style=flat-square&logo=readthedocs)](https://salacoste.github.io/mcp-n8n-workflow-builder/) [![npm version](https://img.shields.io/npm/v/@kernel.salacoste/n8n-workflow-builder?style=flat-square&logo=npm)](https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder) [![npm downloads](https://img.shields.io/npm/dm/@kernel.salacoste/n8n-workflow-builder?style=flat-square&logo=npm)](https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) [Features](#-key-features) • [Quick Start](#-quick-start) • [Documentation](https://salacoste.github.io/mcp-n8n-workflow-builder/) • [Examples](#-examples) • [API Reference](https://salacoste.github.io/mcp-n8n-workflow-builder/api/overview/) ![AI-Powered Workflow Builder - Build n8n workflows with natural language](./docs/assets/images/readme_01.jpg)

--- ## 🎯 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 ```bash # Install globally via npm npm install -g @kernel.salacoste/n8n-workflow-builder # Verify installation npx @kernel.salacoste/n8n-workflow-builder --version ``` ### Configuration #### Option 1: Multi-Instance (Recommended) Create `.config.json` in your project root: ```json { "environments": { "production": { "n8n_host": "https://n8n.example.com", "n8n_api_key": "your_production_api_key" }, "staging": { "n8n_host": "https://staging.n8n.example.com", "n8n_api_key": "your_staging_api_key" }, "development": { "n8n_host": "http://localhost:5678", "n8n_api_key": "your_dev_api_key" } }, "defaultEnv": "development" } ``` #### Option 2: Single Instance (Backward Compatible) Create `.env` file: ```bash N8N_HOST=https://your-n8n-instance.com N8N_API_KEY=your_api_key ``` ### Claude Desktop Integration Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "n8n-workflow-builder": { "command": "npx", "args": ["@kernel.salacoste/n8n-workflow-builder"] } } } ``` **Restart Claude Desktop** and you're ready to go! 🎉 ### Cursor IDE Integration Add to `.cursor/mcp.json` in your workspace: ```json { "mcpServers": { "n8n-workflow-builder": { "command": "npx", "args": ["@kernel.salacoste/n8n-workflow-builder"] } } } ``` --- ## 📖 Complete Documentation **Explore our comprehensive documentation site:** 🌐 **[Full Documentation](https://salacoste.github.io/mcp-n8n-workflow-builder/)** ### Quick Links | Section | Description | |---------|-------------| | 🚀 [Quick Start Tutorial](https://salacoste.github.io/mcp-n8n-workflow-builder/getting-started/quick-start/first-workflow/) | Build your first workflow in 5 minutes | | 📦 [Installation Guide](https://salacoste.github.io/mcp-n8n-workflow-builder/getting-started/installation/npm-installation/) | Detailed setup instructions | | 🔧 [Configuration](https://salacoste.github.io/mcp-n8n-workflow-builder/getting-started/installation/configuration/) | Multi-instance and environment setup | | 🛠️ [API Reference](https://salacoste.github.io/mcp-n8n-workflow-builder/api/overview/) | Complete tool documentation | | 🏗️ [Multi-Instance Setup](https://salacoste.github.io/mcp-n8n-workflow-builder/multi-instance/overview/) | Manage multiple n8n environments | | 💡 [Usage Patterns](https://salacoste.github.io/mcp-n8n-workflow-builder/guides/claude-desktop-patterns/) | Best practices and conversation patterns | | 🐛 [Troubleshooting](https://salacoste.github.io/mcp-n8n-workflow-builder/troubleshooting/faq/) | Common issues and solutions | --- ## 🎨 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) | Tool | Description | Example Use Case | |------|-------------|------------------| | `list_workflows` | List all workflows with filtering | "Show me active workflows in production" | | `get_workflow` | Retrieve complete workflow details | "Get workflow 123 from staging" | | `create_workflow` | Build new workflows from scratch | "Create a daily report workflow" | | `update_workflow` | Modify existing workflows | "Add error handling to workflow 456" | | `delete_workflow` | Remove workflows | "Delete workflow 789" | | `activate_workflow` | Enable workflow execution | "Activate workflow 123" | | `deactivate_workflow` | Disable workflow execution | "Deactivate workflow 456" | | `execute_workflow` | Manually trigger workflow runs | "Execute workflow 789 with test data" | ### Execution Management (4 tools) | Tool | Description | Example Use Case | |------|-------------|------------------| | `list_executions` | View execution history with filters | "Show failed executions from today" | | `get_execution` | Detailed execution information | "Get execution 9876 details" | | `delete_execution` | Remove execution records | "Delete old test executions" | | `retry_execution` | Retry failed workflow runs | "Retry execution 9876" | ### Tag Management (5 tools) | Tool | Description | Example Use Case | |------|-------------|------------------| | `list_tags` / `get_tags` | Retrieve all workflow tags | "Show all workflow tags" | | `get_tag` | Get specific tag information | "Get tag details for 'email-automation'" | | `create_tag` | Create workflow organization tags | "Create tag 'customer-workflows'" | | `update_tag` | Modify tag information | "Rename tag to 'legacy-workflows'" | | `delete_tag` | Remove workflow tags | "Delete tag 'deprecated'" | ### Credential Management (6 tools - Epic 2) | Tool | Description | Example Use Case | |------|-------------|------------------| | `get_credential_schema` | Get credential type JSON schema | "Show schema for httpBasicAuth" | | `list_credentials` | Security guidance (blocked by n8n API) | "List credentials guidance" | | `get_credential` | Security guidance (blocked by n8n API) | "Get credential guidance" | | `create_credential` | Create credentials with schema validation | "Create Gmail OAuth2 credentials" | | `update_credential` | Immutability guidance (DELETE + CREATE) | "Update credential guidance" | | `delete_credential` | Permanently remove credentials | "Delete credential 123" | --- ## 🏗️ Multi-Instance Architecture Manage multiple n8n environments with intelligent routing: ``` ┌─────────────────────────────────────┐ │ MCP Server (Single Instance) │ ├─────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ ConfigLoader│ EnvironmentMgr │ │ └──────────┘ └──────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────┐ │ │ │ Instance Routing │ │ │ └─────────────────────────┘ │ │ │ │ └─────────┼──────────────────────────┘ │ ┌─────┴─────┬─────────────┬──────────────┐ │ │ │ │ ▼ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ Dev │ │Staging │ │ Prod │ │Custom │ │ n8n │ │ n8n │ │ n8n │ │ n8n │ └────────┘ └────────┘ └────────┘ └────────┘ ``` **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 ``` ⚠️ IMPORTANT: Be careful with destructive operations! - Always test in development first - Use get_workflow to backup before modifications - Review workflow details before deletion - Enable debug mode for troubleshooting ``` --- ## 🐛 Troubleshooting ### Common Issues

MCP Server Connection Fails

**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](https://salacoste.github.io/mcp-n8n-workflow-builder/troubleshooting/debug-mode/)

404 Errors When Calling n8n API

**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](https://salacoste.github.io/mcp-n8n-workflow-builder/getting-started/installation/configuration/)

Workflow Activation Fails

**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](https://salacoste.github.io/mcp-n8n-workflow-builder/troubleshooting/error-reference/)

### Get Help - 📚 [Full Troubleshooting Guide](https://salacoste.github.io/mcp-n8n-workflow-builder/troubleshooting/faq/) - 🐛 [Report Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues) - 💬 [GitHub Discussions](https://github.com/salacoste/mcp-n8n-workflow-builder/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](https://salacoste.github.io/mcp-n8n-workflow-builder/about/changelog/) --- ## 🗺️ Roadmap ### ✅ Completed - [x] Core workflow CRUD operations - [x] Execution management and monitoring - [x] Tag-based workflow organization - [x] Multi-instance architecture - [x] Credential lifecycle management - [x] Comprehensive documentation site (38+ pages) - [x] 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](https://github.com/salacoste/mcp-n8n-workflow-builder/issues/new) --- ## 🤝 Contributing We welcome contributions! Here's how you can help: ### Ways to Contribute - 🐛 **Report Bugs:** [Create an issue](https://github.com/salacoste/mcp-n8n-workflow-builder/issues) - 💡 **Suggest Features:** [Open a discussion](https://github.com/salacoste/mcp-n8n-workflow-builder/discussions) - 📖 **Improve Documentation:** Submit documentation improvements - 🔧 **Submit Pull Requests:** Fix bugs or add features ### Development Setup ```bash # Clone repository git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git cd mcp-n8n-workflow-builder # Install dependencies npm install # Build project npm run build # Run tests npm test # Start development server npm run dev ``` ### Code Standards - ✅ TypeScript for type safety - ✅ ESLint for code quality - ✅ Prettier for formatting - ✅ Jest for testing - ✅ Conventional commits [Contributing Guide](https://salacoste.github.io/mcp-n8n-workflow-builder/about/contributing/) --- ## 📄 License This project is licensed under the **MIT License** - see the [LICENSE](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](https://salacoste.github.io/mcp-n8n-workflow-builder/about/license/) --- ## 🙏 Acknowledgments Built with: - 🤖 **[Claude AI](https://claude.ai/)** - AI-powered development assistance - 🔧 **[n8n](https://n8n.io/)** - Workflow automation platform - 🔌 **[Model Context Protocol](https://modelcontextprotocol.io/)** - AI integration standard - 📝 **[TypeScript](https://www.typescriptlang.org/)** - Type-safe development - 📚 **[MkDocs Material](https://squidfunk.github.io/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](#n8n-workflow-builder-mcp-server)** Made with ❤️ using Claude AI **⭐ If you find this useful, please star the repo!**