# n8n MCP Server

An [MCP](https://modelcontextprotocol.io) server that lets any MCP-compatible
client (Claude Code, Claude Desktop, etc.) manage workflows and executions on
**your own self-hosted n8n instance**, via n8n's public REST API. Runs locally
over stdio — your n8n URL and API key never leave your machine.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- A running n8n instance with the [public API](https://docs.n8n.io/api/) enabled
- An n8n API key (n8n → Settings → API)

## Setup

1. Clone this repository and install dependencies:

   ```bash
   git clone https://github.com/mastrangi/mcp-n8n.git
   cd mcp-n8n
   uv sync
   ```

2. Create `.env` (never committed) from the template:

   ```bash
   cp .env.example .env
   ```

   Fill in:
   - `N8N_URL` — your n8n instance's base URL (e.g. `https://n8n.example.com`)
   - `N8N_API_KEY` — generated from your n8n instance's Settings → API page

3. Register with your MCP client. For Claude Code, run from the directory
   you cloned this repo into:

   ```bash
   claude mcp add n8n -- uv run --directory "$(pwd)" n8n-mcp
   ```

   For other clients, point them at the same command
   (`uv run --directory /absolute/path/to/mcp-n8n n8n-mcp`) using stdio transport.

4. Verify it's connected:

   ```bash
   claude mcp list
   ```

## Tools

| Tool | Description |
|---|---|
| `list_workflows` | List workflows, filtered by active status, name, or tags |
| `get_workflow` | Get a workflow's full definition by ID |
| `create_workflow` | Create a workflow from nodes/connections/settings (pass `parentFolderId` in the workflow object to place it in a folder) |
| `update_workflow` | Replace a workflow's definition |
| `delete_workflow` | Delete a workflow by ID |
| `activate_workflow` | Activate a workflow |
| `deactivate_workflow` | Deactivate a workflow |
| `list_executions` | List executions, filtered by workflow or status |
| `get_execution` | Get a specific execution's details |
| `execute_workflow` | Trigger a workflow via its Webhook trigger node (only works for workflows that have one and are active — n8n's public API has no generic "run by ID" endpoint), optionally forwarding `data` as the webhook's JSON body |
| `list_folders` | List folders in a project, filtered by parent folder or name |
| `create_folder` | Create a folder in a project, optionally nested under a parent folder |

## Why no `execute_workflow_by_id`?

n8n's public REST API has no generic "run this workflow now" endpoint —
only workflows with a Webhook trigger node can be invoked externally, by
calling that webhook directly. `execute_workflow` does exactly that: it
looks up the workflow's Webhook node and calls it, returning an error that
explains why when the workflow has no webhook or isn't active.

## Development

```bash
uv run pytest -v
```

## Security

- `N8N_API_KEY` lives only in your local `.env` file, which is gitignored.
  No tool logs, prints, or returns the key.
- `execute_workflow` calls the target webhook without the n8n API key
  attached — n8n's Webhook node captures request headers into execution
  data, so sending the key there would let it leak back out through
  `get_execution(include_data=True)`.

## License

MIT — see [LICENSE](LICENSE).