n8n-MCP koppelen aan je eigen n8n-instantie

Dit bestand is door ToolBrain vertaald en inhoudelijk gewijzigd op 2026-08-30, op basis van "n8n-MCP Deployment Guide" uit czlonkowski/n8n-mcp (MIT), zie https://github.com/czlonkowski/n8n-mcp/blob/f895e5ecc732aed31e2ca9748027034f5b19cccd/docs/N8N_DEPLOYMENT.md en ../LICENSES/n8n-mcp-MIT.txt.

Deze handleiding gaat over de omgekeerde koppeling: niet Claude Desktop die met n8n-MCP praat, maar n8n zelf die via de ingebouwde "MCP Client Tool"-node verbinding maakt met een n8n-MCP- server. Zo kun je binnen een n8n-workflow een AI Agent-node laten werken met n8n-documentatie, workflow-validatie en workflowbeheer.

Wat dit oplevert

• AI-ondersteunde workflow-creatie en -validatie, direct vanuit een n8n-workflow
• Toegang tot documentatie van 500+ n8n-nodes
• Workflowbeheer via de n8n-API
• Real-time validatie van node-configuraties

Lokaal testen

Snelle testscript

git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build

./scripts/test-n8n-integration.sh

Dit script start een echte n8n-instantie in Docker, start de n8n-MCP-server in de juiste modus, begeleidt je bij het instellen van een API-key, en test de volledige integratie.

Handmatige lokale setup

Vereisten: een draaiende n8n-instantie (lokaal of remote) en een n8n-API-key (n8n → Settings → API).

export N8N_MODE=true
export MCP_MODE=http                       # verplicht voor HTTP-modus
export N8N_API_URL=http://localhost:5678   # jouw n8n-URL
export N8N_API_KEY=jouw-api-key
export WEBHOOK_SECURITY_MODE=moderate      # verplicht als N8N_API_URL localhost of RFC1918 is
export MCP_AUTH_TOKEN=test-token-minimaal-32-tekens-lang
export AUTH_TOKEN=test-token-minimaal-32-tekens-lang   # zelfde waarde als MCP_AUTH_TOKEN
export PORT=3001

npm start

Controleren of het draait:

curl http://localhost:3001/health
curl http://localhost:3001/mcp
# geeft {"protocolVersion":"2024-11-05"} terug — dat is de n8n-compatibele versie

Belangrijkste omgevingsvariabelen

Documentatietools werken ook zonder de n8n-API-variabelen; alleen workflowbeheer heeft ze nodig.

Sinds versie 2.9.2 gebruikt het project één geoptimaliseerde Dockerfile voor alle deploy-scenario's — de losse Dockerfile.n8n is vervallen, en n8n-integratie schakel je aan via de omgevingsvariabele N8N_MODE=true. Dat scheelde 500MB+ image-grootte en bracht de buildtijd terug van 8+ minuten naar 1-2 minuten.

Productiedeployment

Belangrijk: Docker cachet images lokaal. Draai vóór elke deploy altijd eerst docker pull ghcr.io/czlonkowski/n8n-mcp:latest, anders loop je het risico op een verouderde versie zonder dat je het merkt.

n8n-MCP op dezelfde server als n8n

docker pull ghcr.io/czlonkowski/n8n-mcp:latest

AUTH_TOKEN=$(openssl rand -hex 32)
echo "Bewaar dit AUTH_TOKEN: $AUTH_TOKEN"

docker network create n8n-net

docker run -d \
  --name n8n-mcp \
  --network n8n-net \
  -p 3000:3000 \
  -e N8N_MODE=true \
  -e MCP_MODE=http \
  -e N8N_API_URL=http://n8n:5678 \
  -e N8N_API_KEY=jouw-n8n-api-key \
  -e WEBHOOK_SECURITY_MODE=permissive \
  -e MCP_AUTH_TOKEN=$AUTH_TOKEN \
  -e AUTH_TOKEN=$AUTH_TOKEN \
  -e LOG_LEVEL=info \
  --restart unless-stopped \
  ghcr.io/czlonkowski/n8n-mcp:latest

Alternatief via systemd (native installatie zonder Docker): maak een unit-bestand aan onder /etc/systemd/system/n8n-mcp.service met de benodigde Environment=-regels en start de service met systemctl enable --now n8n-mcp.

n8n-MCP op een aparte server (cloud)

Zelfde Docker-aanpak, maar met N8N_API_URL wijzend naar de publieke URL van je n8n-instantie. Voor een volledige productie-setup met SSL raadt de bron een Docker Compose-stack met Caddy als reverse proxy aan: één service voor n8n-mcp, één voor Caddy, met een Caddyfile die het domein naar poort 3000 doorstuurt.

