# ⚡ n8n-MCP

<div align="center">
  
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fmutaharhashmi%2Fn8n--mcp-green.svg)](https://github.com/mutaharhashmi/n8n-mcp/pkgs/container/n8n-mcp)
[![Tests](https://img.shields.io/badge/tests-3336%20passing-brightgreen.svg)](https://github.com/mutaharhashmi/n8n-mcp/actions)

**The Bridge Between Workflow Automation and AI Intelligence**

[Overview](#-overview) • [Quick Start](#-quick-start) • [IDE Setup](#-ide--tool-support) • [Deployment](#-deployment) • [Documentation](#-documentation)

</div>

---

## 🌟 Overview

**n8n-MCP** is a Model Context Protocol (MCP) server that empowers AI assistants (Claude, Cursor, etc.) with deep knowledge of [n8n](https://n8n.io). It provides structured access to documentation, properties, and operations for over **1,200 nodes**, enabling AI to build, validate, and manage your workflows with 100% accuracy.

### ✨ Key Features
- 📚 **1,084+ Nodes Indexed**: Full coverage of core and verified community nodes.
- ⚡ **Proprietary Validation**: Smart config checks that prevent runtime failures.
- 💡 **Real-World Examples**: 2,600+ pre-extracted configurations for instant use.
- 🎯 **Template Library**: 2,700+ workflow templates with smart discovery.
- 🤖 **AI-Optimized**: Designed for parallel execution and token efficiency.

---

## 🚀 Quick Start

### Option 1: Hosted Service (Instant) ☁️
The fastest way to try n8n-MCP with zero setup.  
👉 **[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)**

### Option 2: Local Setup (npx) 💻
Run directly in your terminal or connect to Claude Desktop:
```bash
npx n8n-mcp
```

**Add to Claude Desktop (`claude_desktop_config.json`):**
```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["-y", "n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}
```

---

## 💻 IDE & Tool Support

n8n-MCP works seamlessly with these AI-powered environments:

| Tool | Setup Guide |
| :--- | :--- |
| **Claude Desktop** | [View Guide](./docs/README_CLAUDE_SETUP.md) |
| **Claude Code** | [View Guide](./docs/CLAUDE_CODE_SETUP.md) |
| **Cursor** | [View Guide](./docs/CURSOR_SETUP.md) |
| **Windsurf** | [View Guide](./docs/WINDSURF_SETUP.md) |
| **VS Code** | [View Guide](./docs/VS_CODE_PROJECT_SETUP.md) |
| **Antigravity** | [View Guide](./docs/ANTIGRAVITY_SETUP.md) |

---

## 📦 Deployment Options

### 🐳 Docker (Recommended)
Ultra-optimized image (~120MB memory footprint).
```bash
docker pull ghcr.io/mutaharhashmi/n8n-mcp:latest
```
See [Docker Guide](./docs/DOCKER_README.md) for full configuration.

### ☁️ Railway (One-Click)
Deploy to the cloud in minutes.  
[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)

### 🏗️ Local Installation (Developers)
```bash
git clone https://github.com/mutaharhashmi/n8n-mcp.git
cd n8n-mcp
npm install && npm run build && npm run rebuild
```

---

## 🛠️ n8n Integration

Take control of your n8n instance by adding API credentials to your environment:

```env
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key
```
This unlocks **13+ management tools** to create, update, and test workflows directly from your AI assistant. See [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md).

---

## 🤖 AI Orchestration (Pro Tip)

For the best results when using n8n-MCP with **Claude Projects**, use our [Enhanced System Instructions](./docs/CLAUDE_PROJECT_PROMPT.md). It teaches the AI to use parallel execution and multi-level validation for production-ready workflows.

---

## 📚 Documentation & Resources

- 📂 **[Full Installation Guide](./docs/INSTALLATION.md)**
- 🕵️ **[Troubleshooting Guide](./docs/DOCKER_TROUBLESHOOTING.md)**
- 💬 **[Why n8n-MCP? (Claude Testimonial)](./docs/USER_TESTIMONIALS.md)**
- 🆕 **[Changelog](./CHANGELOG.md)**
- 🔒 **[Privacy Policy](./PRIVACY.md)** & **[Security](./SECURITY.md)**

---

<!-- Sponsor section removed for branding update -->

---

<div align="center">
  Built with ❤️ by <strong>Mutahar Hashmi</strong><br>
  <sub>Making AI + n8n workflow creation delightful</sub>
</div>