用途
mcp-server-kicad 让 AI 助手在不破坏文件的前提下编辑真实的 KiCad 项目，覆盖原理图捕获、PCB 布局、符号与封装库、ERC/DRC 及制造导出。模型通过调用工具直接修改磁盘上的 KiCad 文件，无需截图、复制粘贴或手动编辑 s-expression。
主要能力
提供 109 个 MCP 工具，涵盖原理图绘制、PCB 布局、符号和封装库操作、ERC 和 DRC、制造文件导出（Gerber、BOM、3D 模型）等。每个工具都作用于真实文件，写入经过字节保留底层，确保未请求更改的字节原样到达磁盘；无法正确完成的编辑会被拒绝，文件保持完好。该机制覆盖此服务器对电路板或原理图的所有编辑。KiCad 本身仅在两处写入设计文件：库升级（会自行说明）以及 autoroute_pcb 的路由副本（pcbnew 保存的新板，原板不受影响）。
使用方式
安装插件（Claude Desktop）
从最新 release 下载 kicad-<version>.mcpb，在 Settings 中安装，然后打开 Extensions。Claude Desktop 会自行获取 Python 和包本身，因此只需先安装 KiCad。填写其要求的原理图、电路板和导出路径。与 Claude Code 插件不同，Desktop 不从项目目录运行，因此不会自动检测。除非 KiCad 安装在特殊位置，否则将 kicad-cli 字段留空；标准安装在各平台均可自动找到。设计技能仅限 Claude Code。
统一服务器
将 MCP 客户端指向统一服务器，并将 cwd 设为 KiCad 项目目录，使路径自动解析。该单一条目会注册全部 109 个工具。若希望将工具拆分到五个较小的服务器，请参阅 Configuration。
五个工具服务器
可作为统一服务器运行，也可分开运行，以便在上下文中使用更少的工具面。
六个设计技能（Claude Code 插件）
仅有工具时，模型可以点击每个按钮；捆绑的技能教会它点击哪些按钮、以什么顺序、以及“完成”是什么样。设计技能在继续之前将其产物交给独立的审查子代理（agents/），因此不良的 BOM 或布局计划会在成为原理图之前被捕获。
路径解析
优先级从高到低：
- 工具参数：每个工具都接受显式路径。
- 环境变量：覆盖任何自动检测结果。
- 自动检测：扫描工作目录中的 .kicad_pro，并据此推导原理图、电路板和库路径。
手动运行
可使用 MCP Inspector 手动驱动服务器。每个服务器也可直接运行。
运行要求
需要 KiCad 9.x 或 10.x（用于将工作交给 KiCad 的工具）。ERC、DRC、所有导出、jobset、get_version、库升级和 update_pcb_from_schematic 都运行 kicad-cli；fill_zones 和 autoroute_pcb 需要 KiCad 的 pcbnew Python 绑定，autoroute_pcb 还需要 Java。从 KiCad 自带符号或封装库放置零件需要这些库，它们随 KiCad 提供。所有其他读写工具直接解析文件，不需要安装 KiCad。
CI 在 Linux 上针对 KiCad 9 和 KiCad 10 运行完整套件，在 macOS 和 Windows 上针对 KiCad 10 运行，另有无 KiCad 的矩阵覆盖 Python 3.10 至 3.14。
查找 KiCad 安装
kicad-cli 先在 PATH 中查找，然后在 macOS 的 /Applications/KiCad/KiCad.app 中，再到标准 Windows 安装文件夹（Program Files 下的机器级和 AppData 下的用户级，最新版本优先）。两个安装程序都不会将其加入 PATH。KiCad 目录中的其他内容以相同方式相对定位，因此任何平台的标准安装都无需配置：自带符号库和提供 pcbnew 的捆绑 Python 均可自动找到。
可覆盖任何设置以适配特殊安装。CLI 支撑的工具始终被注册；没有 kicad-cli 时它们会失败并给出指明 KICAD_CLI_PATH 的消息，而不是从工具列表中消失。
格式版本
每个工具都通过字节保留底层进行解析和编辑，因此服务器自身的读写不会因格式版本拒绝文件，也不会重写未请求更改的字节。工具通过 kicad-cli 或 pcbnew 交给 KiCad 本身的内容，只有在你的安装能加载该文件时才有效；KiCad 9 安装无法加载 KiCad 10 电路板。
autoroute_pcb 和 fill_zones 都需要能加载电路板的 pcbnew：autoroute 用于 DSN 导出和 SES 导入，fill_zones 用于计算填充。两者在开始前都会检查。KiCad 9 的 pcbnew 遇到 KiCad 10 电路板会拒绝，并给出指明两个版本的消息；请安装 KiCad 10 或将 KICAD_PYTHON 指向它。反方向时 autoroute_pcb 会运行并警告，因为路由副本以 KiCad 10 格式返回。无论如何，autoroute 都不会改动原电路板，因为它写入的是副本。
upgrade_symbol_lib 和 upgrade_footprint_lib 是 KiCad 仍会重写文件的唯一位置，因为更改格式正是你所要求的。它重写的是副本：结果以原子方式移入原位，因此库永远不会被写坏一半，且只会触及内容实际变化的文件。每个文件是原子的；库整体不是事务，因此中断的升级会使部分封装已迁移，但不会损坏。仍会生成 <name>.bak 备份，每次运行覆盖，作为成功升级的撤销手段。
fill_zones 和 update_pcb_from_schematic 也曾因让 pcbnew 重写电路板而列于此处，现已不再如此。fill_zones 仍请 pcbnew 计算填充，因为其他方式无法做到，但 pcbnew 只读取：铜皮以坐标返回，由底层拼接进去。update_pcb_from_schematic 已不再使用 pcbnew。两者都让未请求更改的内容保持字节相同，包括格式戳。
限制与注意事项
Windows：受控文件夹访问
Windows Defender 的勒索软件防护（受控文件夹访问）会保护 Documents 文件夹，并阻止未识别应用的写入。KiCad 将自己的数据放在那里（Documents\KiCad 下的 3D 缓存和模板），因此被阻止的写入会在 kicad-cli 启动时导致访问冲突（退出码 3221225477），在任何工作开始前就失败。每次调用都会失败，包括 --version。
该阻止表现为错误 2：系统找不到指定的文件，因此看起来像缺少文件夹而非权限问题。在启用该功能的机器上实测：文件夹明明存在，写入仍失败并报 FileNotFoundError。
kicad-cli 已为你处理：发生该崩溃时，服务器会重试一次，将 KiCad 自己的 KICAD_DOCUMENTS_HOME 指向受保护集之外的本地文件夹，然后在整个会话中复用。无需配置；没有该阻止的机器不会看到这些。自行设置 KICAD_DOCUMENTS_HOME 会选择文件夹并禁用重试。
项目文件是另一回事。同一阻止适用于任何写入，因此如果 KiCad 项目位于 Documents 下，写入工具可能以同样令人困惑的方式失败，服务器无法修复：那是你要求它编辑的位置。请将项目放在受保护文件夹之外，或在 Windows 安全中心、病毒和威胁防护、勒索软件防护、允许应用通过受控文件夹访问中允许这些工具。
其他已知限制
- KiCad 9 安装无法加载 KiCad 10 电路板（工具交给 KiCad 本身时受此限制）。
- CLI 支撑的工具在没有 kicad-cli 时会失败，但不会从工具列表中消失。
- 库升级不是整体事务，中断会导致部分封装已迁移（但不会损坏）。
- 标准安装不需配置；特殊安装可通过环境变量覆盖路径。
总结
该项目适合希望用 AI 助手自动化 KiCad 设计流程的工程师，提供从原理图到制造导出的完整工具链，并通过字节保留写入机制保障文件安全。欢迎提交问题和拉取请求；开发设置见 CONTRIBUTING.md，字节保留写入路径的架构决策见 docs/adr-cst-substrate.md。
