KiCad Agentic MCP

面向 KiCAD 10 的 AI 辅助 PCB 设计。 Konnect 是一个原生 KiCAD 插件——一个 Rust 二进制文件——让 Claude 和其他 AI 助手通过 Model Context Protocol（MCP）设计原理图和 PCB。

22 个按需工具集中的 202 个工具。 原理图捕获、PCB 布局与布线、ERC/DRC、设计审查审计、JLCPCB 零件搜索、Freerouting、参考电路，以及完整的制造导出流水线——内置技能和代理，开箱即用地教会 Claude KiCAD 约定。

本仓库是 KiCad Agentic MCP，是 mixelpixx/Konnect v0.2.2 的一个代理分支，采用相同的 AGPL-3.0 许可证。在 Konnect 的工具表面之上，它增加了 MCP 网关、带有确定性执行器的计划 IR、证据句柄、任务状态和本地模型运行时。服务器二进制文件仍称为 konnect。

状态：v1.1.1。 它衡量什么、遗漏什么以及不涵盖什么，见 RELEASE_NOTES.md；下面引用的每个数字都追溯到 docs/benchmark.md。欢迎提交问题和 PR——见 CONTRIBUTING.md 和 命名约定。

一个提示词能做什么

一个提示词，作用于提交在 examples/demo/ 中的起始板——可复现，而非示意。KiCAD 的裁决，而非我们的： 之前有 5 个未连接项，之后 0 个，11 段走线，无错误；从相同状态运行两次，两次电路相同，坐标不同。

两个数字，因为它们衡量两件不同的事情： 板子变更在 不到一秒 内落地（Konnect 时间为 0.69 秒和 0.77 秒），而围绕它们的提示词需要 6 到 7 分钟，因为模型每轮只布线一段。两次运行的每次调用记录在 demo-run-2.md 和 demo-run-3.md 中。

Related MCP server: KiCad MCP Pro

快速开始

从发布页面到 KiCAD 自身确认的变更，共五步。在一台从未安装过 Konnect 的机器上走过；记录（包括出错的地方）见 docs/launch/first-run-walk.md。

那次走查测量的内容：从启动 KiCAD 到安装插件大约九次点击和对话框，两次 KiCAD 重启，以及一个在 108 毫秒 内返回的首个任务。总时间取决于你点击的速度，因此不作为一个数字引用。

开始之前，你需要 KiCAD 10（已针对 10.0.3 测试）和一个 MCP 客户端——Claude Desktop、Claude Code 或任何其他支持 MCP 的工具。没有其他要求：不需要 Node、Python 或包树。Windows 是测试最多的平台；macOS 和 Linux 的状态见 要求。

1 — 下载插件包。 从 Releases 获取 konnect-pcm-v<version>-windows.zip（或 -macos.zip / -linux.zip）。konnect-pcm-* 资产是 KiCAD 插件包；其他归档是独立的服务器二进制文件，此路径不需要它们。

2 — 安装它。 KiCAD 10 → 插件和内容管理器 → 从文件安装… → 选择 zip。选择文件的那一刻即安装——应用待处理更改 按钮保持灰色，无需进一步确认。重启 KiCAD。

3 — 打开 KiCAD API。 偏好设置 → 插件 → 勾选 启用 KiCad API，然后重启 KiCAD。KiCAD 默认 关闭 此选项，这里的所有 PCB 工具都通过它和 KiCAD 通信。原理图编辑和导出无需它即可工作；实时板编辑则不行。重启后，同一页面应显示 Listening on ipc://…。

4 — 将 MCP 客户端指向服务器。 PCM 安装后，二进制文件位于你的 KiCAD 文档文件夹中：

C:\Users\<YOU>\Documents\KiCad\10.0\3rdparty\plugins\com_github_mixelpixx_konnect\bin\konnect.exe

将该路径放入客户端的 MCP 配置中——Claude Desktop 使用 %APPDATA%\Claude\claude_desktop_config.json，Claude Code 使用项目根目录下的 .mcp.json。两者的复制粘贴版本在 examples/ 中，完整片段在 下方。重启客户端；konnect 应在启动时报告 21 个工具。这就是完整的入门套件——目录的其余部分按需加载，或通过网关调用而从不出现在 tools/list 中。标准 KiCAD 10 安装不需要 konnect-settings.json：v1.1.1 会自动发现 kicad-cli、KiCAD GUI 二进制文件和 IPC 地址。对于不常见或便携式安装，仍提供显式设置。

