Content
# 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
