<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**

[![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)

</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>