mcp-n8n-workflow-builder
AI-powered n8n workflow automation through natural language. MCP server enabling Claude AI & Cursor IDE to create, manage, and monitor workflows via Model Context Protocol. Multi-instance support, 17 tools, comprehensive docs. Build workflows conversationally without manual JSON editing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/salacoste--mcp-n8n-workflow-builder)HTML
<a href="/listings/salacoste--mcp-n8n-workflow-builder"><img src="/api/listings/salacoste--mcp-n8n-workflow-builder/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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"]
}
}
}---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md ยท README ยท 578 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # 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**
- [](https://salacoste.github.io/mcp-n8n-workflow-builder/)
- [](https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder)
- [](https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder)
- [](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/)
- 
- </div>
- ---
- ## ๐ฏ 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
- <table>
- <tr>
- <td width="50%">
- ### ๐ค 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
- </td>
- <td width="50%">
- ### ๐ฌ 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
- </td>
- </tr>
- </table>
- ---
- ## ๐ 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
- <details>
- <summary><b>MCP Server Connection Fails</b></summary>
- **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/)
- </details>
- <details>
- <summary><b>404 Errors When Calling n8n API</b></summary>
- **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/)
- </details>
- <details>
- <summary><b>Workflow Activation Fails</b></summary>
- **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/)
- </details>
- ### 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
- ---
- <div align="center">
- **[โฌ Back to Top](#n8n-workflow-builder-mcp-server)**
- Made with โค๏ธ using Claude AI
- **โญ If you find this useful, please star the repo!**
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itโs helped, pass it on.