n8n-mcp/docs/DOCKER_TROUBLESHOOTING.md

Docker Troubleshooting Guide

This guide helps resolve common issues when running n8n-mcp with Docker, especially when connecting to n8n instances.

Table of Contents

• Common Issues
  • 502 Bad Gateway Errors
  • Custom Database Path Not Working
  • Container Name Conflicts
  • n8n API Connection Issues
• Docker Networking
• Quick Solutions
• Debugging Steps

Common Issues

Docker Configuration File Not Working (v2.8.2+)

Symptoms:

• Config file mounted but environment variables not set
• Container starts but ignores configuration
• Getting "permission denied" errors

Solutions:

1. Ensure file is mounted correctly:

# Correct - mount as read-only
docker run -v $(pwd)/config.json:/app/config.json:ro ...

# Check if file is accessible
docker exec n8n-mcp cat /app/config.json

2. Verify JSON syntax:

# Validate JSON file
cat config.json | jq .

3. Check Docker logs for parsing errors:

docker logs n8n-mcp | grep -i config

4. Common issues:

• Invalid JSON syntax (use a JSON validator)
• File permissions (should be readable)
• Wrong mount path (must be /app/config.json)
• Dangerous variables blocked (PATH, LD_PRELOAD, etc.)

Custom Database Path Not Working (v2.7.16+)

Symptoms:

• NODE_DB_PATH environment variable is set but ignored
• Database always created at /app/data/nodes.db
• Custom path setting has no effect

Root Cause: Fixed in v2.7.16. Earlier versions had hardcoded paths in docker-entrypoint.sh.

Solutions:

1. Update to v2.7.16 or later:

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

2. Ensure path ends with .db:

# Correct
NODE_DB_PATH=/app/data/custom/my-nodes.db

# Incorrect (will be rejected)
NODE_DB_PATH=/app/data/custom/my-nodes

3. Use path within mounted volume for persistence:

services:
  n8n-mcp:
    environment:
      NODE_DB_PATH: /app/data/custom/nodes.db
    volumes:
      - n8n-mcp-data:/app/data  # Ensure parent directory is mounted

502 Bad Gateway Errors

Symptoms:

• n8n_health_check returns 502 error
• All n8n management API calls fail
• n8n web UI is accessible but API is not

Root Cause: Network connectivity issues between n8n-mcp container and n8n instance.

Solutions:

1. When n8n runs in Docker on same machine

Use Docker's special hostnames instead of localhost:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Alternative hostnames to try:

• host.docker.internal (Docker Desktop on macOS/Windows)
• 172.17.0.1 (Default Docker bridge IP on Linux)
• Your machine's actual IP address (e.g., 192.168.1.100)

2. When both containers are in same Docker network

# Create a shared network
docker network create n8n-network

# Run n8n in the network
docker run -d --name n8n --network n8n-network -p 5678:5678 n8nio/n8n

# Configure n8n-mcp to use container name

{
  "N8N_API_URL": "http://n8n:5678"
}

3. For Docker Compose setups

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    networks:
      - n8n-net
    ports:
      - "5678:5678"
  
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    environment:
      N8N_API_URL: http://n8n:5678
      N8N_API_KEY: ${N8N_API_KEY}
    networks:
      - n8n-net

networks:
  n8n-net:
    driver: bridge

Container Cleanup Issues (Fixed in v2.7.20+)

Symptoms:

• Containers accumulate after Claude Desktop restarts
• Containers show as "unhealthy" but don't clean up
• --rm flag doesn't work as expected

Root Cause: Fixed in v2.7.20 - containers weren't handling termination signals properly.

Solutions:

1. Update to v2.7.20+ and use --init flag (Recommended):

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm", "--init",
    "ghcr.io/czlonkowski/n8n-mcp:latest"
  ]
}

2. Manual cleanup of old containers:

# Remove all stopped n8n-mcp containers
docker ps -a | grep n8n-mcp | grep Exited | awk '{print $1}' | xargs -r docker rm

3. For versions before 2.7.20:

• Manually clean up containers periodically
• Consider using HTTP mode instead

n8n API Connection Issues

Symptoms:

• API calls fail but n8n web UI works
• Authentication errors
• API endpoints return 404

