n8n-free-mcp

Free & open-source MCP server for n8n. Manage your workflows, debug executions and control your self-hosted n8n instance directly from Claude Code, Claude Desktop, Cursor, or any Model Context Protocol 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

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:

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.):

{
  "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 © Justine Serna