KiCad Schematics

MCP-KiCad

通过与 Claude 对话设计电子原理图。 这是一个 MCP 服务，可让大模型绘制真正的 KiCad 原理图——放置元件、连接网络、添加电源符号并运行 KiCad 自带的电气规则检查——然后交给你一个 .kicad_sch 文件，你可以打开、编辑并用于制造。

阅读西班牙语版

一款 LM2596 降压转换器。没有人手动画出它：它是根据文本描述编译生成的，并且通过了 ERC 检查。

---

它实际能做什么

你用日常语言描述电路。Claude 会编写一段简短的声明式描述，并调用一个工具 compile_schematic，将描述转换为完整的原理图文件。

你： 为我制作一个以约 1 Hz 运行、使用 5 V 电源的 555 无稳态电路。

Claude： [查找 NE555 的实际引脚名称，编写设计并进行编译] 完成——7 个元件，ERC 检查通过。这是预览。

生成的文件可以像其他原理图一样在 KiCad 中打开。它不是图片，而是一个包含真实网络表、可直接用于 PCB 布局的真正文件。

输出为何可用

生成某些东西很容易；生成一份能让人接受的原理图却不容易。每份编译好的原理图在交给你之前都会经过检查，编译器会拒绝输出任何未通过检查的文件：

保证	实现方式
导线不会与其他网络的导线交叉	几何检查会重新检查每一段导线。冲突的导线会改用网络标签
导线不会穿过元件本体	使用相同的检查，并对照每个符号的实际轮廓进行核验
每条声明的连接都存在	重新读取生成的文件，并将其网络表与请求内容进行比较
不会意外产生额外连接	反向执行相同检查——如果导线碰到不该连接的引脚，就会报错
电源符号确实接触其引脚	根据实际接触情况核验，而非依据网络名称
导线相交处都有连接点	该规则是通过测量 KiCad 随附的 115 份原理图得出的：三条或更多导线末端相交处，以及两条导线在引脚处相交处，都要有连接点
KiCad 确认无误	kicad-cli 会对结果运行 ERC，并随结果一并返回报告

如果无法干净地绘制连接，就会改用网络标签，而不会生成错误的导线。原理图绝不会在没有提示的情况下出错。

网络与自身交叉不属于上述情况：无论如何它都属于同一个网络，因此导线会在交叉处断开并加上连接点，而不会被丢弃。只有与其他网络发生真正冲突时，才会导致导线被替换。

它不能做什么

• 不处理 PCB。 不做电路板布局、铜箔布线或 Gerber 文件。有意只处理原理图——错误原理图生成的 PCB 毫无价值。
• 不发明元件。 它使用 KiCad 已安装的符号库；缺少的元件可以通过 find_part / import_part 从外部 KiCad 库导入——安装前会进行核验。如果某个元件无处可找，它会如实告知，而不会自行绘制。
• 不是仿真器。 它会绘制你描述的电路，但不会告诉你这个电路是否合理。

---

要求

KiCad 10	提供 kicad-cli，用于运行 ERC 和渲染。更早版本未经测试。
Claude Desktop 或 Claude Code	或任何其他 MCP 客户端。
Go 1.24+	仅在从源代码构建时需要。

---

安装

选项 A — 一键安装（推荐）

从 Releases 下载 mcp-kicad.mcpb，然后双击。Claude Desktop 会将其安装为扩展：无需编辑 JSON，也无需输入路径。此安装包包含适用于 Windows、macOS 和 Linux 的构建版本，因此同一个文件在所有平台上都能使用。

然后直接跳到检查是否正常运行。

在 Apple Silicon 上，捆绑的 macOS 构建版本会通过 Rosetta 运行。如果你想使用原生版本，请改为从选项 B 下载 mcp-kicad-darwin-arm64。

选项 B — 下载二进制文件

