KiCAD MCP Server新手避坑完整清单：安装启动时必遇的8个问题与逐一解法-育师

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-Server

KiCAD MCP Server 是一个基于 Model Context Protocol（MCP）协议的服务器，它让 Claude 等大语言模型能够直接操作 KiCAD 进行 PCB 原理图与电路板设计。新手在安装与首次启动阶段最容易卡住：服务器闪退、30 秒无响应超时、找不到 KiCAD、构建失败等问题几乎人人会碰。这份新手避坑完整清单，把这 8 个安装启动时必遇的问题与逐一解法整理在一起，按顺序自查，通常 10 分钟内就能让你的 KiCAD MCP Server 跑起来。

安装前必读：3 个必备条件

在踩坑之前，先确认环境满足要求（详见 README.md 的 Prerequisites 章节）：

条件	要求	说明
KiCAD	9.0 或更高	必须包含 Python 模块（pcbnew），安装时勾选"Install Python"
Node.js	18 或更高	运行`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" }

坑 3：MCP 客户端 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。

坑 5：npm run build 构建失败

症状：npm install或npm run build报 TypeScript 编译错误，或者提示 node 版本过低。

解法：

确认 Node.js ≥ 18：node --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引导安装。

坑 7：Windows 配置里路径"看着对"却不生效

症状：配置文件的 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.md：

SWIG 模式下 KiCAD 界面不刷新：文件已被正确修改，只是运行中的 UI 没感知到。点界面上的 reload 提示，或 File > Revert 即可；
IPC 连不上：需要在 KiCAD 里开启 Preferences > Plugins > Enable IPC API Server，并在 PCB 编辑器中打开板卡，然后确认/tmp/kicad/api.sock存在。