5 — 给它一些事情做，并打开一个 KiCAD 项目。例如：

向我的原理图添加一个 3.3 V LDO 稳压器子电路，并对其运行 ERC。

回复应指明它放置的部件——一个稳压器、其输入和输出电容——并携带来自 kicad-cli 而非模型的 ERC 结果。在 KiCAD 中打开原理图：符号就在那里。

随时检查安装本身： 打开一个项目（KiCAD 的 PCB 编辑器拒绝在没有项目的情况下打开），然后 PCB 编辑器 → 工具 → 外部插件，你应该看到 Konnect。

这还不能做什么

• PCB 工具需要运行中的 KiCAD，且 API 已打开、板已打开。没有无头 PCB 路径——pcbnew 没有。

• macOS 二进制文件未签名或未公证。 Gatekeeper 会在首次启动时阻止它们；macOS 部分 有确切的 xattr 命令。

• Linux 可编译并通过 CI，但未针对运行中的 KiCAD 进行平台级 QA。

• 符号和焊盘是放置而非创建。 Konnect 搜索并使用现有库部件；创建新部件在 路线图 上。

如果上述五步中有任何一步对你不奏效，那正是值得报告的事情：提交首次运行报告。大约需要两分钟，这是让这些在非维护者机器上得到测量的唯一方式。

为什么 Konnect 存在

Konnect 是 KiCAD-MCP-Server 的继任者，后者是一个 Python/TypeScript 项目，证明了 AI 驱动的 PCB 设计可行——并且在此过程中，展示了该架构在哪些地方走到了尽头。Konnect 旨在解决这些具体问题：

调用路径太长。 在原始服务器中，一次工具调用要经过 TypeScript、模式验证、生成的 Python 子进程、stdin/stdout 上的 JSON、命令路由器，最后是 SWIG 生成的 C++ 代理对象，才能触及你的板。那是四个语言和序列化边界，每个都有自己的故障模式——子进程生命周期管理、过滤 KiCAD 泄漏到流中的警告的 stdout 解析、分块 JSON 重组。在 Konnect 中，工具调用就是函数调用。一个进程、一种语言、没有管道。

依赖面巨大。 运行原始版本意味着携带 Node.js 及其 npm 树、Python 及其 pip 包、wxPython、kicad-skip 和 KiCAD 的 SWIG 绑定——两个包生态系统加上一个绑定层，每一个都是可能破坏安装的移动目标。Konnect 是一个二进制文件——Windows 上 24 MB，无解释器、无包树。无需安装其他任何东西，也无需版本匹配。

SWIG 是死胡同。 原始版本的 PCB 后端依赖 KiCAD 的 SWIG Python 绑定，而 KiCAD 正弃用这些绑定，转而使用其 IPC API。SWIG 还带有实际的操作伤疤：可能导致后端段错误的区域填充调用、代理对象比较错误，以及可能在会话中途静默切换后端的回退路径。Konnect 通过官方 IPC API（基于 NNG 的 protobuf）与 KiCAD 10 通信——这是 KiCAD 正在投入的接口——实时板编辑与 KiCAD 自身的撤销/重做集成。

原理图编辑不应损坏文件。 Konnect 通过自己的 S 表达式引擎编辑 .kicad_sch 文件，具有原子写入（写入、fsync、重命名）、UUID 保留和往返测试——没有已知缺口的第三方原理图库，没有文本操作变通方法。

上下文经济性是一个特性。 提供整个目录——所有工具集加载后共 215 个工具——每次列出消耗 33K 令牌 的上下文。Konnect 的路由器以 21 个工具 / 2.8K 令牌 的入门套件启动，让模型按需拉取工具集，或完全跳过目录，通过网关（kicad_describe / kicad_invoke）调用工具，这完全不会改变 tools/list——加上内置的可观测性（get_recent_calls、server_stats、JSONL 调用日志），使模型能够诊断自己的工具故障。这些数字是测量的，而非估计：见 docs/benchmark.md。

结果是更小、安装更快、与 KiCAD 的发展方向一致，并且为生产使用而非实验而构建。原始项目仍然开放、维护且有用——见 下面的比较。

它能做什么

AI 不是描述更改并手动应用，而是直接操作你的项目：

• 放置并连接原理图组件 — 添加电阻、IC、连接器；按引脚名称连接它们