1. 前往 Releases，下载适用于你系统的文件：

   系统	文件
   Windows（Intel/AMD）	mcp-kicad-windows-amd64.exe
   Linux（Intel/AMD）	mcp-kicad-linux-amd64
   Linux（ARM，例如 Raspberry Pi）	mcp-kicad-linux-arm64
   macOS（Apple Silicon）	mcp-kicad-darwin-arm64
   macOS（Intel）	mcp-kicad-darwin-amd64

2. 将它放到任意位置，例如 C:\Tools\mcp-kicad.exe 或 ~/bin/mcp-kicad。

3. 在 Linux 和 macOS 上，为它添加可执行权限：

   chmod +x ~/bin/mcp-kicad
   

   在 macOS 上，首次运行会因二进制文件未签名而被阻止。使用以下命令允许运行：

   xattr -d com.apple.quarantine ~/bin/mcp-kicad
   

无需安装其他内容。该二进制文件是独立的，无需配置文件：它会自行查找 KiCad。

选项 C — 从源代码构建

git clone https://github.com/unmateria/MCP-Kicad.git
cd MCP-Kicad
go build -o mcp-kicad ./cmd/server      # add .exe on Windows

---

将其连接到 Claude

如果你已安装 .mcpb 安装包，则无需执行此步骤——它会自动完成注册。

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

添加服务：

{
  "mcpServers": {
    "kicad": {
      "command": "C:\\Tools\\mcp-kicad.exe",
      "args": []
    }
  }
}

在 Linux 或 macOS 上，命令是普通路径，例如 "/home/you/bin/mcp-kicad"。

Windows 注意： JSON 中的反斜杠必须加倍（C:\\Tools\\...）。单个反斜杠是服务无法启动的最常见原因。

然后完全退出 Claude Desktop 并重新打开。 仅重新加载窗口并不足够——服务作为子进程运行，只有在完全重启后才会启动。

Claude Code

claude mcp add kicad -- /path/to/mcp-kicad

检查是否正常运行

向 Claude 提问：

使用 get_project_info 检查 KiCad 设置。

你应该会收到检测到的 kicad-cli 路径、库目录和输出目录。如果提示找不到 kicad-cli，请参阅下方的配置。

---

使用方法

只需描述电路即可。具体说明你关心的内容——电源电压、所需的元件型号、已确定的数值——其余交给 Claude。

效果不错的提示词：

使用 LM7805 设计一个由 12 V 输入供电的 5 V 稳压电源，并添加输入和输出去耦电容以及电源指示 LED。

帮我制作一块 ATmega328P 最小系统板：16 MHz 晶振及负载电容、复位上拉电阻、ICSP 接口，以及两个电源引脚上的去耦电容。

搭建一个由两个晶体管构成的无稳态多谐振荡器，让两个 LED 以约 2 Hz 的频率闪烁。

之后可以提出的实用请求：

• “显示原理图” — 渲染预览图。
• “导出为 PDF” — 通过 kicad-cli 导出。
• “运行 ERC” — 执行 KiCad 电气规则检查，并解释违规项。
• “将去耦电容移近 U1 并重新编译” — 设计源文件是文本，因此修改起来很方便。

生成的文件会存放在输出目录中（get_output_dir 会告诉你位置；set_output_dir 可以更改该目录）。

设计源文件

在后台，Claude 会编写一份小型 JSON 文档并对其进行编译。你很少需要接触它，但值得了解一下，因为它解释了结果为何稳定——位置从不以毫米为单位指定，而是通过引脚对引脚进行锚定：