Praktische tips per cloudprovider: op AWS EC2 volstaat een t3.micro met poort 3000 (of 443) open in de security group; op DigitalOcean is een basic droplet van 6 dollar per maand voldoende; op Google Cloud werkt een e2-micro (binnen de gratis tier) met een load balancer voor SSL.

n8n koppelen aan n8n-MCP

1. Voeg in je n8n-workflow de node "MCP Client Tool" toe
2. Configureer de verbinding:
   • Server-URL (moet eindigen op /mcp): bijvoorbeeld http://localhost:3000/mcp (zelfde server), http://n8n-mcp:3000/mcp (Docker-netwerk), of https://mcp.jouwdomein.nl/mcp (aparte server)
   • Auth Token: de waarde van MCP_AUTH_TOKEN/AUTH_TOKEN
   • Transport: HTTP Streamable (SSE)
3. Test de verbinding met een eenvoudige tool zoals search_nodes

Let op: zonder het /mcp-pad in de Server-URL mislukt de verbinding.

Gebruik met AI Agent-nodes

Koppel de MCP Client Tool aan de tool-input van een AI Agent-node (bijvoorbeeld met OpenAI of Anthropic als model) en geef de agent een instructie zoals: zoek eerst met search_nodes naar de juiste node, haal de configuratiedetails op met get_node, valideer met validate_workflow, en maak de workflow pas aan als alle validaties slagen.

Beveiliging en best practices

• Gebruik altijd een sterk, willekeurig MCP_AUTH_TOKEN (32+ tekens) en bewaar tokens in omgevingsvariabelen of een secrets-vault
• Gebruik HTTPS in productie (Caddy, Nginx of Traefik)
• Open alleen de noodzakelijke poorten (3000 of 443) in de firewall
• Overweeg IP-whitelisting voor bekende n8n-instanties
• Pull altijd de laatste image vóór deploy, draai containers waar mogelijk met --read-only, en gebruik in productie een specifieke image-versie in plaats van :latest

Veelvoorkomende problemen

• Verouderde gecachete image: symptomen zijn ontbrekende features of teruggekeerde bugs. Oplossing: altijd docker pull vóór een nieuwe deploy.
• MCP_MODE=http ontbreekt: de n8n MCP Client Tool kan niet verbinden omdat de server dan in stdio-modus draait.
• Server-URL zonder /mcp: geeft "Connection refused" of "Invalid response".
• MCP_AUTH_TOKEN en AUTH_TOKEN komen niet overeen: geeft een authenticatiefout — beide variabelen moeten exact dezelfde waarde hebben.
• "Connection refused": controleer of de container draait (docker ps, docker logs), of de endpoints bereikbaar zijn (curl .../health en curl .../mcp), en of de firewall het verkeer toelaat.
• "Cannot connect to n8n API": controleer of N8N_API_URL een protocol bevat (http/https), of de n8n-API-key nog geldig is, en of de n8n-API in de instellingen aanstaat.

Voor dieper debuggen: zet DEBUG_MCP=true en LOG_LEVEL=debug, en doorloop systematisch de /health- en /mcp-endpoints met curl, inclusief een testcall met een Authorization: Bearer-header.

Performance

Een minimale deployment (1 vCPU, 1GB RAM) is voldoende. De vooraf gebouwde SQLite-database (~15MB) laadt snel, gemiddelde queries duren circa 12ms, en herhaalde queries profiteren van een ingebouwde cache van 15 minuten.

Praktijkvoorbeeld (NL)

Een Nederlandse groothandel in kantoorartikelen heeft een n8n-workflow die orders uit de webshop verwerkt en automatisch inkooporders bij leveranciers aanmaakt. Het interne IT-team wil dat de logistiek-medewerker via een chatvenster in n8n zelf kleine aanpassingen aan die workflow kan laten voorstellen door een AI Agent-node, zonder dat de medewerker de n8n-canvas-editor hoeft te begrijpen. Ze zetten daarom n8n-MCP op dezelfde server als n8n zelf, in hetzelfde Docker-netwerk, en koppelen de MCP Client Tool-node met de interne URL http://n8n-mcp:3000/mcp. Omdat n8n en n8n-mcp in hetzelfde geïsoleerde Docker-netwerk draaien en niet vanaf buiten bereikbaar zijn, kiest het team bewust voor WEBHOOK_SECURITY_MODE=permissive in plaats van de strengere standaardinstelling, en documenteren ze die afwijking in hun eigen infrastructuur-wiki zodat een collega niet per ongeluk dezelfde instelling op een wél publiek bereikbare server kopieert.