• 布局 PCB — 通过 KiCAD 的 IPC API 实时放置、移动、旋转和布线焊盘，完全集成撤销/重做

• 运行设计检查 — ERC、DRC、连接性验证、去耦审计、电源轨审查、BOM 健康检查

• 导出生产文件 — Gerber、钻孔、BOM、贴片、3D 模型、PDF

• 搜索 JLCPCB 零件 — 在本地 250 万零件目录中查找库存组件并建议替代品

• 从参考电路开始 — USB-C、LDO、降压转换器、STM32、I2C、LED 模板，带有验证过的组件值

• 实时观看 — 实时原理图查看器在 AI 编辑时自动刷新

完整工具目录记录在 tool-directory.md 中。

工作原理

安装

从 KiCAD 插件管理器（推荐）

1. 从 Releases 下载适用于你操作系统的软件包： konnect-pcm-v<version>-windows.zip、-macos.zip 或 -linux.zip。每个 软件包都捆绑了对应平台的服务器二进制文件——macOS 软件包是通用构建， 一次下载即可覆盖 Apple Silicon 和 Intel。（konnect-pcm-* 资源是 KiCAD 插件包；其他压缩包是独立的服务器二进制文件。）

2. 打开 KiCAD 10 → 插件和内容管理器

3. 点击 从文件安装 并选择 zip 文件。选择后即开始安装—— 应用待定更改 保持灰色，无需其他确认

4. 重启 KiCAD

5. 启用 KiCAD API：首选项 → 插件 → 启用 KiCad API，然后 再次重启 KiCAD。该功能默认关闭，而每个 PCB 工具都需要它

验证：打开（或创建）一个项目——没有项目时 KiCAD 的 PCB 编辑器无法打开—— 然后进入 PCB 编辑器 → 工具 → 外部插件 → 你应该能看到 Konnect。

从源码构建

# protoc is required (protobuf code generation), and cmake (the nng crate
# compiles the NNG C library with it).
# Windows: choco install protoc cmake
# macOS:   brew install protobuf cmake
# Linux:   apt install protobuf-compiler cmake
cargo build --release -p konnect

macOS

Releases 页面提供 适用于 Apple Silicon（aarch64-apple-darwin）和 Intel（x86_64-apple-darwin）的独立服务器二进制文件。它们尚未进行代码签名， 因此如果你通过浏览器下载，请在首次启动前清除隔离标志：

tar xzf konnect-v*-aarch64-apple-darwin.tar.gz
xattr -d com.apple.quarantine ./konnect   # only needed for browser downloads
./konnect --help

或者按上述方法从源码构建（已在 Apple Silicon 上验证；同一个 target/release/konnect 二进制文件就是 MCP 服务器）。

macOS 上的 KiCad 将其工具保存在应用包内，且不在 PATH 中； v1.1.1 会自动搜索标准应用包并使用 KiCad 的默认 IPC 地址。只有非常规或重命名的安装才需要在 ~/Library/Application Support/konnect/config.toml 中显式覆盖：

kicad_cli = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
kicad_binary = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad"
# Optional override; the default is ipc:///tmp/kicad/api.sock.
ipc_address = "ipc:///tmp/kicad/api.sock"

Claude Desktop 的配置位于 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "konnect": {
      "command": "/path/to/konnect"
    }
  }
}

对于 Claude Code，将相同的片段放在项目根目录的 .mcp.json 中。

macOS 的 PCM 软件包（konnect-pcm-v<version>-macos.zip）捆绑了 通用服务器二进制文件，一次下载即可覆盖两种架构。原理图 查看器可以在 macOS 上编译并启动（Tauri 2 使用系统 WKWebView—— WebView2 仅是 Windows 的要求），但尚未像 Windows 构建那样经过充分测试。

使用 Claude Desktop 设置

PCM 安装后，服务器二进制文件位于你的 KiCAD 文档文件夹中：

C:\Users\<YOU>\Documents\KiCad\10.0\3rdparty\plugins\com_github_mixelpixx_konnect\bin\konnect.exe

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "konnect": {
      "command": "C:\\Users\\<YOU>\\Documents\\KiCad\\10.0\\3rdparty\\plugins\\com_github_mixelpixx_konnect\\bin\\konnect.exe"
    }
  }
}

重启 Claude Desktop 后 Konnect 工具就会出现。对于 Claude Code，将相同的 片段放入项目根目录的 .mcp.json 中（参见 examples/）。

原理图查看器

一个独立的查看器，在原理图文件变化时自动刷新：

schematic-viewer.exe path\to\your\root_schematic.kicad_sch

将其指向层次化设计的根图纸，所有子图纸也会被 渲染，工具栏中带有缩进深度的图纸选择器。从 KiCAD 保存的编辑（或 AI 通过原理图工具所做的编辑）只会重新渲染发生变化的图纸 并实时刷新视图——渲染针对临时文件夹快照进行，因此 查看器永远不会阻止 KiCAD 保存。单击拖动平移，滚轮缩放， 0 适配窗口，R 刷新，拖放以打开其他文件。AI 也可以通过 open_schematic_viewer 工具启动它。

需要 WebView2 运行时（Windows 10/11 预装）和 KiCAD 安装以获取 kicad-cli（自动发现，或传入 --kicad-cli <path>）。与 主工作区分开构建——构建步骤参见 DEV.md。

要求

• KiCAD 10（Windows 是测试最充分的平台；macOS 可通过发布 二进制文件或源码构建使用——参见上面的 macOS 部分。Linux 可在 CI 中编译并通过测试，但尚未进行针对平台的 QA；两者均已在 路线图 中跟踪）

• kicad-cli（随 KiCAD 附带——用于导出、ERC、DRC）。KiCAD 的安装程序 不会将其加入 PATH；服务器会搜索常见的安装位置， 如果你的安装位置不同，也可以显式指定

• 对于 PCB 工具：KiCAD 正在运行且目标板已打开，并且 KiCAD API 已开启——首选项 → 插件 → 启用 KiCad API，该功能默认关闭

许可证：对小规模用户免费

Konnect 根据 GNU AGPL-3.0 许可。

如果你是爱好者、学生、自由职业者或开源项目：自由使用， 无任何附加条件。 设计板卡、出货、销售。

如果你是企业：AGPL 要求你在 Konnect 之上或周边构建的任何内容—— 包括通过网络提供的软件——必须以相同许可证开源。 如果这不适合你，可提供商业许可证：参见 COMMERCIAL.md。

与 KiCAD-MCP-Server 的关系

原始的 Python/TypeScript 项目 仍然完全开源（MIT）并持续维护。Konnect 是新的开发发生地—— 它所验证的架构，为生产环境重新构建：

故障排除

插件未出现在 KiCAD 中 — 通过插件和内容管理器安装（不要 手动复制），然后重启 KiCAD。入口位于 PCB 编辑器 的 工具 → 外部插件 下，而 PCB 编辑器在项目打开之前根本无法启动。

PCB 工具返回 "IPC connect failed" — 两个独立的条件必须同时 满足：首选项 → 插件 → 启用 KiCad API 已勾选（KiCAD 默认将其 关闭），并且 KiCAD 正在运行且你的板文件已打开。重启后 API 页面应显示 Listening on ipc://…。 docs/TROUBLESHOOTING.md 详细介绍了这两点。

"Failed to spawn kicad-cli" — 服务器按以下顺序查找 kicad-cli： 配置中的 kicad_cli 值（如果你设置了的话），然后是 PATH，然后是已知的 安装前缀（包括 %LOCALAPPDATA%\Programs\KiCad\<ver>\bin， KiCAD 的安装程序会将按用户安装放在此处），最后是 Windows 注册表。启动时 它会记录是哪一个响应的。如果都没有——非常规安装位置、 便携式副本——请在插件设置对话框或配置文件中显式设置 kicad_cli。

验证器报告错误而不是零发现 — 这是有意为之。无法运行的检查 绝不会被报告为已通过的检查。

支持

• 第一次使用？ 提交首次使用报告 — 六个问题，大部分只需点击一次。来自放弃使用者的报告 比来自成功使用者的报告更有价值。反馈结果汇总在 docs/adoption.md 中。

• 错误与功能请求：GitHub Issues

• 安装或 IPC 套接字遇到问题：docs/TROUBLESHOOTING.md

• 路线图：ROADMAP.md

• 贡献：CONTRIBUTING.md

无遥测。 Konnect 不报告任何内容，在任何地方，任何时候。关于它在 其他人机器上行为的所有已知信息都来自有人选择将其记录下来。一个编辑 你的设计文件的工具，通过不向外界发送数据来赢得信任。