{
  "version": 1,
  "project": "led_18650",
  "sheet": "auto",

  "blocks": [
    {
      "name": "led",
      "symbols": [
        { "ref": "BT1", "lib": "Device:Battery_Cell", "value": "18650" },
        { "ref": "R1", "lib": "Device:R", "value": "100", "rot": 90,
          "place": { "pin": "1", "at": "BT1.+", "dir": "up", "cells": 1 } },
        { "ref": "D1", "lib": "Device:LED", "value": "LED_RED", "rot": 90,
          "place": { "pin": "A", "at": "R1.2", "dir": "right", "cells": 3 } }
      ]
    }
  ],

  "nets": {
    "VBAT":   ["BT1.+", "R1.1"],
    "_ANODE": ["R1.2", "D1.A"],
    "GND":    ["D1.K", "BT1.-"]
  },

  "power_nets": { "GND": "power:GND" }
}

每个区块中的第一个符号会作为锚点；其他符号都连接到一个已放置符号的引脚上，距离为整数个 2.54 mm 网格单元。这样一来，无论模型如何调整顺序，原理图都能保持对齐网格且清晰易读。

完整格式详见 internal/tools/design_format.md（与 design_guide 工具提供给模型的文本相同），docs/compiler/ 中还有 13 个完整示例——从由两个部分组成的 LED 电路，到包含 27 个组件的温室控制器。

---

配置

无需配置。服务会在常见位置查找 KiCad：

• Windows — C:\Program Files\KiCad\<version>\bin\kicad-cli.exe，然后是 PATH
• Linux — /usr/bin/kicad-cli、/usr/local/bin/kicad-cli，然后是 PATH
• macOS — /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli，然后是 PATH

如果你的安装位置比较特殊，或者想更改文件的写入位置，请将 config.ini.example 复制到 config.ini，放在可执行文件旁边，然后填写所需内容：

[paths]
kicad_cli  = /opt/kicad/bin/kicad-cli
output_dir = /home/you/schematics
libs_root  = /home/you/mcp-kicad-libs

[api_keys]
mouser                =
digikey_client_id     =
digikey_client_secret =

API 密钥是可选的，且仅用于获取元数据——没有分销商提供 CAD 文件。所有实际提供符号和封装的来源都无需密钥。

生成的文件默认位于 <your home>/mcp-kicad/output。

---

工具

共提供 33 个工具。实际上，Claude 几乎所有操作都通过 compile_schematic 完成；其余工具用于检查和修复现有文件。

设计 compile_schematic · design_guide · get_design_context · kicad_workflow_help · apply_template · list_templates

查找零件 find_part · import_part · check_component_existence · symbol_pins · list_symbol_libraries · register_library

读取原理图 read_schematic · get_connectivity_summary · cluster_components · layout_metrics

手动编辑 create_schematic · add_symbol · connect_pins · disconnect_pin · add_wire · add_label · add_power_rail · junction · no_connect · connect_netlist · batch_schematic

检查和导出 validate_design（ERC/DRC） · export_schematic_image（SVG/PDF） · modify_pcb_layout

设置 get_project_info · get_output_dir · set_output_dir

---

KiCad 没有的元件

KiCad 自带约 22 700 个符号。你需要的那个通常不在其中。 find_part 会同时搜索所有来源，import_part 则会安装候选元件：

find_part   query="ESP32-C3-MINI-1"
import_part ref="espressif:symbols/Espressif.kicad_sym#ESP32-C3-MINI-1"
→ MCP_Imported:ESP32-C3-MINI-1   53 pins, footprint matched, ready for compile_schematic

来源	内容	许可证
已安装	此计算机上的 KiCad 库和所有已导入的内容	—
jlcpcb	JLCPCB 的贴装目录：符号、封装和 3D 模型，全部相互匹配	MIT
cern	CERN 开源硬件：数千个真实零件编号对应的符号	CERN-OHL-P-2.0
digikey-lib	Digi-Key 的库，包含 150 个分类库	按仓库规定
espressif	Espressif 自有的 ESP32 库	按仓库规定
sparkfun	SparkFun 的扩展板、传感器和连接器	CC-SA-4.0
lcsc	LCSC / EasyEDA，转换为 KiCad 格式——按 C 编号涵盖大量长尾元件	第三方数据
mouser、digikey	仅用于识别：根据订单代码查找真实 MPN、制造商、封装和数据手册。没有 CAD 文件——没有分销商提供这些文件。需要 API 密钥	—

