# 🤖 n8n MCP Server - Control n8n with Claude AI

> **Give Claude AI full control over your n8n workflows through natural conversation**

[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

---

## 🎯 What This Does (In Plain English)

Instead of clicking through n8n's web interface, you can now **talk to Claude** and have it manage your workflows:

**You say:** *"Show me all my workflows"*
**Claude does:** Lists all your n8n workflows with their status

**You say:** *"Activate my Daily Report workflow"*
**Claude does:** Turns on that workflow for you

**You say:** *"What workflows failed today?"*
**Claude does:** Shows you failed executions with error details

It's like having an AI assistant that knows how to use n8n for you.

---

## ✨ What You'll Be Able To Do

Once set up, you can ask Claude to:

### 📋 Workflow Management
- ✅ List all your workflows
- ✅ Create new workflows
- ✅ Activate/deactivate workflows
- ✅ Update workflow settings
- ✅ Delete workflows
- ✅ Organize workflows with tags

### ⚡ Execution Monitoring
- ✅ See which workflows ran successfully
- ✅ Find failed executions
- ✅ Retry failed workflows
- ✅ Get detailed error information
- ✅ Track execution history

### 🔧 Advanced Features
- ✅ Manage environment variables
- ✅ Handle credentials securely
- ✅ Manage users and projects
- ✅ Generate security audits
- ✅ Health check your n8n instance

**Total: 42 different operations** - all through natural conversation with Claude.

---

## 🤔 Before You Start: What Are These Things?

### What is MCP (Model Context Protocol)?
Think of it as a "universal connector" that lets Claude AI talk to other software. It's like teaching Claude how to use n8n by giving it a specialized plugin.

**Official docs:** https://modelcontextprotocol.io/

### What is n8n?
n8n is a workflow automation tool (like Zapier, but self-hosted). It connects different apps and automates tasks. For example: "When I get an email, save it to Google Sheets and notify me on Slack."

**n8n website:** https://n8n.io/

### What is Docker?
Docker packages software so it runs the same way on any computer. Think of it as a "container" for software - it includes everything needed to run, so you don't have to install dependencies manually.

**Docker website:** https://www.docker.com/

---

## 📋 Prerequisites (What You Need First)

Before starting, make sure you have:

### 1. **Docker Desktop** (Required)
- **Download:** https://www.docker.com/products/docker-desktop
- **Install it** and make sure it's running (you'll see the Docker icon in your system tray)
- **Test it works:** Open terminal/command prompt and type:
  ```bash
  docker --version
  ```
  You should see something like: `Docker version 24.0.0`

### 2. **n8n Instance with API Access** (Required)
You need:
- ✅ A running n8n instance (self-hosted or cloud)
- ✅ The URL to your n8n (e.g., `https://your-n8n.com`)
- ✅ An API key from n8n

**How to get your n8n API key:**
1. Log into your n8n instance
2. Click your profile icon (top right)
3. Go to "Settings" → "API"
4. Click "Create API Key"
5. Copy the key (starts with `eyJ...`) - you'll need this later

### 3. **Claude Desktop** (Required)
- **Download:** https://claude.ai/download
- Install the desktop app (not just the web version)

### 4. **Docker MCP Gateway** (Required)
This is the "bridge" between Claude and Docker containers.

**Install it:**
```bash
# On macOS/Linux
curl -fsSL https://raw.githubusercontent.com/docker/mcp-gateway/main/install.sh | sh

# On Windows (PowerShell as Administrator)
irm https://raw.githubusercontent.com/docker/mcp-gateway/main/install.ps1 | iex
```

**Verify it installed:**
```bash
docker mcp --version
```

**Official docs:** https://github.com/docker/mcp-gateway

### 5. **Basic Terminal Knowledge** (Helpful but not required)
You'll need to copy-paste commands into a terminal. Don't worry - we'll guide you through each one.

---

## 🚀 Installation Guide (Step-by-Step)

