schematic-mcp

通过 MCP 为 AI 智能体提供硬件原理图上下文。

schematic-mcp 让兼容 MCP 的智能体把硬件原理图当作结构化电气数据来检查，而不是把它当作截图或大段文本。

状态：V0.1 / alpha。首个适配器面向现代 KiCad .kicad_sch 文件。

为什么会有它

编写固件的 AI 编程智能体常常需要回答这类问题：

• 哪个 ESP32 引脚连接到了 SENSOR_OUT？

• U4.GPIO12 上连接了什么？

• 哪些器件共享这条 I2C 网络？

• MCU 上有哪些引脚以及已解析出的网络？

• 固件假定的 GPIO 映射是否真的与原理图吻合？

服务器以确定性方式解析 EDA 文件，构建规范的元件/引脚/网络模型，并通过 MCP 工具和资源暴露该模型。

设计原则是保守的：当连线关系无法有把握地解析时，宁可显示警告，也不要编造一条电气连接。

设计重点

schematic-mcp 刻意定位为文件驱动的硬件上下文层，而不是通用的 EDA GUI 自动化服务器。常规 KiCad 读取/查询流程不需要运行中的 KiCad 进程。各 EDA 专属适配器产出规范的电气图，而面向智能体的 MCP 契约始终保持格式中立。

这也使项目与编辑器/IPC 自动化形成互补：编辑器工具对交互式设计修改很有价值，而 schematic-mcp 专注于可被编程智能体、CI 系统和未来跨 EDA 适配器消费的确定性硬件事实。固件 ↔ 原理图验证是第一个落地场景。

项目边界和生态论证见 docs/project-positioning.md。

Related MCP server: mcp-kicad-sch-api

V0.1 特性

• 解析最新 KiCad .kicad_sch S 表达式文件

• 读取元件、位号、值和库 ID

• 将库引脚几何解析为原理图坐标

• 为多单元符号按当前激活单元选择引脚

• 根据导线、标签和连接点构建连通关系

• 解析命名网络和匿名网络

• 检查单个元件或引脚

• 将一个引脚追踪到同一电气网络上的所有端点

• 生成紧凑的 MCU 引脚映射

• 按物理引脚号或符号引脚名将固件引脚预期与实际网络比对

• 把当前规范模型暴露为 MCP 资源

• 使用 SCHEMATIC_MCP_ROOT 或 --root 限制文件系统访问

• 通过 stdio 或 Streamable HTTP 本地运行

• 在 GitHub Actions 中自动执行解析器、图谱和文件系统边界测试

MCP 工具

资源：

• schematic://current/summary

• schematic://current/model

从 GitHub 安装

需要 Python 3.10 以上。在软件包生态首次运行之前，可以直接从 GitHub 安装当前的 main 分支：

python -m pip install "git+https://github.com/vonpanda/schematic-mcp.git"
schematic-mcp --help

用于可靠的生产环境时，推荐锁顶一个 release tag 或 commit，而不是跟随未固定的开发分支。首个打包发布版本跟踪见 issue #8。

开发安装

git clone https://github.com/vonpanda/schematic-mcp.git
cd schematic-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

本项目使用官方 MCP Python SDK 的稳定 v2 系。

运行

本地 stdio

schematic-mcp

或者：

python -m schematic_mcp

不设置环境变量也能限制可读文件：

schematic-mcp --root /absolute/path/to/your/hardware-projects

尝试内置 fixture

仓库内含一个很小的合成 KiCad 原理图，适合演示和测试：

schematic-mcp --root "$PWD/examples"

然后 MCP 兼容客户端可以调用：

open_schematic("minimal.kicad_sch")
schematic_summary()
list_components()
trace_signal("U1", "1")

该示例应当把 U1.1 解析到 SENSOR_OUT，并将 U2.1 显示为另一个端点。参见 examples/README.md。

固件 ↔ 原理图验证演示

第二个合成示例演示了一个仅靠源码无法让智能体安全发现的硬件缺陷：固件刻意交换了 SENSOR_INT 与 LED_STATUS 的 GPIO 分配，而原理图保留了正确的电气映射。