每个来源只会被索引一次，存入 libs/cache/，此后即可离线搜索。只有经过验证后才会安装：

1. 可以解析，
2. kicad-cli 能够读回并重新写入，
3. 能放入临时原理图，且引脚已解析，
4. 引脚与封装焊盘进行比较，
5. KiCad 能绘制出来，并生成图像。

验证失败的元件完全不会安装。 半导入的符号比没有符号更糟，因为它看起来像是能用。如果某个元件在所有来源中都不存在，答案就是它不存在——绝不悄悄选用替代品，也绝不凭空绘制几何图形。

所有内容都放入一个库 MCP_Imported，并向 KiCad 注册，因此 GUI 的符号选择器也能看到。每个导入的符号都带有 MCP_Source 属性，记录其来源、许可证和导入时间——这也是 libs/ 不纳入版本管理的原因：它可以根据来源重新生成。

---

工作原理

.design.json → 编译 → .kicad_sch

1. 放置。 每个符号的位置都根据引脚锚点计算，并解析为 2.54 mm 网格上的绝对坐标。
2. 布线。 简短且显然正确的连接使用闭式几何绘制；较长的连接则交给 A* 路由器处理，以避开元件本体。
3. 电源。 每个引脚放置一个电源符号，沿引脚指向偏移，然后对齐成电源轨。
4. 把关。 重新检查每条导线。凡是跨越其他网络、穿过符号或共线重叠的导线，都会被删除并替换为网络标签——连通性得以保留，错误连接则不会。
5. 整理。 将位号和数值文本移出元件本体和导线；将图纸居中，如果电路放不下，则升级纸张尺寸。
6. 验证。 从头重新读取文件，追踪并将其网络表与源文件进行比较，然后运行 kicad-cli ERC。

KiCad 文件通过真正的 S 表达式解析器（internal/sexp）进行读写——绝不通过文本模式匹配处理。

---

已知限制

• 密集图纸上的文本仍可能重叠。 位号和网络标签会移到可选位置中重叠最少的地方，但在拥挤的原理图上，最佳位置有时仍会碰到其他内容。编译器会准确报告剩余问题，以及分别需要增加多少间距才能避免重叠。
• 有些连接会变成标签而不是导线。 这是把关步骤在发挥作用。电气上完全相同，但不那么美观。
• PNG 预览需要 Chromium 系浏览器（Edge、Chrome、Chromium 或 Brave）。如果没有，则改用质量较低的纯 Go 渲染器。目前只有 Windows 路径经过实际验证。
• 已使用 Claude Desktop 和 Claude Code 进行测试。 其他 MCP 客户端应该也能运行，但尚未尝试。

---

开发

go build -o mcp-kicad ./cmd/server   # build
go test ./...                        # all tests
go run ./cmd/verify_e2e              # end-to-end smoke test
go run ./cmd/compile -o out.kicad_sch docs/compiler/led_18650.design.json
go run ./cmd/measure_layout out.kicad_sch    # layout quality metrics
go run ./cmd/pininfo <library.kicad_sym>     # pin positions in a symbol library

# The component sources are claims about the outside world. `go test ./...`
# never touches the network; these re-measure them on demand.
MCP_KICAD_LIVE=1 go test ./internal/parts/providers/ -run TestLive -v
MCP_KICAD_LIVE=1 go test ./internal/tools/ -run TestLiveImportAndCompile -v

docs/compiler/ 中的 13 个来源构成参考语料——对流水线的每项更改都会针对所有来源进行检查。

架构说明见 CLAUDE.md。

---

许可证

PolyForm Noncommercial License 1.0.0 — 可免费用于、修改并分享任何非商业用途，包括个人项目、业余电子制作、教育、研究和非营利组织。此许可证不授予商业使用权。