Back to Blog

How to Connect Your Self-Hosted n8n to Claude via MCP — Complete Homelab Guide

Notion
•10 min read
TechnologyTutorialhomelabsAIDeveloper-Tools

I run a self-hosted n8n instance on my homelab behind pfSense, Nginx Proxy Manager, and a managed switch. Getting Claude Desktop to talk to n8n via the Model Context Protocol (MCP) was not straightforward — there were Node.js version conflicts, DNS resolution issues, reverse proxy gotchas, and authentication configuration to sort out.

This guide documents exactly what I did, what broke, and how I fixed it. If you run a homelab with n8n and want Claude to manage your workflows, this is the tutorial I wish I had.

What is MCP and Why Should You Care?

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude interact with external tools and services. When you connect n8n to Claude via MCP, Claude can search your workflows, read their configurations, trigger executions, and help you build new automations — all through natural conversation.

Instead of copying JSON between Claude and n8n, you just say "list my workflows" and Claude does it.

Prerequisites

Before you start, make sure you have the following ready.

Hardware and Infrastructure:

  • A self-hosted n8n instance (v2.2.0 or later, which includes built-in MCP support)

  • A machine to run Claude Desktop (macOS or Windows)

  • Network connectivity between your Mac and your n8n instance (same LAN or VPN) Software:

  • Node.js v20+ installed on your Mac (this is critical — more on this later)

  • Claude Desktop app installed from claude.ai/download

  • n8n running and accessible via HTTP on your local network My Setup for Reference:

  • n8n v2.6.4 running in Docker on Proxmox at 192.168.1.157:5678

  • Nginx Proxy Manager at 192.168.1.187 handling SSL and reverse proxying

  • pfSense firewall at 192.168.1.1 managing DNS and DHCP

  • Mac Mini connected via ethernet to a NETGEAR GS308E managed switch

  • Claude Desktop on macOS

Step 1: Enable MCP on Your n8n Instance

The first thing to do is enable MCP access inside n8n itself.

  1. Open your n8n web interface
  2. Go to Settings → Instance-level MCP
  3. Toggle Enable MCP access to ON
  4. Click the Connection details button in the top-right corner
  5. Switch to the Access Token tab
  6. Copy the generated MCP Access Token immediately — you will only see it in full once Save this token somewhere secure. You will need it for the Claude Desktop configuration.

Important: The MCP access token is tied to your user account. If you regenerate it, all connected clients will need the new token.

Step 2: Mark Workflows as MCP-Accessible

By default, no workflows are visible to MCP clients. You must explicitly enable each one.

For a workflow to be MCP-eligible, it must have a supported trigger node and be published (activated). Draft workflows will not appear.

To enable a workflow:

  1. Open the workflow in the n8n editor
  2. Click the workflow Settings gear icon
  3. Toggle Available in MCP to ON
  4. Make sure the workflow is activated (published) Alternatively, from the Settings → Instance-level MCP page, you can click Enable workflows to bulk-enable from a list.

Add a clear description to each workflow — this helps Claude understand what the workflow does and when to use it.

Step 3: Install Node.js v20+ on Your Mac

This is where most people hit their first wall. Claude Desktop uses npx to launch MCP servers, and the supergateway package (which bridges n8n's Streamable HTTP endpoint to Claude's stdio protocol) requires modern JavaScript features like the nullish coalescing assignment operator (??=) and logical assignment (&&=). These features require Node.js v20 or later.

If you use nvm (Node Version Manager):

nvm install 22
nvm alias default 22
node --version  # Should show v22.x.x

If you do not use nvm:

brew install node@22

Verify the version:

node --version
npx --version

Both should report versions associated with Node.js v20 or higher.

The gotcha I hit: I had multiple Node.js versions installed via nvm (v14, v18, v20, v22). Claude Desktop was picking up v18 by default because of the PATH order. Even after switching nvm to v22, the npx subprocess was falling back to v14 due to how nvm injects paths. The fix was to use absolute paths in the config file (see Step 4).

Step 4: Configure Claude Desktop

Open Claude Desktop and navigate to Settings → Developer → Edit Config. This opens the claude_desktop_config.json file.

Alternatively, edit it directly:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Here is the working configuration:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "/Users/YOUR_USERNAME/.nvm/versions/node/v22.12.0/bin/node",
      "args": [
        "/Users/YOUR_USERNAME/.nvm/versions/node/v22.12.0/bin/npx",
        "-y",
        "supergateway",
        "--streamableHttp",
        "http://YOUR_N8N_IP:5678/mcp-server/http",
        "--header",
        "authorization:Bearer YOUR_MCP_ACCESS_TOKEN"
      ],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Replace the placeholders:

  • YOUR_USERNAME → your macOS username
  • YOUR_N8N_IP → the local IP of your n8n instance (e.g., 192.168.1.157)
  • YOUR_MCP_ACCESS_TOKEN → the token from Step 1 Why absolute paths?

Claude Desktop does not inherit your shell's nvm configuration. It resolves npx from the system PATH, which may point to an older Node.js version. By specifying the full path to the v22 node binary as the command and the v22 npx as the first argument, you guarantee the correct runtime is used.

The env.PATH override ensures that any child processes spawned by npx also use Node.js v22 instead of falling back to an older version in the default PATH.

