n8n MCP Claude Code集成踩坑

问题一：Docker Socket挂载导致n8n无法调用Claude Code CLI

问题现象

我的n8n和Claude Code都运行在Docker容器里，按照官方文档配置了MCP集成后，n8n工作流运行时一直报Command not found: claude错误。检查Claude Code容器日志一切正常，但n8n就是连不上。

排查过程

# 登录到n8n容器内部测试
docker exec -it n8n_container sh
which claude  # 结果：not found
echo $PATH    # 结果：/usr/local/sbin:/usr/local/bin:...

问题不在PATH。n8n运行在容器里，而Claude Code CLI安装在宿主机上。n8n容器根本访问不到宿主机上的claude命令。

n8n官方文档说需要将Claude Code CLI安装为全局npm包：

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

但我在容器内安装后，Claude Code需要登录认证，而容器内无法打开浏览器完成OAuth流程。

解决方案

正确的做法是将宿主机的Claude Code CLI通过卷挂载进n8n容器，同时挂载Docker socket让n8n能访问宿主机Docker：

# 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}

关键是挂载编译后的CLI文件路径而非源代码路径。验证：

docker exec -it n8n_container claude --version
# 应显示：claude 1.x.x

---

问题二：N8N_MCP_API_KEY环境变量传递失败

问题现象

配置完成后n8n日志显示成功连接到MCP服务器，但Claude Code执行时返回：Error: Anthropic API key not found。

排查过程

我在docker-compose.yml里设置了N8N_MCP_API_KEY环境变量，但Claude Code运行时读取的是它自己的配置文件~/.claude/config.json，不是n8n容器内的环境变量。

n8n的MCP Client节点在调用Claude Code时，实际是在宿主机上执行claude命令，而不是在n8n容器内。所以环境变量需要设在**宿主机层面**，或者在n8n的MCP Client配置中手动传入。

解决方案

方案A：在宿主机配置文件设置API密钥

# 在宿主机上
export ANTHROPIC_API_KEY=sk-ant-xxxxx
# 然后重启n8n容器（继承宿主机的环境变量）
docker-compose down && docker-compose up -d

方案B：在n8n MCP Client节点中手动传入

在n8n的MCP Client Tool节点中配置时，手动指定API密钥：

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

验证连接是否成功：

# 在宿主机测试Claude Code是否正常
claude --print "API key loaded: $(echo $ANTHROPIC_API_KEY | head -c 8)..."

---

问题三：Webhook URL在Nginx反向代理下匹配失败

问题现象

n8n MCP服务器启用后，从Claude Code发起调用时n8n报错：Webhook URL does not match configured base URL。

问题分析

我的n8n通过Nginx反向代理暴露，配置大致如下：

# /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的N8N_WEBHOOK_URL默认是http://localhost:5678，但外部访问时Nginx将其转发为https://n8n.example.com/webhook/...，导致n8n认为请求来源与配置的base URL不匹配。

解决方案

在docker-compose.yml中明确设置N8N_WEBHOOK_URL为你的公开域名：

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

然后在Nginx配置中添加正确的协议头：

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;  # 关键：传递真实协议
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

重载Nginx配置后测试：

curl -X POST https://n8n.example.com/webhook/test -H "Content-Type: application/json" -d '{}'
# 应返回200而非403/400

---

完整Docker Compose配置

以下是经过验证的完整配置，解决了上述三个问题：

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    volumes:
      # 挂载Claude Code CLI到容器内
      - /usr/local/lib/node_modules/@anthropic-ai/claude-code:/usr/local/bin/claude:ro
      # Docker socket用于调用宿主机Docker
      - /var/run/docker.sock:/var/run/docker.sock
      # 持久化n8n数据
      - ./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

---

验证MCP连接是否正常

配置完成后，在n8n中创建一个测试工作流：

1. 添加「MCP Client Tool」节点

2. 选择claude-code工具

3. 输入测试prompt：List the files in your current directory

4. 运行工作流

如果返回文件列表而非错误，说明MCP集成成功。

---

防止方法：日常维护检查清单

集成完成后，为了避免问题复现，建议定期检查：

• **每月检查一次**：Claude Code CLI版本是否更新（`claude --version`对比GitHub releases）
• **每次n8n更新后**：验证MCP连接是否正常（跑一遍上面的验证测试）
• **Nginx配置变更后**：检查`X-Forwarded-Proto`头是否正确传递
• **API密钥轮换时**：同时更新宿主机环境变量和n8n容器配置

---

总结

三个问题的根本原因：

问题	根因	解决关键
Claude CLI找不到	容器与宿主机隔离	挂载CLI二进制文件
API密钥读取失败	n8n容器读不到宿主机环境变量	方案A或B二选一
Webhook URL不匹配	反向代理协议头丢失	设置N8N_WEBHOOK_URL + X-Forwarded-Proto

n8n + Claude Code + MCP的集成本身不复杂，但Docker环境下的路径隔离、网络代理、文件挂载需要额外注意。上述配置已经在Ubuntu 22.04 + Nginx + Docker 29.x环境下验证通过。

---

👉 立即参与：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