KiCad Tools

mcp-server-kicad

让 AI 助手编辑真实的 KiCad 项目，而不破坏项目文件。

109 个 MCP 工具，涵盖原理图绘制、PCB 布局、符号和封装库、ERC 和 DRC，以及制造文件导出。无需截图、复制粘贴，也无需手动编辑 s-expression：模型调用工具，KiCad 文件随之在磁盘上更改。

快速开始 • 功能一览 • 配置 • 工具参考 • 要求 • 贡献

重要

维护模式。 截至 2026 年 10 月，本项目仅提供安全修复和 KiCad 兼容性修复，不计划新增工具或功能。现有安装仍可正常使用。原因

为何进入维护模式

这个插件基于一个理念构建：KiCad 文件很大，因此 AI 助手应通过工具修改文件，而不是直接编辑文本。我们将这一理念与未安装插件、但已安装 KiCad 的普通 Claude Code 进行了测试：使用相同的模型（Claude Opus 5.5）、相同的设置和相同的任务，并由 KiCad 10 本身评判每项结果（网表、板子、ERC 和 DRC）。

• 六项单独编辑，针对一个公开的 KiCad 10 设计（更改数值、设置为不贴装、替换封装、为焊盘分配网络、旋转封装、跨图纸重命名网络），每项运行三次。普通 Claude Code 18 次全部正确。使用插件时，18 次中只有 3 次正确。
• 一次包含 20 项板级编辑的长会话。 两者都正确完成了所有编辑，而插件会话消耗的上下文约为 1.8 倍。
• 通过阅读每份对话记录，发现插件失败的原因：
  • 某些编辑没有对应的工具（焊盘的网络、不贴装标记、替换单个封装）。
  • 插件指示模型绝不要直接编辑 KiCad 文件，因此模型停下来改为询问。
  • 板同步工具重写了板上几乎所有封装，导致模型撤销了自己的工作。
• 这些测试未能验证最初的设想。 普通 Claude Code 修改了一个 2 MB 的板子，却没有读取整个文件：它搜索目标元件，只编辑所需的行。

这些都是针对单个设计的小规模测试，并不能代表所有板子或模型。但结果足以让我们停止添加工具。测试材料未公开，因为所用设计没有附带许可证。

替代方案： 使用安装了 KiCad 的编码 Agent，例如 Claude Code。要求它在完成前使用 kicad-cli 检查更改（导出网表、ERC、DRC）。

仍欢迎提交 KiCad 兼容性问题报告和修复。

效果展示

"Add a 100 nF decoupling cap on U1's VCC pin, then check ERC."

  get_pin_positions            locate U1's VCC and GND pins
  auto_place_decoupling_cap    place C3 and wire both pins to their nets
  run_erc                      report what the change broke

"Now push the netlist to the board and route it."

  update_pcb_from_schematic    sync footprints and pad nets onto the PCB
  autoroute_pcb                route with Freerouting
  run_drc                      clearance, width, and unconnected checks

每个工具都直接操作真实文件，写入操作只会更改你指定的字节。无法正确完成的编辑会被拒绝，并保持文件原样。KiCad 本身仅在两种情况下写入设计文件：升级库，以及 autoroute_pcb 生成布线副本时；后者会创建一块新板，不会改动你的板子。

快速开始

Claude Code

安装插件。它会配置服务器，并随附设计技能：

claude plugin marketplace add ProductOfAmerica/mcp-server-kicad
claude plugin install kicad

Claude Desktop

从最新版本下载 kicad-<version>.mcpb，然后依次从 Settings 和 Extensions 安装。 Claude Desktop 会获取 Python 和软件包本身；你需要安装 KiCad，此外，autoroute_pcb 还需要 Java 25 或更高版本。

Desktop 不会在你的项目目录中运行，因此请填写它要求提供的原理图、板和导出路径。除非 KiCad 安装在不常见的位置，否则 kicad-cli 字段留空即可。设计技能仅适用于 Claude Code。

其他所有客户端

pip install mcp-server-kicad

然后将 MCP 客户端指向统一服务器，并在 env 中用绝对路径指定原理图、板和导出文件夹，这样工具无需每次调用时都收到路径：

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad"],
      "env": {
        "KICAD_SCH_PATH": "/path/to/project/project.kicad_sch",
        "KICAD_PCB_PATH": "/path/to/project/project.kicad_pcb",
        "KICAD_OUTPUT_DIR": "/path/to/project"
      }
    }
  }
}

这一个条目会注册全部 109 个工具。如果客户端在你的项目文件夹中启动服务器，则可以省略 env：服务器会从其中唯一的 .kicad_pro 文件获取路径（参见路径解析方式）。 想把工具拆分到五个较小的服务器中？请参见配置。

你将获得

五个工具服务器

可将它们作为一个统一服务器运行，也可以在需要减少上下文中的工具数量时分别运行。

六项设计技能（Claude Code 插件）

仅有工具，就能让模型点击每个按钮。随附的技能会教它该点哪些按钮、按什么顺序操作，以及如何判断“完成”。

设计技能会先将其产物交给独立的审查子 Agent（agents/）检查，再继续下一步，因此不合格的 BOM 或摆放计划会在变成原理图之前被发现。

配置

拆分服务器

需要只加载部分工具时，可使用五个条目，而不是一个：

{
  "mcpServers": {
    "kicad-schematic": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-schematic"]
    },
    "kicad-pcb": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-pcb"]
    },
    "kicad-symbol": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-symbol"]
    },
    "kicad-footprint": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-footprint"]
    },
    "kicad-project": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-project"]
    }
  }
}

