Content
# n8n MCP Server
The MCP Server connects Claude directly to n8n, allowing you to manage workflows and executions with voice commands without manual coding.
## What is MCP?
**MCP = Model Context Protocol** — A protocol that enables Claude to communicate with external tools directly.
```
Without it: You → Write curl manually → n8n API → Read the result with your eyes
With it: You → Say "check workflows" → Claude connects to n8n and brings you the result
```
## Available Commands (Tools)
| Command | Description |
|-------|-------|
| `list_workflows` | Get all workflows (or active ones only) |
| `get_workflow` | Get details of a specific workflow with all nodes |
| `create_workflow` | Create a new workflow from JSON |
| `update_workflow` | Update an existing workflow |
| `activate_workflow` | Activate a workflow |
| `deactivate_workflow` | Deactivate a workflow |
| `delete_workflow` | Delete a workflow permanently |
| `list_executions` | Get execution history (filter by ID or status) |
| `get_execution` | Get details of a specific execution with outputs of all nodes |
| `delete_execution` | Delete an execution record |
| `list_credentials` | Get names of saved credentials (without secrets) |
| `list_tags` | Get all tags |
| `list_variables` | Get all environment variables in n8n |
| `n8n_health` | Check if n8n is running |
## Installation
### 1 — Download Files
```bash
git clone https://github.com/mhiggawi/n8n-mcp-server.git
cd n8n-mcp-server
```
### 2 — Install Requirements
```bash
pip install -r requirements.txt
```
Or directly:
```bash
pip install mcp httpx
```
### 3 — Configure Claude Code Settings
Open Claude Code settings file:
- **Mac/Linux:** `~/.claude/settings.json`
- **Windows:** `%APPDATA%\Claude\settings.json`
Add this block inside `mcpServers`:
```json
{
"mcpServers": {
"n8n": {
"command": "python3",
"args": ["/full/path/to/n8n-mcp-server/server.py"],
"env": {
"N8N_BASE_URL": "https://your-n8n-url.com",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
```
> **Windows Note:** Use `python` instead of `python3` and change the path to `C:\\Users\\...`
### 4 — Restart Claude Code
Close and reopen Claude Code — the server will start automatically.
## How to Get the API Key from n8n
1. Open n8n → **Settings** → **API**
2. Click **Create API Key**
3. Copy the key and put it in `settings.json`
## Example Usage
After setup, you can say to Claude:
```
Get all active workflows in n8n
```
```
Show the last 5 executions with errors
```
```
Activate the workflow named "Send Invitations"
```
```
Check the details of execution number 12345
```
## Requirements
| Requirement | Version |
|---------|---------|
| Python | 3.10 or later |
| Claude Code CLI | Any version |
| n8n | self-hosted or cloud |
## File Structure
```
n8n-mcp-server/
├── server.py ← Main MCP server
├── requirements.txt ← Required libraries
└── README.md ← This file
```
## Important Notes
- Do not put `N8N_API_KEY` directly in the code — always use `env` in `settings.json`
- `list_credentials` returns only credential names — **never exposes secrets**
- The server uses `stdio` transport — any Claude communicates with it via stdin/stdout locally
## Common Issues
**Server not appearing in Claude:**
- Ensure the path in `args` is correct and absolute (full path)
- Ensure `python3` is installed: `python3 --version`
- Restart Claude Code after modifying `settings.json`
**Error `401 Unauthorized`:**
- The API Key is incorrect or expired — renew from n8n Settings
**Error `Connection refused`:**
- The `N8N_BASE_URL` is incorrect or n8n is not running
- Check with `curl https://your-n8n-url.com/healthz`
