KiCAD MCP Server新手避坑完整清单安装启动时必遇的8个问题与逐一解法【免费下载链接】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 等大语言模型能够直接操作 KiCAD 进行 PCB 原理图与电路板设计。新手在安装与首次启动阶段最容易卡住服务器闪退、30 秒无响应超时、找不到 KiCAD、构建失败等问题几乎人人会碰。这份新手避坑完整清单把这 8 个安装启动时必遇的问题与逐一解法整理在一起按顺序自查通常 10 分钟内就能让你的 KiCAD MCP Server 跑起来。安装前必读3 个必备条件在踩坑之前先确认环境满足要求详见 README.md 的 Prerequisites 章节条件要求说明KiCAD9.0 或更高必须包含 Python 模块pcbnew安装时勾选Install PythonNode.js18 或更高运行node --version验证Python随 KiCAD 捆绑服务器使用 KiCAD 自带 Python而非系统 Python标准安装流程Linux 为例只需四步克隆仓库、npm install、pip3 install -r requirements.txt、npm run build。Windows 用户推荐直接运行一键脚本 setup-windows.ps1它会自动检测 KiCAD、安装依赖、构建项目并生成配置git clone --branch stable https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-Server.git cd KiCAD-MCP-Server .\setup-windows.ps1 注意克隆stable分支——它只在正式发版时更新main分支可能包含尚未发布的修复。坑 1服务器闪退日志提示 Server transport closed unexpectedly这是最常见的启动问题。Claude Desktop 日志里只有一句 Server transport closed unexpectedly真正的原因藏在服务器自己的日志文件里。解法打开日志目录~/.kicad-mcp/logs/Windows 为%USERPROFILE%\.kicad-mcp\logs\每个进程有独立日志文件名形如kicad_interface-pid.log查看最新一个文件的最后 50~100 行。绝大多数情况是import pcbnew失败——KiCAD 安装时没勾 Python 模块。手动验证 C:\Program Files\KiCad\10.0\bin\python.exe -c import pcbnew; print(pcbnew.GetBuildVersion())能打印出版本号如10.0.0才算通过失败则重新安装 KiCAD 并勾选 Python 支持。详细排查步骤见 docs/WINDOWS_TROUBLESHOOTING.md 的 Issue 1。坑 2提示 No KiCAD installations found症状日志显示找不到 KiCAD 安装。服务器只扫描标准位置Windows 的C:\Program Files\KiCad、%LOCALAPPDATA%\Programs\KiCad等装到 D 盘自定义目录就会找不到。解法首选把 KiCAD 装到标准路径或者在 MCP 配置中手动指定KICAD_PYTHON指向捆绑 Python 的完整路径PYTHONPATH指向对应的dist-packages目录例如env: { KICAD_PYTHON: C:\\Users\\YourName\\AppData\\Local\\Programs\\KiCad\\10.0\\bin\\python.exe, PYTHONPATH: C:\\Users\\YourName\\AppData\\Local\\Programs\\KiCad\\10.0\\lib\\python3\\dist-packages }坑 3MCP 客户端 30 秒超时且没有任何报错症状Claude Desktop 转圈 30 秒后判定连接失败日志却一片空白。这是 macOS 用户最容易中招的坑。根本原因直接跑pip3 install -r requirements.txt会把 Pillow、cairosvg 等依赖装进系统 Python而服务器实际使用的是 KiCAD 捆绑的 Python——依赖装错了地方服务器根本看不见。解法二选一用 KiCAD 自带 Python 创建虚拟环境--system-site-packages参数不能省/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages source venv/bin/activate pip install -r requirements.txt或者用捆绑解释器直接装/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m pip install --user -r requirements.txt完整说明见 README.md 的 macOS 章节。坑 4提示 Python executable not found: python3症状Linux 上服务器启动即报找不到 Python 可执行文件。解法Linux 下服务器按虚拟环境 →KICAD_PYTHON环境变量 → KiCAD 捆绑 Python → 系统 Python的顺序自动探测绝大多数标准安装Ubuntu/Debian/Fedora/Arch无需任何配置。当你的 Python 装在不常见位置时先用which python3查出路径再写入配置env: { KICAD_PYTHON: /usr/bin/python3, PYTHONPATH: /usr/lib/kicad/lib/python3/dist-packages }同时用python3 -c import pcbnew; print(pcbnew.GetBuildVersion())确认这个解释器能访问 pcbnew——如果访问不了说明选错了 Python。坑 5npm run build 构建失败症状npm install或npm run build报 TypeScript 编译错误或者提示 node 版本过低。解法确认 Node.js ≥ 18node --version清理后重装依赖解决绝大多数依赖损坏问题rm -rf node_modules package-lock.json npm install npm run build仍然失败时尝试npm install --legacy-peer-deps再构建。构建成功的标志是dist/index.js存在——MCP 客户端配置里指向的正是这个文件。坑 6提示缺少 Pillow、cairosvg 等 Python 包症状日志报ModuleNotFoundError: No module named Pillow或 cairosvg、colorlog、pydantic 等。解法和坑 3 同源——用KiCAD 捆绑的 Python安装依赖而不是系统 pip# Windows C:\Program Files\KiCad\10.0\bin\python.exe -m pip install -r requirements.txt # Linux标准安装 sudo apt-get install -y kicad kicad-libraries pip3 install -r requirements.txt依赖清单见 requirements.txt包含 kicad-skip原理图支持、Pillow、cairosvg、colorlog、pydantic 等。如果捆绑 Python 连 pip 都没有先用get-pip.py引导安装。坑 7Windows 配置里路径看着对却不生效症状配置文件的 JSON 语法没问题但服务器就是起不来——多半是 Windows 路径的反斜杠写法错了。JSON 中单个\是转义符C:\Users\Name里的\U、\N会直接破坏字符串。正确写法两种都合法二选一保持一致即可// ✅ 双反斜杠 args: [C:\\Users\\Name\\KiCAD-MCP-Server\\dist\\index.js] // ✅ 正斜杠 args: [C:/Users/Name/KiCAD-MCP-Server/dist/index.js]参考 docs/WINDOWS_TROUBLESHOOTING.md 的 Issue 7以及仓库提供的配置模板 config/claude-desktop-config.json、config/vscode-mcp.example.json。坑 8服务器重启后所有工具调用都失败症状配置一切正常、第一次用得好好的重启电脑或重启 MCP 服务器后place_component、open_board等调用开始报错。根本原因KiCAD 项目/板卡的加载状态保存在服务器进程内存里服务器重启后引用丢失。解法每次服务器重新启动后先调用open_project打开项目再执行其他操作。这是使用习惯问题而非 Bug。顺带一提还有两个不算坑但常被当成坑的现象可参考 docs/KNOWN_ISSUES.mdSWIG 模式下 KiCAD 界面不刷新文件已被正确修改只是运行中的 UI 没感知到。点界面上的 reload 提示或 File Revert 即可IPC 连不上需要在 KiCAD 里开启 Preferences Plugins Enable IPC API Server并在 PCB 编辑器中打开板卡然后确认/tmp/kicad/api.sock存在。启动成功自检清单全部排查完后用这份清单确认 KiCAD MCP Server 已真正就绪import pcbnew能打印 KiCAD 版本号9.0npm run build无报错dist/index.js存在MCP 配置路径使用双反斜杠或正斜杠服务器启动后不闪退日志显示初始化成功Claude 端能看到kicad服务器并成功连接对 AI 说Create a new KiCAD project能正常执行把这份清单收藏起来之后环境变动升级 KiCAD、重装系统时照着重新自检一遍即可。祝你的第一块 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），仅供参考