uvx --from mcp-server-kicad mcp-server-kicad-schematic

优先级从高到低：

1. 工具参数。 每个工具都接受显式路径。
2. 环境变量。 环境变量会覆盖自动检测的任何内容。
3. 自动检测。 扫描工作目录以查找 .kicad_pro，并据此推导原理图、板和库的路径。

要求

• Python 3.11+

• KiCad 9.x 或 10.x，仅供调用 KiCad 的工具使用：

  • kicad-cli：ERC、DRC、导出、作业集、get_version、库升级和 update_pcb_from_schematic
  • pcbnew Python 绑定：fill_zones 和 autoroute_pcb（后者还需要 Java 25 或更高版本；请参阅下载 Freerouting）
  • KiCad 自带库：放置自带符号或封装时需要

  其他所有工具都直接解析文件，无需 KiCad。

CI 覆盖 Linux（KiCad 9 和 10）、macOS 和 Windows（KiCad 10），以及 Python 3.11 到 3.14。

下载 Freerouting

autoroute_pcb 会运行 Freerouting。 除非 FREEROUTING_JAR 指定了 jar 文件，否则首次调用时会从 https://github.com/freerouting/freerouting/releases/download/v2.5.0/freerouting-2.5.0.jar 下载 Freerouting 2.5.0，即 freerouting-2.5.0.jar（65 MB，需要 Java 25 或更高版本），并将其缓存为 ~/.local/share/mcp-server-kicad/freerouting-2.5.0.jar （Windows 上为 %USERPROFILE%\.local\share\mcp-server-kicad\）。保存下载文件前，以及每次使用缓存副本时，都会将其 SHA-256 与此软件包中固定的值进行校验。校验不匹配的下载不会保存；校验不匹配的缓存副本不会运行，并会重新下载。

运行 Freerouting 时会使用 --gui.enabled=false 和 --usage_and_diagnostic_data.disable_analytics=true，这是其文档为无头运行和不发送使用数据提供的设置，因此不会打开窗口，分析功能也会保持关闭。启动时，Freerouting 仍会向 GitHub 查询最新版本；它没有提供关闭此功能的设置。

若要跳过下载，请将 FREEROUTING_JAR 设为你信任的 Freerouting jar 文件的绝对路径。该 jar 文件会按原样使用，不进行哈希校验。相对路径或指向不存在文件的路径会被忽略，程序将继续下载。较早版本会在同一文件夹中缓存未固定版本的 freerouting.jar；现在不再读取该文件，可以将其删除。

查找 KiCad 安装位置

标准安装无需配置。程序会先在 PATH 中查找 kicad-cli，然后查找 macOS 上的 /Applications/KiCad/KiCad.app，最后按从新到旧的顺序查找 Windows 上的 Program Files 和 AppData。自带库和 pcbnew 的 Python 会根据其位置查找。对于特殊安装：

如果没有 kicad-cli，需要它的工具仍会列出，但会报错并指出 KICAD_CLI_PATH。

KiCad 10 文件

该服务自身的读写功能同样支持 KiCad 9 和 10 的原理图、PCB、符号库和封装，且不会更改任何非指定字节（参见 docs/adr-cst-substrate.md）。交由 KiCad 自行处理的任务只有在安装版本能够加载文件时才能成功，而 KiCad 9 无法加载 KiCad 10 的 PCB：

• fill_zones 和 autoroute_pcb 在启动前会拒绝使用 KiCad 9 pcbnew 处理 KiCad 10 的 PCB；请安装 KiCad 10，或将 KICAD_PYTHON 指向 KiCad 10。使用 KiCad 10 的 pcbnew 处理 KiCad 9 的 PCB 时，autoroute_pcb 可以正常工作，但会警告路由后的副本将以 KiCad 10 格式返回。它绝不会触碰原始 PCB。
• upgrade_symbol_lib 和 upgrade_footprint_lib 会按设计交由 KiCad 重写文件。每个文件仅在内容发生变化时才会被原子替换，因此升级中断不会损坏任何文件。备份会保存为 <name>.bak，每次运行都会覆盖。

Windows：受控文件夹访问

Defender 的受控文件夹访问会阻止未识别的应用写入 Documents，而 KiCad 会在此处保存数据。因此，kicad-cli 每次调用时都会在启动阶段崩溃（退出代码 3221225477），包括 --version，且错误看起来像是文件缺失：error 2: The system cannot find the file specified。

该服务会尝试绕过此问题：将 KICAD_DOCUMENTS_HOME 指向一个不受保护的本地文件夹后重试一次，并在本次会话中继续使用该设置。你可以自行设置 KICAD_DOCUMENTS_HOME 来指定文件夹（这样会关闭重试）。

无法修复你的项目文件。 如果项目位于 Documents 下，写入工具也会以同样的方式失败。请移动项目，或前往 Windows 安全中心 > 病毒和威胁防护 > 勒索软件防护 > 允许应用通过受控文件夹访问，将这些工具加入允许列表。

工具参考

调试

使用 MCP Inspector手动驱动服务：

npx -y @modelcontextprotocol/inspector uvx --from mcp-server-kicad mcp-server-kicad

参与贡献

欢迎提交问题和拉取请求。开发环境设置请参阅 CONTRIBUTING.md，有关字节保留写入路径背后的架构决策，请参阅 docs/adr-cst-substrate.md。

• 报告错误
• 浏览未解决的问题
• 安全政策
• 行为准则

许可证

GPL-3.0-or-later。截至 0.20.1（含）的版本采用 MIT 许可证；详见 NOTICE。