Solutions:

1. Verify n8n API is enabled:

   • Check n8n settings → REST API is enabled
   • Ensure API key is valid and not expired

2. Test API directly:

# From host machine
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows

# From inside Docker container
docker run --rm curlimages/curl \
  -H "X-N8N-API-KEY: your-key" \
  http://host.docker.internal:5678/api/v1/workflows

3. Check n8n environment variables:

environment:
  - N8N_BASIC_AUTH_ACTIVE=true
  - N8N_BASIC_AUTH_USER=user
  - N8N_BASIC_AUTH_PASSWORD=password

Docker Networking

Understanding Docker Network Modes

Scenario	Use This URL	Why
n8n on host, n8n-mcp in Docker	http://host.docker.internal:5678	Docker can't reach host's localhost
Both in same Docker network	http://container-name:5678	Direct container-to-container
n8n behind reverse proxy	http://your-domain.com	Use public URL
Local development	http://YOUR_LOCAL_IP:5678	Use machine's IP address

Finding Your Configuration

# Check if n8n is running in Docker
docker ps | grep n8n

# Find Docker network
docker network ls

# Get container details
docker inspect n8n | grep NetworkMode

# Find your local IP
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Windows
ipconfig | findstr IPv4

Quick Solutions

Solution 1: Use Host Network (Linux only)

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "--network", "host",
    "-e", "N8N_API_URL=http://localhost:5678",
    "ghcr.io/czlonkowski/n8n-mcp:latest"
  ]
}

Solution 2: Use Your Machine's IP

{
  "N8N_API_URL": "http://192.168.1.100:5678"  // Replace with your IP
}

Solution 3: HTTP Mode Deployment

Deploy n8n-mcp as HTTP server to avoid stdio/Docker issues:

# Start HTTP server
docker run -d \
  -p 3000:3000 \
  -e MCP_MODE=http \
  -e AUTH_TOKEN=your-token \
  -e N8N_API_URL=http://host.docker.internal:5678 \
  -e N8N_API_KEY=your-n8n-key \
  ghcr.io/czlonkowski/n8n-mcp:latest

# Configure Claude with mcp-remote

Debugging Steps

1. Enable Debug Logging

{
  "env": {
    "LOG_LEVEL": "debug",
    "DEBUG_MCP": "true"
  }
}

2. Test Connectivity

# Test from n8n-mcp container
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
  sh -c "apk add curl && curl -v http://host.docker.internal:5678/api/v1/workflows"

3. Check Docker Logs

# View n8n-mcp logs
docker logs $(docker ps -q -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)

# View n8n logs
docker logs n8n

4. Validate Environment

# Check what n8n-mcp sees
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \
  sh -c "env | grep N8N"

5. Network Diagnostics

# Check Docker networks
docker network inspect bridge

# Test DNS resolution
docker run --rm busybox nslookup host.docker.internal

Platform-Specific Notes

Docker Desktop (macOS/Windows)

• host.docker.internal works out of the box
• Ensure Docker Desktop is running
• Check Docker Desktop settings → Resources → Network

Linux

• host.docker.internal requires Docker 20.10+
• Alternative: Use --add-host=host.docker.internal:host-gateway
• Or use the Docker bridge IP: 172.17.0.1

Windows with WSL2

• Use host.docker.internal or WSL2 IP
• Check firewall rules for port 5678
• Ensure n8n binds to 0.0.0.0 not 127.0.0.1

Still Having Issues?

1. Check n8n logs for API-related errors
2. Verify firewall/security isn't blocking connections
3. Try simpler setup - Run n8n-mcp on host instead of Docker
4. Report issue with debug logs at GitHub Issues

Useful Commands

# Remove all n8n-mcp containers
docker rm -f $(docker ps -aq -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest)

# Test n8n API with curl
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows

# Run interactive debug session
docker run -it --rm \
  -e LOG_LEVEL=debug \
  -e N8N_API_URL=http://host.docker.internal:5678 \
  -e N8N_API_KEY=your-key \
  ghcr.io/czlonkowski/n8n-mcp:latest \
  sh

# Check container networking
docker run --rm alpine ping -c 4 host.docker.internal