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

Related MCP server: mcp-n8n-builder

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