Follow these steps **exactly** in order. Each step has a "✅ Success Check" so you know it worked.

### Step 0: Enable Docker MCP Toolkit (IMPORTANT!)

Before anything else, you need to enable MCP support in Docker Desktop:

1. **Open Docker Desktop**
2. Click the **Settings** icon (gear icon, top right)
3. Go to **Beta features** (in the left sidebar)
4. Find **"Enable Docker MCP Toolkit"**
5. **Check the box** to enable it
6. Click **"Apply & Restart"**
7. Wait for Docker Desktop to restart

**✅ Success Check:** After restart, open terminal and run:
```bash
docker mcp --version
```
You should see version information (not an error).

---

### Step 1: Download This Project

**Option A: Using Git (if you have it)**
```bash
cd ~/Desktop
git clone https://github.com/Shravan1610/n8n-mcp-server.git
cd n8n-mcp-server
```

**Option B: Download ZIP**
1. Go to https://github.com/Shravan1610/n8n-mcp-server
2. Click the green "Code" button
3. Click "Download ZIP"
4. Unzip it to your Desktop
5. Open terminal and navigate to it:
   ```bash
   cd ~/Desktop/n8n-mcp-server-main
   ```

**✅ Success Check:** Run `ls` - you should see files like `README.md`, `package.json`, `Dockerfile`

---

### Step 2: Configure Your n8n Connection

**Create your environment file:**
```bash
cp .env.example .env
```

**Edit the `.env` file:**

1. **On Mac/Linux:**
   ```bash
   nano .env
   ```

2. **On Windows:**
   ```bash
   notepad .env
   ```

3. **Fill in your n8n details:**
   ```env
   N8N_API_KEY=paste_your_actual_n8n_api_key_here
   N8N_BASE_URL=https://your-n8n-instance.com/api/v1
   ```

   **Important notes:**
   - Replace `paste_your_actual_n8n_api_key_here` with the API key you got from n8n
   - Replace `https://your-n8n-instance.com` with your actual n8n URL
   - **DO NOT add a trailing slash** at the end of the URL
   - Keep `/api/v1` at the end

4. **Save the file:**
   - In nano: Press `Ctrl+O`, then `Enter`, then `Ctrl+X`
   - In notepad: File → Save

**Example `.env` file (with YOUR actual values):**
```env
N8N_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your_actual_key_here
N8N_BASE_URL=https://your-actual-n8n-url.com/api/v1
```

**✅ Success Check:** Run `cat .env` (Mac/Linux) or `type .env` (Windows) - you should see your API key and URL (not the placeholder text)

---

### Step 3: Build the Docker Container

This packages everything needed to run the MCP server.

**Run the build script:**

**On Mac/Linux:**
```bash
chmod +x build.sh
./build.sh
```

**On Windows:**
```bash
docker build -t n8n-mcp-server:latest .
```

**This will take 2-3 minutes.** You'll see lots of output - that's normal.

**✅ Success Check:** Run `docker images | grep n8n-mcp-server` - you should see the image listed with "latest" tag

---

### Step 4: Test the Server (Optional but Recommended)

Let's make sure it can connect to your n8n instance.

**Run the test:**

**On Mac/Linux:**
```bash
chmod +x test.sh
./test.sh
```

