n8n MCP Local Setup

Install

You only need Node.js 18+.

npx -y github:pedrogrigs/n8n-mcp-local-setup install

The installer asks for three things:

When it finishes, your local MCP endpoint is ready at:

http://127.0.0.1:3007/mcp

Restart Codex or Claude Code after install so they reload MCP configuration.

Related MCP server: n8n-MCP

Why Use This

The hosted n8n MCP endpoint is convenient, but a local setup is better when you want control.

What It Configures

The installer automatically:

• Installs the npm package n8n-mcp

• Runs the correct HTTP entrypoint for n8n-mcp

• Generates a strong local bearer token

• Starts a local MCP server on 127.0.0.1

• Enables autostart on login

• Configures Codex if installed

• Configures Claude Code if installed

• Replaces old configs pointing to https://api.n8n-mcp.com

• Verifies /health

• Verifies MCP tools/list when possible

Platform Support

Common Commands

Check status:

npx -y github:pedrogrigs/n8n-mcp-local-setup status

Run diagnostics:

npx -y github:pedrogrigs/n8n-mcp-local-setup doctor

Restart the local server:

npx -y github:pedrogrigs/n8n-mcp-local-setup restart

Print generic MCP client snippets:

npx -y github:pedrogrigs/n8n-mcp-local-setup snippets

Non-Interactive Install

Use this only in a secure shell session.

macOS/Linux:

N8N_API_KEY="your-api-key" npx -y github:pedrogrigs/n8n-mcp-local-setup install --yes --url https://your-n8n.example.com --port 3007

Windows PowerShell:

$env:N8N_API_KEY="your-api-key"
npx -y github:pedrogrigs/n8n-mcp-local-setup install --yes --url https://your-n8n.example.com --port 3007

Where Secrets Are Stored

The installer creates a local runtime folder:

That folder contains config.json with your n8n API key and local MCP token.

Do not publish or share that file.

Codex

The installer updates ~/.codex/config.toml and creates a backup before editing.

After installing, restart Codex and run:

/mcp

You should see n8n-mcp pointing to:

http://127.0.0.1:3007/mcp

Claude Code

If the claude command exists, the installer uses Claude Code's MCP CLI to add the local HTTP server at user scope.

After installing, restart Claude Code.

You can verify with:

claude mcp list

Agent Prompt

If you prefer to let a local coding agent run the setup, send it this prompt:

prompts/AGENT_INSTALL_PROMPT.md

The prompt includes the important implementation detail learned from real setup: for HTTP mode, run node_modules/n8n-mcp/dist/mcp/index.js, not the npm n8n-mcp stdio wrapper.

Generic MCP Config

For clients that support HTTP:

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3007/mcp",
      "headers": {
        "Authorization": "Bearer <your-local-token>"
      }
    }
  }
}

For clients that only support stdio:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3007/mcp",
        "--header",
        "Authorization: Bearer <your-local-token>"
      ]
    }
  }
}

Troubleshooting

Node.js is missing or too old:

Install Node.js LTS from https://nodejs.org, then run the installer again.

Codex or Claude Code does not show the MCP:

npx -y github:pedrogrigs/n8n-mcp-local-setup doctor

Port already in use:

npx -y github:pedrogrigs/n8n-mcp-local-setup install --port 3010

Rotate the local bearer token:

npx -y github:pedrogrigs/n8n-mcp-local-setup install --rotate-token

Project Status

This project is intentionally small: a focused installer and supervisor for local n8n-mcp.

Pull requests are welcome for:

• More MCP clients

• Better Linux desktop fallbacks

• Improved diagnostics

• Safer migration paths from existing configs

See CONTRIBUTING.md and SECURITY.md.

License

MIT