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_URLDocker 容器里的localhost指向容器自身而不是宿主机这是 502 最常见的原因。文档给了一张按场景选择 URL 的对照表场景使用的 URL原因n8n 在宿主机、n8n-mcp 在 Dockerhttp://host.docker.internal:5678Docker 容器无法直接访问宿主机 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_URLhttp://host.docker.internal:5678, -e, N8N_API_KEYyour-api-key, ghcr.io/czlonkowski/n8n-mcp:latest ] } } }如果host.docker.internal不可解析文档给出可依次尝试的替代地址host.docker.internalmacOS/Windows 上的 Docker Desktop172.17.0.1Linux 上默认的 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 curldocker 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 ancestorghcr.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 DesktopmacOS/Windowshost.docker.internal开箱即用确认 Docker Desktop 正在运行即可。Linuxhost.docker.internal需要 Docker 20.10旧版本可改用--add-hosthost.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），仅供参考