Save the file and fully restart Claude Desktop (Cmd+Q, then reopen — not just close the window).

Step 5: Verify the Connection

After restarting Claude Desktop, look for the MCP tools icon (a hammer icon) in the chat input area. If it appears, the connection was successful.

Test it by asking Claude: "List my n8n workflows."

Claude should return the names and details of the workflows you marked as MCP-accessible in Step 2.

If the icon does not appear, check the MCP logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

Things That Will Break (and How to Fix Them)

Node.js Version Mismatch

Symptom: SyntaxError: Unexpected token '??=' or Unexpected token '&&='

Cause: supergateway requires Node.js v20+ but Claude Desktop is using an older version.

Fix: Use absolute paths to your Node.js v22 binaries in the config. Set the env.PATH to include only the v22 bin directory. See Step 4 for the exact configuration.

DNS Resolution Failure

Symptom: Could not resolve host: n8n.yourdomain.com when using a local domain

Cause: Your Mac's DNS is not pointing to your local DNS server (e.g., pfSense or Pi-hole) that has the host override.

Fix: Set your Mac's DNS manually to your pfSense LAN IP. If using an ethernet adapter, run:

sudo networksetup -setdnsservers "YOUR_ADAPTER_NAME" 192.168.1.1

Find your adapter name with networksetup -listallnetworkservices. Also check if IPv6 DNS is taking priority over IPv4 — if your Mac has an IPv6 DNS server listed first (from an AT&T router, for example), it will try that before your local DNS.

EHOSTUNREACH on Port 443

Symptom: connect EHOSTUNREACH 192.168.1.x:443

Cause: You are using an HTTPS URL through a reverse proxy (like Nginx Proxy Manager) but port 443 is not properly mapped or the SSL certificate is not configured.

Fix: For local MCP connections, bypass the reverse proxy entirely. Use the direct HTTP URL to n8n:

http://192.168.1.x:5678/mcp-server/http

There is no security benefit to routing through SSL for a connection that never leaves your LAN.

Reverse Proxy Buffering Breaks SSE

Symptom: MCP connection drops immediately or tools timeout

Cause: Nginx Proxy Manager (or any reverse proxy) buffers responses by default, which breaks Server-Sent Events (SSE) and Streamable HTTP connections.

Fix: If you must use a reverse proxy, add this to the Advanced tab of your n8n proxy host in NPM:

location /mcp-server/ {
    proxy_http_version 1.1;
    proxy_buffering off;
    gzip off;
    chunked_transfer_encoding off;
    proxy_set_header Connection '';
}

n8n MCP Endpoint Not Found

Symptom: 404 when hitting /mcp-server/http

Cause: Your n8n version is too old, or MCP is not enabled.

Fix: Update n8n to v2.2.0 or later. Verify MCP is enabled in Settings → Instance-level MCP. Make sure at least one workflow is marked as MCP-accessible.

Architecture Overview

Here is how the pieces fit together in a typical homelab setup:

Claude Desktop (Mac)
    ↓ spawns
supergateway (Node.js v22, stdio ↔ HTTP bridge)
    ↓ HTTP POST with Bearer token
n8n (192.168.1.157:5678/mcp-server/http)
    ↓ reads
Workflows marked "Available in MCP"
    ↓ returns
Tool definitions, workflow metadata, execution results
    ↓ back to
Claude Desktop (displays tools, executes on request)

The supergateway package acts as a bridge. Claude Desktop communicates via stdio (standard input/output), while n8n's MCP server speaks Streamable HTTP. Supergateway translates between the two.

Security Considerations

Even though this is a local connection, there are some things to keep in mind.

MCP token security: Your MCP access token grants full access to all MCP-enabled workflows. Do not commit it to version control or share it publicly. Store it only in the Claude Desktop config file.

Network exposure: The n8n MCP endpoint listens on the same port as the n8n web UI. If n8n is exposed to the internet (via port forwarding or a tunnel), the MCP endpoint is also exposed. Consider restricting MCP access to your LAN only using pfSense firewall rules.

Workflow permissions: When you mark a workflow as MCP-accessible, any connected Claude client can discover and execute it. Only enable workflows you trust to be triggered by AI.

No WAN GUI access: Make sure your pfSense firewall does not allow WAN access to the web GUI. Check System → Advanced → Admin Access and verify no WAN rules are permitting inbound traffic.

What You Can Do Now

Once connected, Claude can do the following with your n8n instance through MCP:

  • Search workflows by name, description, or trigger type
  • Read workflow metadata including node configurations and trigger details
  • Execute workflows that have webhook or manual triggers
  • Help you build new workflows by understanding your existing setup and suggesting node configurations For example, you can say: "Show me all my active workflows" or "Execute the news aggregation workflow" and Claude will handle it through the MCP connection.

Summary

Connecting a self-hosted n8n instance to Claude via MCP requires getting five things right: enabling MCP in n8n, marking workflows as accessible, using the correct Node.js version, configuring absolute paths in Claude Desktop, and pointing the connection directly at n8n's local IP rather than routing through a reverse proxy.

The most common pitfall is Node.js version conflicts when you have multiple versions installed via nvm. The fix is always the same: absolute paths to the correct binaries and a clean PATH override in the config.

Once it works, the experience is seamless. Claude becomes a direct interface to your automation platform, and you can manage your homelab workflows through conversation instead of clicking through UIs.