Submit
jserna0001

n8n-free-mcp

Community jserna0001
Updated

Free & open-source MCP server for n8n - manage workflows, executions and tags from Claude, Cursor or any MCP client

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

MCP Server · Populars

MCP Server · New