# n8n-free-mcp

**Free & open-source MCP server for [n8n](https://n8n.io).** Manage your workflows, debug executions and control your self-hosted n8n instance directly from Claude Code, Claude Desktop, Cursor, or any [Model Context Protocol](https://modelcontextprotocol.io) client.

- 🆓 100% free, MIT licensed — no paywalls, no telemetry
- 🏠 Built for self-hosted / homelab n8n instances (works with n8n Cloud too)
- 🔑 Uses n8n's official public API (`/api/v1`) with your own API key
- 🪶 Tiny: one file, two dependencies (`@modelcontextprotocol/sdk` + `zod`)
- 🧠 Context-friendly: list tools return compact summaries instead of dumping full workflow JSON

## Tools

| Tool | Description |
|---|---|
| `list_workflows` | List workflows (id, name, active, tags, node count) with filters + pagination |
| `get_workflow` | Full workflow JSON: nodes, connections, settings |
| `create_workflow` | Create a new workflow from n8n-format JSON |
| `update_workflow` | Replace a workflow (read-only fields stripped automatically) |
| `activate_workflow` / `deactivate_workflow` | Toggle a workflow's triggers |
| `delete_workflow` | Delete a workflow (irreversible ⚠️) |
| `list_executions` | List executions, filter by status (`error`/`success`/`waiting`) or workflow |
| `get_execution` | Execution detail — with `includeData=true` returns per-node I/O for debugging |
| `delete_execution` | Delete an execution record |
| `list_tags` | List instance tags |
| `check_connection` | Verify the instance is reachable and the API key works |

## Setup

### 1. Get an n8n API key

In your n8n instance: **Settings → n8n API → Create an API key**.

### 2. Install

```bash
git clone https://github.com/jserna0001/n8n-free-mcp.git
cd n8n-free-mcp
npm install
npm run build
```

### 3. Configure your MCP client

**Claude Code:**

```bash
claude mcp add --scope user n8n \
  --env N8N_API_URL=https://your-n8n-instance.com \
  --env N8N_API_KEY=your-api-key \
  -- node /path/to/n8n-free-mcp/dist/index.js
```

**Claude Desktop / Cursor / other clients** (`claude_desktop_config.json`, `mcp.json`, etc.):

```json
{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/n8n-free-mcp/dist/index.js"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Alternative: `.env` file.** Instead of passing env vars from the client, copy `.env.example` to `.env` in the project root and fill it in. Environment variables from the client take precedence.

### 4. Try it

Ask your assistant things like:

- *"List my n8n workflows"*
- *"Show me the failed executions of the last runs and diagnose the error"*
- *"Deactivate the workflow called X"*
- *"Duplicate this workflow but change the webhook path"*

## Notes

- The n8n public API does not expose credential *values* (by design). Credential management tools are intentionally out of scope.
- `update_workflow` performs a full replace (`PUT`), as required by the n8n API — fetch with `get_workflow`, modify, then update.
- n8n API keys are JWTs with an expiration date. If you start getting 401s, generate a new key.

## Contributing

Issues and PRs welcome. Ideas on the roadmap:

- [ ] Trigger workflows via webhook test URLs
- [ ] Variables & projects endpoints
- [ ] npm package (`npx n8n-free-mcp`)
- [ ] Docker image

## License

[MIT](LICENSE) © Justine Serna