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
# 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:
{
"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:
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):
{
"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:
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "npx",
"args": ["@kernel.salacoste/n8n-workflow-builder"]
}
}
}
📖 Complete Documentation
Explore our comprehensive documentation site:
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:
┌─────────────────────────────────────┐
│ 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
- Build in Development: Create and test workflows locally
- Deploy to Staging: Validate in QA environment
- 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.jsonautomatically 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
Symptoms: Claude/Cursor can't find n8n tools
Solutions:
- Restart Claude Desktop / Cursor IDE
- Check
claude_desktop_config.json/.cursor/mcp.jsonsyntax - Verify n8n instance is accessible
- Enable debug mode:
DEBUG=truein environment
Symptoms: "Request failed with status code 404"
Solutions:
- Verify
n8n_hostuses base URL (e.g.,https://n8n.example.com) - Do NOT include
/api/v1suffix (server adds it automatically) - Check n8n API key has correct permissions
- Test connectivity:
curl https://your-n8n-instance.com/api/v1/workflows
Symptoms: "Workflow cannot be activated without valid trigger"
Solutions:
- Ensure workflow has at least one trigger node (webhook, schedule, etc.)
manualTriggeris NOT recognized by n8n API v1.82.3- Server automatically adds valid triggers if missing
Get Help
📊 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
🗺️ 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
🤝 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
# 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
📄 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
🙏 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
Made with ❤️ using Claude AI
⭐ If you find this useful, please star the repo!