**On Windows:**
```bash
docker run --rm -i --env-file .env n8n-mcp-server:latest
```
Then paste this and press Enter:
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
```
Press `Ctrl+C` to exit.

**✅ Success Check:** You should see a JSON response (not an error). If you see "Unexpected token" or connection errors, check your `.env` file.

---

### Step 5: Set Up Docker MCP Gateway

Now we tell Docker MCP Gateway about our n8n server.

**Initialize the gateway (first time only):**
```bash
docker mcp catalog init
```

**Add the n8n server configuration:**

1. **Edit the Docker MCP config file:**

   **On Mac/Linux:**
   ```bash
   nano ~/.docker/mcp/docker-mcp.yaml
   ```

   **On Windows:**
   ```bash
   notepad %USERPROFILE%\.docker\mcp\docker-mcp.yaml
   ```

2. **Add this configuration at the end:**
   ```yaml
   n8n-server:
     image: n8n-mcp-server:latest
     environment:
       N8N_API_KEY: paste_your_actual_n8n_api_key_here
       N8N_BASE_URL: https://your-n8n-instance.com/api/v1
     description: "n8n workflow automation MCP server"
   ```

3. **Replace the placeholder values:**
   - Use the **same API key** from your `.env` file
   - Use the **same n8n URL** from your `.env` file

4. **Save the file**

**Enable the server:**
```bash
docker mcp server enable n8n-server
```

**✅ Success Check:** Run `docker mcp server list` - you should see `n8n-server` with status "enabled"

---

### Step 6: Connect to Claude Desktop

**Option A: Automatic (Docker MCP Gateway handles it)**

The Docker MCP Gateway should automatically configure Claude Desktop. Just **completely quit and restart Claude Desktop.**

**Option B: Manual Configuration (if automatic doesn't work)**

1. **Find your Claude Desktop config file:**
   - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

2. **Edit the file:**

   **On Mac:**
   ```bash
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

   **On Windows:**
   ```bash
   notepad %APPDATA%\Claude\claude_desktop_config.json
   ```

3. **Add or update the configuration:**
   ```json
   {
     "mcpServers": {
       "docker-mcp-gateway": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "docker-mcp-gateway"]
       }
     }
   }
   ```

4. **Save the file**

**Restart Claude Desktop:**
- **Don't just close the window** - fully quit the app:
  - **Mac:** Claude Desktop → Quit Claude Desktop (or Cmd+Q)
  - **Windows:** Right-click the system tray icon → Exit
- **Start Claude Desktop again**

**✅ Success Check:** Open Claude Desktop and start a new conversation. Type "What n8n tools do you have?" - Claude should list the 42 available tools. If not, see troubleshooting below.

---

## 🎉 You're Done! Now What?

Try asking Claude these things:

### Basic Commands
```
"List all my n8n workflows"
"Show me the details of workflow [name]"
"What's the health status of my n8n instance?"
```

### Workflow Management
```
"Activate my [workflow name] workflow"
"Deactivate the [workflow name] workflow"
"Show me all inactive workflows"
```

### Execution Monitoring
```
"Show me all failed executions from today"
"What went wrong with execution [id]?"
"Retry execution [id]"
```

### Advanced Operations
```
"List all environment variables"
"Create a variable named API_URL with value https://api.example.com"
"Show me all users in my n8n instance"
```

---

## 🆘 Troubleshooting (Common Issues)

### Issue 1: "Docker MCP command not found"

**Symptoms:** `docker mcp: command not found`

**Solution:**
1. **Make sure Docker MCP Toolkit is enabled:**
   - Open Docker Desktop
   - Settings → Beta Features → Enable Docker MCP Toolkit
   - Apply & Restart

2. **Reinstall Docker MCP Gateway:**
   ```bash
   curl -fsSL https://raw.githubusercontent.com/docker/mcp-gateway/main/install.sh | sh
   ```

---

### Issue 2: "Tools not showing in Claude"

**Symptoms:** Claude says it doesn't have n8n tools available

**Solutions:**
1. **Verify Docker MCP Gateway is running:**
   ```bash
   docker mcp server list
   ```
   Make sure `n8n-server` shows as "enabled"

2. **Enable the server if it's disabled:**
   ```bash
   docker mcp server enable n8n-server
   ```

