n8n-mcp 的 n8n_health_check 返回 502 错误怎么排查？
【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp
当 n8n-mcp 通过 Docker 容器部署、并且N8N_API_URL指向宿主机上的 n8n 时，n8n_health_check经常返回 502，同时所有 n8n 管理 API 调用全部失败，但 n8n 的 Web UI 却能正常访问。Docker Troubleshooting Guide 将这一现象的根因明确归结为一件事：n8n-mcp 容器与 n8n 实例之间的网络不通。换句话说，问题通常不在 API Key，而在容器访问宿主机时用了错误的地址（localhost）。本文按"选对地址 → 核对实际部署 → 验证连通 → 看日志"的顺序给出文档中的排查路径。
症状与根因
文档列出的典型症状是：
n8n_health_check返回 502 错误；- 所有 n8n 管理 API 调用失败；
- n8n Web UI 可访问，但 API 不可达。
根因是 n8n-mcp 容器到 n8n 实例之间的网络连通性问题。注意一个关键前提：n8n_health_check依赖N8N_API_URL和N8N_API_KEY两个环境变量已正确配置（见 工具文档），如果 API Key 缺失会表现为认证失败而不是 502，可以先确认这一点再往下排查网络。
第一步：按部署拓扑选对 N8N_API_URL
Docker 容器里的localhost指向容器自身，而不是宿主机，这是 502 最常见的原因。文档给了一张按场景选择 URL 的对照表：
| 场景 | 使用的 URL | 原因 |
|---|---|---|
| n8n 在宿主机、n8n-mcp 在 Docker | http://host.docker.internal:5678 | Docker 容器无法直接访问宿主机 localhost |
| 两者在同一 Docker 网络 | http://container-name:5678 | 容器间直连 |
| n8n 在反向代理之后 | http://your-domain.com | 使用公网 URL |
| 本地开发 | http://YOUR_LOCAL_IP:5678 | 使用本机 IP 地址 |
n8n 在 Docker、且与 n8n-mcp 同机
把localhost换成 Docker 的特殊主机名，在 MCP 客户端配置中（以下 JSON 中的your-api-key需替换为你自己的 n8n API Key）：
{ "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" ] } } }如果host.docker.internal不可解析，文档给出可依次尝试的替代地址：
host.docker.internal（macOS/Windows 上的 Docker Desktop）；172.17.0.1（Linux 上默认的 Docker bridge IP）；- 本机的真实 IP（例如
192.168.1.100）。
两个容器在同一 Docker 网络
创建共享网络并把 n8n 接入，然后让N8N_API_URL指向容器名：
# 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{ "N8N_API_URL": "http://n8n:5678" }Docker Compose 部署
把两个服务放进同一个网络n8n-net（${N8N_API_KEY}由 Compose 的环境变量提供）：
# 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第二步：核对你的实际部署
不确定自己属于哪种场景时，先用文档中的命令确认 n8n 的实际运行方式和网络归属：
# 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如果 n8n 根本没出现在docker ps里，说明它跑在宿主机进程上，回到"同机"场景使用host.docker.internal或本机 IP。
第三步：验证容器到 n8n API 的连通性
改完N8N_API_URL后，不要只重跑 health check，文档建议先直接从容器视角测 API 是否可达。以下命令中的your-key需替换为你的 n8n API Key：
# 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主机上能通、容器里不通，就是N8N_API_URL的地址选择问题；容器里也不通，再往下查 DNS 与网络：
# Check what n8n-mcp sees docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \ sh -c "env | grep N8N" # Test DNS resolution docker run --rm busybox nslookup host.docker.internal # Check Docker networks docker network inspect bridge也可以复用 n8n-mcp 镜像本身做连通性测试（命令会先在容器内apk add curl）：
docker run --rm ghcr.io/czlonkowski/n8n-mcp:latest \ sh -c "apk add curl && curl -v http://host.docker.internal:5678/api/v1/workflows"第四步：打开调试日志与诊断模式
仍无法定位时，文档给出两层调试手段。一是在 MCP 客户端配置中开启 debug 日志：
{ "env": { "LOG_LEVEL": "debug", "DEBUG_MCP": "true" } }二是把n8n_health_check切到诊断模式，该模式会返回更多调试信息（含环境变量与工具状态），verbose可进一步输出细节：
n8n_health_check({ "mode": "diagnostic", "verbose": true })同时查看两侧容器日志：
# View n8n-mcp logs docker logs $(docker ps -q -f ancestor=ghcr.io/czlonkowski/n8n-mcp:latest) # View n8n logs docker logs n8n修复成功后，再次运行n8n_health_check（默认mode: "status"），返回对象中的status字段为healthy即表示 API 端点、认证与版本信息均已通过检查；该工具还会返回n8nVersion、versionCheck和performance（响应时间、缓存命中率）等信息，可用于确认实例完全恢复。
平台相关的边界条件
不同操作系统下host.docker.internal的可用性不同，文档的 Platform-Specific Notes 明确列出：
- Docker Desktop（macOS/Windows）：
host.docker.internal开箱即用，确认 Docker Desktop 正在运行即可。 - Linux：
host.docker.internal需要 Docker 20.10+；旧版本可改用--add-host=host.docker.internal:host-gateway参数，或直接使用 Docker bridge IP172.17.0.1。 - Windows + WSL2：使用
host.docker.internal或 WSL2 IP，检查防火墙对 5678 端口的放行，并确保 n8n 绑定在0.0.0.0而不是127.0.0.1。
仍不通过时的文档建议
文档 "Still Having Issues?" 一节给出的后续动作依次是：检查 n8n 日志中的 API 相关错误；确认防火墙/安全策略没有拦截连接；尝试更简单的部署方式——把 n8n-mcp 直接跑在宿主机上而不是 Docker 中。如果确认是 n8n-mcp 侧问题而非网络问题，应带上 debug 日志反馈给项目方。
需要区分的是：本文排查的是 n8n-mcp 容器到 n8n API 的 502 连通性问题；文档中另一类 localhost 报错——n8n_trigger_webhook_workflow的 "SSRF protection: Localhost access is blocked"——属于 Webhook 的 SSRF 防护策略，通过WEBHOOK_SECURITY_MODE解决，与本节的 502 不是同一问题。
【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
