Troubleshooting

/mcp doesn't show n8n-mcp after /n8n-init

MCP server registrations are loaded when Claude Code starts. After /n8n-init writes .mcp.json, restart Claude Code (close and reopen) — the server will appear in /mcp on the next start.

"Node not found" when building

Almost always a nodeType prefix mismatch:

• Search/validate tools need the short prefix: nodes-base.slack
• Workflow tools need the full prefix: n8n-nodes-base.slack

search_nodes returns both — nodeType is for search/validate, workflowNodeType is for n8n_create_workflow and friends.

API key rejected

1. Verify the key at <your-n8n-url>/settings/api — is it still there and active?
2. Confirm the n8n user who owns the key has permission to list/create workflows.
3. For self-hosted: check that the public API is enabled (N8N_PUBLIC_API_DISABLED=false).
4. Check .mcp.json — the key field is N8N_API_KEY, and there shouldn't be extra quotes or whitespace.

/n8n-init won't overwrite files

Intended. It asks for confirmation to protect pre-existing work. If you really want to overwrite, say yes at the prompt.

Workflow validation passes but runtime fails

Validation checks configuration, not runtime behavior. Common runtime-only failures:

• Credentials not attached — n8n-mcp can't see your saved credentials. Attach them in the n8n UI after the workflow is created.
• External API rate limits — the n8n Executions panel will show the actual error.
• Expression evaluation — test expressions in the n8n UI; the n8n-expression-syntax skill helps.

Agent tries to use full prefix in search

If a subagent calls search_nodes({query: "n8n-nodes-base.slack"}) or similar, something's wrong. Re-invoke the skill n8n-mcp-tools-expert — it encodes the format rules. If it keeps happening, open an issue against the repo.

"Connection refused" when MCP starts

n8n-mcp is installed on-demand via npx -y n8n-mcp. First run takes longer; subsequent runs are cached. If it keeps failing:

• Confirm node and npm are installed and on PATH.
• Clear the npx cache and retry: npx clear-npx-cache (or delete ~/.npm/_npx/).

Credentials leaked — .mcp.json ended up in git

1. Rotate the key immediately at <your-n8n-url>/settings/api.
2. Remove from git history: git filter-repo --path .mcp.json --invert-paths (or similar).
3. Add .mcp.json to .gitignore (/n8n-init does this automatically; if it's missing, that's a bug — please report).

Something else

Open an issue at the repo with:

• Claude Code version
• Plugin version (from /plugin list)
• What you ran and what happened
• Any error output