KiCAD MCP Server启动失败这份完整排错清单帮你30分钟定位日志与根因【免费下载链接】KiCAD-MCP-ServerKiCAD MCP is a Model Context Protocol (MCP) implementation that enables Large Language Models (LLMs) like Claude to directly interact with KiCAD for printed circuit board design.项目地址: https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-ServerKiCAD MCP Server 是一个 Model Context ProtocolMCP服务器它让 Claude 等 AI 助手直接驱动 KiCAD 完成原理图绘制、PCB 布局布线等设计工作。当它启动失败时最常见的表现是客户端提示Server transport closed unexpectedly、30 秒超时没有任何报错、或者日志里出现No KiCAD installations found。这篇文章给出一份完整的排错清单先教你 3 步找到日志文件再按命中率从高到低过一遍 5 类根因最后附手动启动验证方法——照着做绝大多数启动问题都能在 30 分钟内定位。一、先看症状你的启动失败是哪一种不同症状对应不同的排查起点先对号入座症状典型平台最可能的原因客户端提示 Server transport closed unexpectedlyWindowsPython 子进程启动即崩溃通常是pcbnew导入失败客户端 30 秒超时界面无任何报错macOS依赖装进了系统 Python而不是 KiCAD 自带的 Python日志显示 No KiCAD installations found全平台KiCAD 装在非默认路径自动发现找不到终端里进程秒退报 Node/构建错误全平台Node.js 未装或dist/index.js未构建 关键认知KiCAD MCP Server 实际是Node.js 主进程 Python 子进程的两层结构入口见 src/index.ts 与 python/kicad_interface.py。Python 端一旦崩溃Node 端往往只留下一句笼统的transport closed真正的错误信息几乎都藏在 Python 端日志里——所以下一节找对日志是排错的关键。二、3 步定位日志文件排错第一步所有日志统一写入用户主目录下的~/.kicad-mcp/logs/按进程隔离v2.7.0 起每个服务进程独立一个文件避免并发写冲突Python 端日志最重要~/.kicad-mcp/logs/kicad_interface-pid.logpid是进程号可能有多个打开修改时间最新的那个Windows 路径为%USERPROFILE%\.kicad-mcp\logs\kicad_interface-pid.log实现细节见 python/kicad_interface.pyNode 端日志~/.kicad-mcp/logs/kicad-mcp-日期.log按天命名带 10MB×3 轮转逻辑见 src/logger.ts看最后 50~100 行启动崩溃的原因一定在日志尾部头部的 Python 版本、平台信息只用于交叉确认环境常用查看命令任选其一# Linux / macOS看最新 Python 端日志的尾部 tail -n 50 $(ls -t ~/.kicad-mcp/logs/kicad_interface-*.log | head -1)# Windows PowerShell看最新日志尾部 50 行 Get-Content (Get-ChildItem $env:USERPROFILE\.kicad-mcp\logs\kicad_interface-*.log | Sort-Object LastWriteTime -Descending)[0] -Tail 50 小技巧如果日志目录不存在或文件为空说明 Python 子进程根本没跑起来直接跳到第五节Node/构建问题排查。三、打开调试开关让日志说出更多默认日志级别是info。复现问题时在 MCP 配置例如 Claude Desktop 的mcpServers.kicad.env段参考 config/claude-desktop-config.json中加入以下环境变量LOG_LEVELdebugNode 端输出 debug 级日志PYTHONUNBUFFERED1Python 端实时刷出日志避免崩溃前内容憋在缓冲区丢失KICAD_MCP_DEV1开发者模式额外捕获会话日志便于报 bug 时附带完整现场说明见 docs/KNOWN_ISSUES.md改完配置后重启客户端再触发一次启动然后回到第二节的日志路径看最新文件。四、排错清单5 类最常见启动失败根因4.1 Python 导入不了 pcbnew命中率最高这是transport closed unexpectedly的头号元凶MCP Server必须使用 KiCAD 自带的 Python它内置了pcbnew模块系统里随便装的 Python 是不行的。验证一条命令# LinuxKiCAD 安装后 python3 -c import pcbnew; print(pcbnew.GetBuildVersion()) # Windows直接调用 KiCAD 自带的 python.exe C:\Program Files\KiCad\10.0\bin\python.exe -c import pcbnew; print(pcbnew.GetBuildVersion())期望输出类似10.0.0的版本号。若报ModuleNotFoundError: No module named pcbnew按平台处理Windows确认配置中的PYTHONPATH指向 KiCAD 的dist-packages目录且command指向 KiCAD 的python.exe示例见 config/windows-config.example.jsonmacOS典型坑是pip3 install -r requirements.txt装进了系统 Python而服务从未用它于是启动 30 秒超时无报错。要么用 KiCAD 自带 Python 建虚拟环境需--system-site-packages要么直接用它的解释器执行pip install --user完整步骤见 README 的 Installation 章节依赖清单见 requirements.txt务必用同一个 Python安装4.2 日志报 No KiCAD installations found服务器启动时会自动扫描常见安装位置Windows 的C:\Program Files\KiCad、%LOCALAPPDATA%\Programs\KiCadLinux/macOS 的标准位置发现逻辑集中在 python/utils/kicad_roots.py。如果你把 KiCAD 装到了自定义目录就在配置env中手动指定KICAD_PYTHONKiCAD 自带python.exe或python3的完整路径PYTHONPATH对应的dist-packagesWindows或site-packages路径各平台示例配置都在 config/ 目录下如 config/linux-config.example.json、config/macos-config.example.json照着改路径即可。4.3 Node.js 缺失或项目未构建启动命令本质是node dist/index.js。满足三点即可Node.js 版本 ≥ 18node --version确认项目目录下执行过npm install且npm run build成功dist/index.js文件确实存在如果npm run build报 TypeScript 错误通常是依赖装了一半删掉node_modules与锁文件重装再构建仍失败可尝试npm install --legacy-peer-deps。Windows 上还有自动化方案setup-windows.ps1 会一次完成检测、安装、构建、生成配置和诊断。4.4 Python 依赖缺失日志出现ModuleNotFoundError且包名是 Pillow、cairosvg 等第三方库时说明requirements.txt没装或装错了 Python回到 4.1 的原则用 KiCAD 自带 Python 执行 pip。Windows 上该节完整解法见 docs/WINDOWS_TROUBLESHOOTING.md。4.5 配置文件路径写错JSON 配置里路径报错是新手高频坑两个铁律❌ 单反斜杠C:\Users\Name\...\dist\index.js\U、\d会被当成转义符✅ 双反斜杠C:\\Users\\Name\\KiCAD-MCP-Server\\dist\\index.js或全部用正斜杠C:/Users/Name/...完整错误与正确对照示例见 docs/WINDOWS_TROUBLESHOOTING.md 的 Path Issues in Configuration 一节。五、手动启动验证1 分钟复现问题把客户端晾在一边直接在终端手动启动服务器能瞬间区分是服务器自身的问题还是客户端配置的问题# 在项目根目录设置好 PYTHONPATH 后 node dist/index.js判定标准进程启动后安静地等待输入、不立即退出 服务器正常此时问题在客户端配置秒退并打印报错 把报错与第二节日志尾部拼在一起根因基本水落石出。按CtrlC退出。另有两条轻量诊断命令值得随手跑# 一键打印 KiCAD 相关路径解析结果平台路径诊断 python3 python/utils/platform_helper.py # 确认 pcbnew 可用及版本要求 KiCAD 9.0 及以上 python3 -c import pcbnew; print(pcbnew.GetBuildVersion())六、卡住了按这份清单提交反馈若以上都没解决项目维护者最需要的是以下四样东西清单见 docs/KNOWN_ISSUES.md Reporting New Issues 一节错误信息原文 日志尾部摘录复现步骤KiCAD 版本号 操作系统开启KICAD_MCP_DEV1后收集的会话日志另外两个与启动相关的常见疑问顺带说明服务器重启后所有命令失败重启会丢失已打开的 board 引用先执行open_project再操作即可这属于设计行为IPC 连不上服务器会自动回退到 SWIG 后端不会导致启动失败只有想要实时 UI 刷新时才需要去 KiCAD 里启用 IPC API Server七、30 分钟排错清单可截图保存步骤动作通过标准1打开最新日志~/.kicad-mcp/logs/kicad_interface-*.log尾部能看到明确报错2import pcbnew验证命令打印出 KiCAD 版本号3确认 Python 依赖装在 KiCAD 自带 Python 下无 ModuleNotFoundError4确认dist/index.js存在、Node ≥ 18node dist/index.js不秒退5检查配置路径双反斜杠 / 正斜杠与 docs/WINDOWS_TROUBLESHOOTING.md 对照无误6打不开跑平台诊断python3 python/utils/platform_helper.py或 setup-windows.ps1 / setup-macos.sh输出无 ERROR7手动启动node dist/index.js复现进程稳定驻留等待输入✅ 按顺序走完这张表启动失败几乎总会暴露在第 1~3 步KiCAD MCP Server 的日志是精确到进程、带时间戳和级别的结构化输出读懂它尾部 50 行根因就藏不住了。祝排错顺利早日让 AI 帮你画板子【免费下载链接】KiCAD-MCP-ServerKiCAD MCP is a Model Context Protocol (MCP) implementation that enables Large Language Models (LLMs) like Claude to directly interact with KiCAD for printed circuit board design.项目地址: https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-Server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考