运行确定性本地演示：

python examples/demo_firmware_validation.py

它会从 examples/firmware_with_pin_bug.c 中提取简洁的 GPIO 契约，解析 examples/esp32_firmware_validation.kicad_sch，并报告两处匹配与两处不匹配。

通过 MCP 执行同样的对比：

通过 MCP 执行同样的对比： GXP9

完整智能体工作流与预期结果见 docs/firmware-validation-demo.md。

Streamable HTTP

schematic-mcp --transport streamable-http --host 127.0.0.1 --port 8000

MCP 端点为 http://127.0.0.1:8000/mcp。默认只监听 loopback，不要把未鉴权的开发服务器直接暴露到公网。

在 MCP Inspector 中运行：

mcp dev src/schematic_mcp/server.py

MCP 客户端配置示例

{
  "mcpServers": {
    "schematic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/schematic-mcp", "run", "schematic-mcp"],
      "env": {"SCHEMATIC_MCP_ROOT": "/absolute/path/to/your/hardware-projects"}
    }
  }
}

然后第二个客户端可以调用：

open_schematic("board/main.kicad_sch")
get_component("U4")
get_mcu_pinmap("U4")
trace_signal("U4", "12")

文件系统安全

默认情况下，本地服务器可以打开其进程可访问的路径。对于你不完全信任的智能体，应通过 SCHEMATIC_MCP_ROOT 或 --root 限制在一个允许的项目目录内。凡尝试打开该目录之外的文件都会被拒绝，即使通过路径绕过也会被拦截。

漏洞报告与部署建议请参见 SECURITY.md。

当前限制

V0.1 明显还比较小。虽然能识别层次子图纸，但还没有把多 sheet 图递归合并成一张整图。不常见的多单元/库结构，以及第三方 KiCad 导出文件，仍需要更广泛的兼容性测试夹具。总线语义也尚未被重建。PDF、Altium 和 EasyEDA 也还没有实现。

trace_signal 只能沿已解析出的网络连接追踪，不虚拟同一芯片封装内部多个引脚直接切片连接；validate_pinmap 仅对比显式给出的预期映射，自动从任意固件框架提取 GPIO 结构不属于当前解析器范围。

路线图

• V0.2 — 层级化 KiCad 工程与更丰富的总线/网络语义

• V0.3 — 带可信度元数据的 PDF/矢量原理图适配器

• V0.4 — Altium 和 EasyEDA 适配器

• V0.5 — 数据手册上下文与电气规则推理

• V0.6 — 面向各框架的固件 GPIO 提取（ESP-IDF/Arduino/Zephyr）与 CI 引脚契约检查

• 以后 — PCB、BOM、Gerber 和制造上下文

长期目标是打造一个厂商无关的面向 AI 智能体的硬件上下文服务器。

贡献

硬件工程师、嵌入式开发人员和 EDA 用户都可以从以下方面入手：补充最小化兼容性 fixture、解析器边界用例、测试和真实智能体工作流。

先浏览 CONTRIBUTING.md。编程智能体和维护者还应阅读 AGENTS.md，了解架构不变量、安全约束和预期的自主迭代方式。请不要为项目贡献客户专有原理图，除非你有明确授权。

有用的维护/项目文档：

• AGENTS.md — 智能体与维护者规范

• docs/project-positioning.md — 项目边界与生态价值

• docs/architecture.md — 解析器/模型/MCP 三者的工程方案

• docs/firmware-validation-demo.md — 固件与原理图不匹配演示

• examples/README.md — 可编辑的合成样例

• CHANGELOG.md — 发布历史

• SECURITY.md — 安全策略

• docs/oss-readiness.md — 开源就绪度自查清单

许可证与版权声明

以 Apache License 2.0 许可发布。在许可条款允许下，可商业使用、修改和再分发；再分发必须保留适用的版权、许可证与 NOTICE 信息，具体要求遵循 Apache-2.0。

见 LICENSE 与 NOTICE。

最初在 SYANKOR 内部开发。