3. **Completely restart Claude Desktop:**
   - Quit (don't just close)
   - Wait 5 seconds
   - Start again

4. **Check Docker is running:**
   - Look for Docker icon in system tray
   - Should show "Docker Desktop is running"

---

### Issue 3: "Cannot connect to n8n" or "401 Unauthorized"

**Symptoms:** Claude says it can't reach your n8n instance or authentication fails

**Solutions:**
1. **Verify your API key works:**
   ```bash
   curl -H "X-N8N-API-KEY: your_api_key" "https://your-n8n.com/api/v1/workflows?limit=1"
   ```
   Replace with your actual values. You should get JSON response, not an error.

2. **Check your `.env` file:**
   ```bash
   cat .env
   ```
   Make sure:
   - API key is correct (starts with `eyJ`)
   - URL has no trailing slash
   - URL ends with `/api/v1`

3. **Check the Docker MCP config:**
   ```bash
   cat ~/.docker/mcp/docker-mcp.yaml
   ```
   Make sure the values match your `.env` file

4. **Rebuild the server:**
   ```bash
   ./build.sh
   docker mcp server disable n8n-server
   docker mcp server enable n8n-server
   ```

---

### Issue 4: "Unexpected non-whitespace character" Error

**Symptoms:** JSON parsing errors when testing

**This should be fixed in this version.** If you still see it:

1. **Make sure you're using the latest code:**
   ```bash
   git pull origin main
   ./build.sh
   ```

2. **Verify the image was rebuilt:**
   ```bash
   docker images | grep n8n-mcp-server
   ```
   Check the "CREATED" date - should be recent

---

### Issue 5: "Permission Denied" Errors

**On Mac/Linux:**
```bash
chmod +x build.sh test.sh
./build.sh
```

**On Windows:** Run PowerShell as Administrator

---

## 🤔 Common Mistakes (Learn from Others!)

### ❌ Mistake 1: Forgetting to Enable Docker MCP Toolkit
**The #1 issue!** You MUST enable this in Docker Desktop Settings → Beta Features before anything will work.

### ❌ Mistake 2: Adding Trailing Slash to URL
**Wrong:**
```env
N8N_BASE_URL=https://n8n.example.com/api/v1/
```
**Correct:**
```env
N8N_BASE_URL=https://n8n.example.com/api/v1
```

### ❌ Mistake 3: Forgetting to Quit Claude Desktop
Closing the window isn't enough - you must **fully quit the app** for config changes to take effect.

### ❌ Mistake 4: Using Wrong API Key
Make sure you're using an n8n **API key**, not your login password. Get it from: n8n Settings → API → Create API Key

### ❌ Mistake 5: Docker Not Running
The Docker icon must be in your system tray and show "running" status. If Docker isn't running, nothing will work.

### ❌ Mistake 6: Not Enabling the Server
After editing `docker-mcp.yaml`, you must run:
```bash
docker mcp server enable n8n-server
```

---

## 🎓 How It Works (For the Curious)

Here's what happens behind the scenes:

1. **You talk to Claude** in natural language
2. **Claude understands** what you want to do with n8n
3. **Claude calls** the Docker MCP Gateway
4. **The Gateway launches** your n8n MCP server container
5. **The MCP server** makes API calls to your n8n instance
6. **n8n responds** with the data
7. **The response flows back** through Gateway → Claude → You

It's like having a translator that speaks "Human" on one side and "n8n API" on the other.

---

## 📚 Available Tools (All 42 of Them)

<details>
<summary>Click to expand the complete list</summary>

### Workflow Management (10 tools)
- `n8n_list_workflows` - List all workflows with pagination
- `n8n_get_workflow` - Get detailed workflow information
- `n8n_create_workflow` - Create new workflows
- `n8n_update_workflow` - Modify existing workflows
- `n8n_delete_workflow` - Delete workflows
- `n8n_activate_workflow` - Enable workflows
- `n8n_deactivate_workflow` - Disable workflows
- `n8n_transfer_workflow` - Transfer workflows between projects
- `n8n_get_workflow_tags` - Get workflow tags
- `n8n_update_workflow_tags` - Update workflow tags

### Execution Management (4 tools)
- `n8n_list_executions` - List executions with filtering
- `n8n_get_execution` - Get detailed execution information
- `n8n_delete_execution` - Delete execution records
- `n8n_retry_execution` - Retry failed executions

### Credentials Management (4 tools)
- `n8n_create_credential` - Create new credentials
- `n8n_delete_credential` - Delete credentials
- `n8n_get_credential_schema` - Get credential schemas
- `n8n_transfer_credential` - Transfer credentials

### Variables Management (4 tools)
- `n8n_list_variables` - List environment variables
- `n8n_create_variable` - Create new variables
- `n8n_update_variable` - Update existing variables
- `n8n_delete_variable` - Delete variables

### Tags Management (5 tools)
- `n8n_list_tags` - List all tags
- `n8n_create_tag` - Create new tags
- `n8n_get_tag` - Get tag details
- `n8n_update_tag` - Update tag names
- `n8n_delete_tag` - Delete tags

### Users Management (5 tools)
- `n8n_list_users` - List all users
- `n8n_create_user` - Create new users
- `n8n_get_user` - Get user details
- `n8n_delete_user` - Delete users
- `n8n_update_user_role` - Update user roles

### Projects Management (7 tools)
- `n8n_list_projects` - List all projects
- `n8n_create_project` - Create new projects
- `n8n_update_project` - Update project details
- `n8n_delete_project` - Delete projects
- `n8n_add_user_to_project` - Add users to projects
- `n8n_remove_user_from_project` - Remove users
- `n8n_update_user_in_project` - Update user roles

### Audit & Monitoring (3 tools)
- `n8n_generate_audit` - Generate security audits
- `n8n_pull_source_control` - Pull from source control
- `n8n_health_check` - Check instance health

</details>

---

## 🔒 Security & Privacy

**What data does this share?**
- Only the data you ask Claude to fetch from n8n
- Your n8n API key stays on your computer (in `.env` file)
- No data is sent to third parties

**Best practices:**
- ✅ Never commit `.env` file to Git (it's in `.gitignore`)
- ✅ Use read-only API keys if possible
- ✅ Rotate your API keys periodically
- ✅ Don't share your `.env` file with anyone

**Docker security:**
- ✅ Runs as non-root user
- ✅ No privileged access required
- ✅ Isolated container environment

---

## 💡 Pro Tips

### Tip 1: Create Shortcuts
Save common commands as Claude conversations for quick access.

### Tip 2: Combine Operations
You can ask Claude to do multiple things at once:
*"Show me all failed workflows from today, then retry each one"*

### Tip 3: Use Descriptive Workflow Names
Claude works better when your workflows have clear names like "Daily Email Report" instead of "Workflow 1"

### Tip 4: Ask for Explanations
Claude can explain what workflows do: *"Explain what my 'Customer Onboarding' workflow does"*

### Tip 5: Monitor in Real-Time
Ask Claude to check execution status while workflows are running

---

## 🚀 Next Steps

Now that you have it working:

1. **⭐ Star this repo** if it helped you!
2. **🔁 Share** with other n8n users
3. **💬 Give feedback** - what features do you want added?
4. **🐛 Report bugs** via GitHub Issues
5. **🤝 Contribute** - PRs welcome!

---

## 📞 Need Help?

- **GitHub Issues:** https://github.com/Shravan1610/n8n-mcp-server/issues
- **n8n API Docs:** https://docs.n8n.io/api/
- **MCP Documentation:** https://modelcontextprotocol.io/
- **Docker MCP Gateway:** https://github.com/docker/mcp-gateway

---

## 🙏 Acknowledgments

Built with:
- [Anthropic MCP SDK](https://github.com/anthropics/mcp)
- [n8n API](https://docs.n8n.io/api/)
- [Docker MCP Gateway](https://github.com/docker/mcp-gateway)

---

## 🎯 About This Project

This is **Day 1** of my 30-day challenge to build useful AI integrations.

Built in one session. Open sourced for the community.

**More projects coming!** Follow for daily updates.

---

**⭐ If this saved you time, drop a star on GitHub!**

**Built with Model Context Protocol | 42 Tools | Production Ready**