n8n MCP Claude Code integration pitfalls

Problem 1: Docker Socket Mount Prevents n8n from Calling Claude Code CLI

Symptoms

Both my n8n and Claude Code run inside Docker containers. Following the official docs for MCP integration, the n8n workflow kept throwing Command not found: claude errors. Claude Code container logs looked fine — n8n just couldn't reach it.

Debugging Process

# Log into n8n container to test
docker exec -it n8n_container sh
which claude  # Result: not found
echo $PATH    # Result: /usr/local/sbin:/usr/local/bin:...

The problem isn't PATH. n8n runs inside the container, but Claude Code CLI is installed on the host machine. The n8n container has no access to the host's claude command.

The official docs say to install Claude Code CLI as a global npm package:

npm install -g @anthropic-ai/claude-code

But after installing inside the container, Claude Code needs login authentication — and the container can't open a browser for the OAuth flow.

Solution

The correct approach is to mount the host's Claude Code CLI binary into the n8n container, and also mount the Docker socket so n8n can access the host's Docker daemon:

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n:latest
    volumes:
      - /usr/local/lib/node_modules/@anthropic-ai/claude-code:/usr/local/bin/claude
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - N8N_MCP_API_KEY=${ANTHROPIC_API_KEY}

The key is mounting the compiled CLI binary path, not the source code path. Verify:

docker exec -it n8n_container claude --version
# Should output: claude 1.x.x

---

Problem 2: N8N_MCP_API_KEY Environment Variable Not Reaching Claude Code

Symptoms

After configuration, n8n logs showed successful connection to the MCP server, but Claude Code execution returned: Error: Anthropic API key not found.

Debugging Process

I set N8N_MCP_API_KEY in docker-compose.yml, but Claude Code reads from its own config file ~/.claude/config.json — not the environment variables inside the n8n container.

When n8n's MCP Client node calls Claude Code, it actually executes the claude command on the **host machine**, not inside the n8n container. So the environment variable needs to be set at the **host level**, or manually passed in the n8n MCP Client configuration.

Solution

Option A: Set API key in host config file

# On the host machine
export ANTHROPIC_API_KEY=sk-ant-xxxxx
# Then restart n8n container (inherits host environment variables)
docker-compose down && docker-compose up -d

Option B: Manually pass in n8n MCP Client node

In the n8n MCP Client Tool node configuration, manually specify the API key:

{
  "anthropic_api_key": "{{ $env.ANTHROPIC_API_KEY }}"
}

Test that the connection works:

# On host, test if Claude Code is working
claude --print "API key loaded: $(echo $ANTHROPIC_API_KEY | head -c 8)..."

---

Problem 3: Webhook URL Mismatch Under Nginx Reverse Proxy

Symptoms

After enabling n8n's MCP server, calls from Claude Code resulted in n8n error: Webhook URL does not match configured base URL.

Root Cause Analysis

My n8n is exposed via Nginx reverse proxy with this config:

# /etc/nginx/sites-available/n8n
server {
    listen 80;
    server_name n8n.example.com;

    location / {
        proxy_pass http://localhost:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

n8n's default N8N_WEBHOOK_URL is http://localhost:5678, but external requests via Nginx are forwarded as https://n8n.example.com/webhook/.... This causes n8n to reject the request as the source URL doesn't match its configured base URL.

Solution

Explicitly set N8N_WEBHOOK_URL to your public domain in docker-compose.yml:

environment:
  - N8N_WEBHOOK_URL=https://n8n.example.com/
  - N8N_PROTOCOL=https
  - WEBHOOK_URL=https://n8n.example.com/

Then add the correct protocol headers in Nginx config:

location / {
    proxy_pass http://localhost:5678;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;  # Critical: pass real protocol
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Reload Nginx and test:

curl -X POST https://n8n.example.com/webhook/test -H "Content-Type: application/json" -d '{}'
# Should return 200, not 403/400

---

Complete Docker Compose Configuration

Here's the verified complete configuration that addresses all three problems:

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    volumes:
      # Mount Claude Code CLI into container
      - /usr/local/lib/node_modules/@anthropic-ai/claude-code:/usr/local/bin/claude:ro
      # Docker socket for calling host Docker
      - /var/run/docker.sock:/var/run/docker.sock
      # Persist n8n data
      - ./n8n_data:/home/node/.n8n
    environment:
      - N8N_WEBHOOK_URL=https://n8n.example.com/
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.example.com/
      - N8N_MCP_API_KEY=${ANTHROPIC_API_KEY}
      - EXECUTIONS_TIMEOUT=300
      - EXECUTIONS_TIMEOUT_MAX=600
    restart: unless-stopped

---

Verify MCP Connection Is Working

After configuration, create a test workflow in n8n:

1. Add an "MCP Client Tool" node

2. Select the claude-code tool

3. Input test prompt: List the files in your current directory

4. Run the workflow

If it returns a file list instead of an error, the MCP integration is successful.

---

Prevention: Ongoing Maintenance Checklist

To avoid these problems recurring after the integration is complete, do regular checks:

• **Monthly**: Check if Claude Code CLI version is updated (`claude --version` vs GitHub releases)
• **After every n8n update**: Verify MCP connection by running the verification test above
• **After Nginx config changes**: Confirm `X-Forwarded-Proto` header is correctly passed
• **When rotating API keys**: Update both host environment variables and n8n container configuration

---

Summary

Root causes of the three problems:

Problem	Root Cause	Key Fix
Claude CLI not found	Container/host isolation	Mount CLI binary
API key read failure	n8n container can't read host env vars	Choose Option A or B
Webhook URL mismatch	Reverse proxy loses protocol header	Set N8N_WEBHOOK_URL + X-Forwarded-Proto

n8n + Claude Code + MCP integration itself isn't complex, but Docker environment path isolation, network proxying, and file mounting require extra attention. The above configuration has been verified on Ubuntu 22.04 + Nginx + Docker 29.x.

---

👉 Start now: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews