Codex 接入 KiCad 配置实录：用 kicad-mcp 连接原理图与 PCB 编辑器

最近在研究让 AI 直接参与 EDA 工作流。比起让模型生成一段 .kicad_sch 文本再手工导入，我更关心的是另一条链路：让 Codex 通过 MCP 调用工具，并把操作实时发送给正在运行的 KiCad。

本文参考了 CSDN 文章《用 AI 接入 KiCad 实时画原理图/PCB：完整教程（Codex + kicad-mcp）》，但配置部分按当前 Codex 的官方 MCP 格式重新整理，并结合 Huaqiu-Electronics/kicad-mcp 仓库与 KiCad IPC 文档核对。示例以 Windows 为主，路径尽量使用 %USERPROFILE%、<项目目录> 这类可以直接理解和替换的写法。

说明：这是一篇配置与连通性验证记录，不代表 AI 生成的原理图或 PCB 已通过 ERC、DRC、SI/PI、热设计和实物测试。正式设计中，AI 的每次修改仍应经过人工复核，并优先在测试工程或版本控制下操作。

一、先弄清接入链路

整个链路可以简化为：

Codex（MCP 客户端）
        │  STDIO / JSON-RPC
        ▼
kicad-mcp（本地 Python 进程）
        │  本地 IPC
        ▼
正在运行的 KiCad 原理图或 PCB 编辑器

这里有三个容易混淆的点：

Codex 不直接控制鼠标，也不是先把整个工程作为附件上传后再改文件；它调用的是本机 MCP 服务器暴露的工具。不过，工具返回给模型的器件、网络或文档信息仍可能进入所用 AI 服务的上下文，涉密工程应先核对数据策略和工具权限。
kicad-mcp 不是 KiCad 本体，而是把 MCP 工具调用翻译为 KiCad 侧可理解的请求。
KiCad 9/10 的 IPC API 面向正在运行的 GUI 实例，所以目标编辑器必须先打开。KiCad 官方文档也明确说明了这一限制。

Huaqiu-Electronics/kicad-mcp 会寻找本机的 kicad.exe、eeschema.exe 或 pcbnew.exe 进程，并根据进程号和编辑器类型构造连接地址。因此，启动顺序不是可有可无的细节。

还要注意一个兼容性边界：该仓库当前代码使用的是形如 ipc://kicad_sdk_pair-{pid}-{editor} 的项目特定连接地址，而 KiCad 官方 IPC 文档描述的是 api.sock / Windows 命名管道机制。两者不能简单视为完全相同的实现。参考文章记录了 KiCad 10.0.2 的可用案例，但第三方项目与 KiCad 版本仍应配套验证；如果原版 KiCad 无法连接，先查仓库的最新 README、Issue 和目标版本，不要只靠反复修改 Codex 配置。

二、准备环境

1. KiCad

建议使用当前维护中的 KiCad 10.x 稳定版，并及时更新到该大版本的最新修订版。本文参考资料使用的是 KiCad 10 系列。

安装完成后：

打开 KiCad 工程；
进入原理图编辑器或 PCB 编辑器；
在编辑器首选项中找到 Scripting /“脚本”相关设置，确认 Enable IPC API 已启用；
保持需要操作的编辑器窗口和目标工程处于打开状态。

不同 KiCad 修订版的菜单文字可能略有差异。如果 MCP 能启动但所有工具都连接失败，IPC 开关和目标编辑器是否已经打开应是第一检查项。

2. Python 与 uv

仓库当前声明需要 Python 3.11 或更高版本，并推荐用 uvx 在隔离环境中直接运行 PyPI 包。这样不必把 kicad-mcp 永久安装到系统 Python。

Windows 可以用 WinGet 安装 uv：

winget install --id=astral-sh.uv -e

也可以使用 Astral 官方安装脚本，但执行网络脚本前应先阅读脚本内容：

powershell -c "irm https://astral.sh/uv/install.ps1 | more"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后重新打开终端并检查：

uv --version
uvx --help

如果 uvx 找不到，先不要改 Codex 配置，优先解决 PATH 问题。

三、先在命令行确认 kicad-mcp 能启动

原理图模式：

uvx kicad-mcp --editor-type schematic

PCB 模式：

uvx kicad-mcp --editor-type pcb

第一次运行时，uvx 会下载包并创建隔离环境，等待时间通常比后续启动更长。该命令会启动一个以 STDIO 通信的 MCP 服务器，因此在普通终端中看起来像“停在那里”等待输入并不一定是故障；测试后可用 Ctrl+C 结束。

仓库还支持 symbol 和 footprint 两种 --editor-type，但初次配置建议先只连接最常用的 schematic 或 pcb，确认链路后再扩展。

四、配置 Codex

Codex 官方文档说明，用户级 MCP 配置默认位于：

%USERPROFILE%\.codex\config.toml

也可以在受信任项目中使用项目级配置：

<项目目录>\.codex\config.toml

如果只希望 KiCad 工具在某个硬件项目中出现，项目级配置更整洁；如果希望所有项目都能使用，放到用户级配置即可。

方案 A：先只配置原理图

在 config.toml 中加入：

[mcp_servers.kicad-schematic]
enabled = true
command = "uvx"
args = ["kicad-mcp", "--editor-type", "schematic"]
startup_timeout_sec = 120
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

这里将启动超时设为 120 秒，是为了给 uvx 首次下载和初始化留出余量。default_tools_approval_mode = "prompt" 则让工具调用默认需要确认，适合刚接入时观察每一步修改。

方案 B：同时配置原理图与 PCB

在原理图配置后继续添加：

[mcp_servers.kicad-pcb]
enabled = true
command = "uvx"
args = ["kicad-mcp", "--editor-type", "pcb"]
startup_timeout_sec = 120
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

两个服务是两个独立进程。只做原理图时，可以临时把 PCB 服务设为：

enabled = false

这样可减少无关工具，也避免 PCB 编辑器未打开时出现连接日志。

也可以用 Codex CLI 添加

Codex 官方还提供 codex mcp add：

codex mcp add kicad-schematic -- uvx kicad-mcp --editor-type schematic
codex mcp add kicad-pcb -- uvx kicad-mcp --editor-type pcb

随后检查：

codex mcp list

CLI 方式适合快速添加；如果要设置超时、启用状态和工具审批策略，直接查看并维护 config.toml 会更清晰。

五、正确的启动顺序

推荐固定为下面的顺序：

打开 KiCad 工程；
打开需要控制的原理图编辑器或 PCB 编辑器；
确认 IPC API 已启用；
再启动或重启 Codex；
在 Codex 中查看 MCP 服务器与工具列表。

不要在 KiCad 还没打开时反复重启 MCP。kicad-mcp 的代码会先等待 KiCad 进程，找不到时记录 KiCad not found；即使 MCP 进程继续存在，后续工具也可能因为客户端没有初始化而失败。

如果先开了 Codex、后开 KiCad，最省事的处理通常是保持 KiCad 编辑器打开，然后重启 Codex 或重启对应的 MCP 服务器。

六、从只读查询开始验证

连接建立后，不要一上来就让 AI 自动布板。先让 Codex 执行一个不会修改工程的查询，例如：

请只调用 KiCad MCP 的 queryCurrentFrameType，
不要修改、保存或关闭任何 KiCad 文档，并告诉我返回的 frame_type。

预期结果通常为：

原理图编辑器：FRAME_SCH
PCB 编辑器：FRAME_PCB_EDITOR

只读查询成功后，再做一个可撤销的小操作，例如缩放视图；确认工具目标与当前文档一致后，才逐步尝试放置符号、连线或保存。

建议第一次测试使用空白工程或工程副本，并在每一步后检查：

当前活动窗口是不是预期的编辑器；
坐标和单位是不是合理；
修改对象数量是否符合预期；
ERC / DRC 是否引入新问题；
保存前是否已经建立 Git 提交或其他可恢复快照。

七、常见问题

1. Codex 中看不到 KiCad MCP

依次检查：

codex mcp list
uv --version
uvx --help

然后检查 config.toml 是否为合法 TOML、表名是否写成 [mcp_servers.<名称>]，最后重启 Codex。Codex CLI、IDE 扩展和同一主机上的桌面客户端共享该 MCP 配置。

2. 日志出现 `KiCad not found`

这表示 MCP 启动时没有找到 KiCad 进程。请先打开目标工程和对应编辑器，再重启 MCP/Codex。只打开 KiCad 项目管理器、没有进入原理图或 PCB 编辑器时，也可能无法建立目标连接。

3. 工具存在，但调用时提示客户端未初始化

这通常不是“工具没注册”，而是 MCP 已经启动、KiCad IPC 连接却没有建立。重点检查 IPC 开关、编辑器类型、启动顺序以及是否同时开了多个 KiCad 实例。

4. 第一次启动超时

uvx 首次需要下载依赖。可以先在终端运行一次相同命令完成缓存，或适当增大：

startup_timeout_sec = 180

5. 同时打开多个 KiCad 实例后连错工程

仓库会扫描 KiCad 相关进程。多实例会让“应该连接哪一个”变得不明确。初次验证时只保留一个 KiCad 工程和一个目标编辑器窗口，确认稳定后再考虑多实例工作流。

6. `queryCurrentFrameType` 成功，但复杂绘图不可靠

连通成功只说明通信链路成立，不说明所有高层任务都能一次完成。复杂电路应拆成小步骤：放置少量符号、核对封装与引脚、分段连线、运行 ERC/DRC，再继续下一部分。大量重复单元可以考虑脚本化生成，但必须用 kicad-cli 和人工检查验证结果。

八、我更推荐的使用边界

把 Codex + KiCad MCP 当成“可审查的工程助手”，而不是自动交付 PCB 的黑盒：

读取优先：先查询当前文档、器件和网络，再允许修改；
小步修改：每次只做一个容易验证、容易撤销的动作；
先副本后原件：初次测试不要直接操作唯一工程；
规则工具兜底：ERC、DRC、网表和制造输出检查不能省；
人对最终结果负责：封装、极性、电气额定值、走线电流、间距和生产文件都要人工签字式复核。

九、参考资料

参考文章：用 AI 接入 KiCad 实时画原理图/PCB：完整教程（Codex + kicad-mcp）
MCP 项目：Huaqiu-Electronics/kicad-mcp
Codex 官方文档：Model Context Protocol
KiCad 开发者文档：IPC API for Add-on Developers
uv 官方文档：Installing uv
KiCad 官方下载页：Download KiCad

AIGC 说明：本文由 AI 协助检索、整理和撰写，配置结构于 2026-10-24 对照 Codex、KiCad、uv 官方资料及 kicad-mcp 仓库核对。第三方 MCP 项目仍可能更新，实际使用时请以仓库最新 README、发布版本和本机运行结果为准。

posted @ 2026-10-24 21:00 s-taRsea 阅读(145) 评论(0) 收藏举报

刷新页面返回顶部

Codex 接入 KiCad 配置实录：用 kicad-mcp 连接原理图与 PCB 编辑器

Codex 接入 KiCad 配置实录：用 kicad-mcp 连接原理图与 PCB 编辑器

一、先弄清接入链路

二、准备环境

1. KiCad

2. Python 与 uv

三、先在命令行确认 kicad-mcp 能启动

四、配置 Codex

方案 A：先只配置原理图

方案 B：同时配置原理图与 PCB

也可以用 Codex CLI 添加

五、正确的启动顺序

六、从只读查询开始验证

七、常见问题

1. Codex 中看不到 KiCad MCP

2. 日志出现 KiCad not found

3. 工具存在，但调用时提示客户端未初始化

4. 第一次启动超时

5. 同时打开多个 KiCad 实例后连错工程

6. queryCurrentFrameType 成功，但复杂绘图不可靠

八、我更推荐的使用边界

九、参考资料

公告

2. 日志出现 `KiCad not found`

6. `queryCurrentFrameType` 成功，但复杂绘图不可靠