🔌 KiCad + KiCad-MCP-Server 安装与联动教程

一句话讲清两者关系：KiCad 是画 PCB 的软件本体，KiCad-MCP-Server 是一座桥——它通过 MCP（Model Context Protocol）协议，让 AI 助手（Claude / WorkBuddy / Cline 等）用自然语言直接读写 KiCad 的原理图和 PCB 文件，并可与正在运行的 KiCad 界面实时联动。

一、架构总览：它们是怎么"联动"起来的

flowchart TD
    AI["🤖 AI 助手
WorkBuddy / Claude / Cline"]
    MCP["KiCad-MCP-Server（Node.js）
dist/index.js
· 实现 MCP 协议 / 参数校验 / 工具路由
· 管理 Python 子进程生命周期"]
    PY["Python 接口层 kicad_interface.py
· 路由到 SWIG 或 IPC 后端"]
    SWIG["后端 A · SWIG
pcbnew 模块，直接读写文件"]
    IPC["后端 B · IPC
kicad-python（kipy）
Protobuf over socket"]
    FILES["📄 .kicad_sch / .kicad_pcb
文件级联动（无需开 KiCad）"]
    GUI["🖥️ 运行中的 KiCad 9.0+ 进程
实时联动（需开启 IPC API Server）"]
    HUMAN["👤 人类设计师
在 KiCad UI 中查看 / 编辑 / 保存"]

    AI -->|MCP 协议 JSON-RPC over stdio| MCP
    MCP -->|派生子进程 JSON 命令| PY
    PY --> SWIG
    PY --> IPC
    SWIG --> FILES
    IPC --> GUI
    FILES <--> HUMAN
    GUI <--> HUMAN

核心结论： 联动有两个层次——

两种后端可自动切换（auto 模式：优先 IPC，连不上就回退 SWIG）。

二、前置条件

三、第一步：安装 KiCad

1. 到 kicad.org/download 下载官方安装包。
2. Windows 安装时确认勾选 Python 组件（官方安装器默认勾选，务必保留）。
3. 安装完成后，找到 KiCad 捆绑的 Python，验证 pcbnew 模块可用：

1
2

# Windows（以本机 KiCad 10.0 为例）
& "D:\Program Files\KiCad\10.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"

⚠️ 路径坑（重点）：KiCad 9.0 的老文档写的是 lib\python3\dist-packages，但 KiCad 10.0 的 Windows 实际布局是 bin\Lib\site-packages。请以你自己机器上的 import pcbnew 能成功为准来定 PYTHONPATH，不要照抄老文档。

四、第二步：安装 KiCad-MCP-Server

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 1. 克隆 stable 分支（只随正式版本更新，最稳）
git clone --branch stable https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# 2. 安装 Node 依赖
npm install

# 3. 用 KiCad 捆绑的 Python 安装 Python 依赖（关键！）
& "D:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -r requirements.txt

# 4. 编译 TypeScript → 生成 dist/index.js
npm run build

⚠️ 最容易踩的两个坑：

1. 必须用 KiCad 捆绑的 python.exe 装 requirements，装到系统 Python 里等于白装——MCP Server 启动时 import pcbnew 会失败。
2. npm run build 不能省略，MCP 配置指向的是 dist/index.js，不编译就没这个文件。

Python 依赖清单（requirements.txt 核心项）

备选：仓库还提供了自动化脚本——Windows 用 setup-windows-opencode.ps1（针对 OpenCode 客户端），macOS 用 setup-macos.sh（--verify / --dry-run / --apply）。手动装更通用，脚本装更省事。

五、第三步：配置 MCP 客户端，把两者接起来

MCP Server 通过 stdio 与客户端通信，客户端只需在配置文件里声明"用 node 跑 dist/index.js，并带上 KiCad 的 Python 路径"。

5.1 WorkBuddy（本机方案）

编辑 C:\Users\<用户名>\.workbuddy\mcp.json，在 mcpServers 里加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["F:\\KiCAD-MCP-Server\\dist\\index.js"],
      "env": {
        "PYTHONPATH": "D:\\Program Files\\KiCad\\10.0\\bin\\Lib\\site-packages",
        "KICAD_PYTHON": "D:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      },
      "disabled": false
    }
  }
}

5.2 Claude Desktop

配置路径：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/path/to/kicad/site-packages",
        "LOG_LEVEL": "info"
      }
    }
  }
}

5.3 各平台 PYTHONPATH 速查

路径不确定时，直接运行 python -c "import pcbnew; print(pcbnew.__file__)"，打印出来的目录就是 PYTHONPATH。

5.4 完整环境变量清单

六、联动机制详解：两种工作模式

6.1 文件级联动（SWIG，默认可用，无需开 KiCad）

MCP 用 pcbnew 模块直接读写 .kicad_sch / .kicad_pcb 文件，KiCad 界面不用开着也能干活。

• AI → 人：AI 用 MCP 工具改完文件 → 人在 KiCad 里 File → Revert（或关闭重开 PCB/原理图编辑器）→ 看到改动。
• 人 → AI：人在 KiCad 里编辑 → Ctrl+S 保存 → AI 用 get_board_info 等工具读回最新状态。

特点：无需 GUI、稳定；但同步是"手动 save/reload"，约 1~5 秒延迟，属于"近实时"。

6.2 实时联动（IPC，实验性，改动秒级上屏）

MCP 通过 kicad-python (kipy) 库，用 Protobuf over socket 直接连运行中的 KiCad 进程，改动立刻出现在 UI，无需手动刷新，还支持 undo/redo 事务。

开启条件（缺一不可）：

1. KiCad 9.0+ 正在运行；
2. KiCad 内开启 IPC：Preferences → Plugins → Enable IPC API Server；
3. 已安装 kicad-python（pip install kicad-python，requirements 里已含）；
4. PCB 编辑器里打开了一个 board。

后端自动选择：启动时 auto 模式先试 IPC，连不上自动回退 SWIG（文件操作仍可用）；KiCad 稍后启动并开 IPC 后，下一次调用支持 IPC 的工具会自动重连切到 IPC。 注意"会话钉扎"：一旦 open_project 把项目钉在 SWIG 上，本次会话不会中途升到 IPC，需在 GUI 里打开同一工程后重新 open_project 才会切到 IPC。

6.3 三种典型联动工作流

flowchart TB
    subgraph W1["工作流 1 · AI 布局，人工复核"]
        direction LR
        A1["① AI 放置全部元件"] --> A2["② AI 布关键走线"] --> A3["③ 人复核 / 微调 / 补完布线"] --> A4["④ 保存 → AI 读回最终结果"]
    end
    subgraph W2["工作流 2 · 人工画骨架，AI 精修"]
        direction LR
        B1["① 人放主要元件"] --> B2["② 保存 → AI 读布局给建议"] --> B3["③ AI 补放其余元件"] --> B4["④ 人 reload 复查，循环迭代"]
    end
    subgraph W3["工作流 3 · IPC 实时结对设计（需开 KiCad + IPC）"]
        direction LR
        C1["① AI 放 R1 → UI 立刻可见"] --> C2["② 人在 UI 移动 D1 → AI 立刻读到新位置"] --> C3["③ 来回接力，无需手动 save/reload"]
    end

七、验证联动是否成功

7.1 确认 MCP Server 能启动

1
2
3

cd F:\KiCAD-MCP-Server
$env:PYTHONPATH = "D:\Program Files\KiCad\10.0\bin\Lib\site-packages"
node dist\index.js

能稳定挂住不秒退，说明 pcbnew 导入成功（秒退基本就是 PYTHONPATH 不对）。

7.2 让 AI 跑一句冒烟测试

在客户端对话里说：

1

用 kicad 的 check_kicad_ui 工具检查一下 KiCad 状态。

返回里重点看三个字段：

• backend：ipc 还是 swig
• realtime_sync：是否实时同步
• ipc_connected：IPC 是否已连上

7.3 端到端验证（文件级）

1

帮我新建一个项目，放一个 10k 电阻在 (30,30)mm，再跑一下 DRC。

然后人工打开 KiCad 工程，确认元件确实在里面。

八、常见问题排查

看日志

日志默认在 ~/.kicad-mcp/logs/kicad_interface-<pid>.log（每个 Server 进程一个文件），排错优先看这里。

九、本机实际配置速查（Windows / KiCad 10.0）

十、一句话总结

装 KiCad（带 Python）→ 装 Node → clone KiCAD-MCP-Server → 用 KiCad 的 python 装 requirements → npm run build → 在 MCP 客户端里配置 node dist/index.js + 正确的 PYTHONPATH → 重启客户端。 默认走 SWIG 文件级联动（无需开 KiCad），要实时就在 KiCad 里开 IPC API Server 走 IPC 后端。