内容
# KiCad-MCP
KiCad 原理图和 PCB 布局设计审查的 MCP 服务器。
**版本：** 0.3.0
## 概述
`kicad-mcp` 通过 HTTP 将 KiCad 项目数据暴露给 AI 代理，遵循 [模型上下文协议](https://modelcontextprotocol.io/)。服务器结合了两个数据源：
1. **`kicad-cli`** — ERC、DRC、BOM、网表、板统计和制造导出（Gerber、钻孔、贴装）。
2. **直接 `.kicad_pcb` 解析** — 封装几何、焊盘尺寸、放置坐标、铜区、轨迹、过孔和网路由分析为结构化 JSON。
这让代理可以审查原理图、检查封装图案（例如 QFN 暴露焊盘尺寸）、分析铜浇口，并验证制造输出，而无需手动打开 KiCad。
## 工作流程
典型流程：项目发现 → 原理图审查 → 布局/几何审查 → 制造导出检查。
## 项目布局
```
kicad-mcp/
kicad_mcp/
app.py # MCP 服务器入口（FastMCP + HTTP）
__main__.py # python -m kicad_mcp
config.py # KiCad CLI 路径解析
project.py # .kicad_pro / 文件发现
cli.py # kicad-cli 子进程助手
parsing.py # 网表 / PCB 网名助手
sexpr.py # KiCad S 表达式解析器
pcb_model.py # 封装、几何、区域、路由模型
prompts.py # MCP 审查提示模板
review/
schematic.py # ERC、BOM、网表
layout.py # DRC、板统计、网跟踪摘要
geometry.py # 封装、放置、几何、浇口、路由
manufacturing.py # Gerber、钻孔、位置、IPC-D-356 导出
compare.py # 原理图 vs PCB 网比较
library/
search.py # MCP 组件搜索工具
credentials.py # 分销商 API 密钥 / 令牌存储
models.py # 规范化组件记录
registry.py # 提供商注册（Mouser、DigiKey、...）
providers/
base.py # 提供商接口
mouser.py # Mouser 搜索 API 客户端
digikey.py # DigiKey 产品信息 V4（OAuth2）
ecad/
models.py # ECAD 零件匹配 / 下载模型
samacsys.py # SamacSys 组件搜索引擎客户端
ultralibrarian.py # Ultra Librarian 网络导出客户端
registry.py # ECAD 提供商注册
ecad_tools.py # SamacSys MCP 下载/搜索工具
tests/
test_pcb_model.py # PCB 解析器单元测试
smoke_test.py # KiCad CLI 烟雾测试（无 MCP 服务器）
integration_test.py # MCP 服务器集成测试
img/
kicad-mcp-workflow.png
pyproject.toml
README.md
```
## MCP 工具
### 原理图工具
| 工具 | 描述 |
|------|-------------|
| `get_project_info` | 从 `.kicad_pro` 解析项目文件、网络类和板默认值 |
| `scan_project_structure` | 列出原理图和 PCB 文件 |
| `get_clean_component_list` | 导出 BOM（参考、值、封装） |
| `get_electrical_netlist` | 原理图连接网表（S 表达式） |
| `check_schematic_erc` | 运行电气规则检查（ERC） |
### 布局工具
| 工具 | 描述 |
|------|-------------|
| `check_pcb_drc` | 运行设计规则检查（DRC） |
| `get_board_stats` | 板尺寸、焊盘/过孔计数、铜面积（通过 `kicad-cli`） |
| `list_project_nets` | 所有 PCB 网络，按电源和信号分组 |
| `inspect_net_trace` | 人类可读的网络路由摘要，附 IPC-2152 估计 |
### 几何和封装工具
这些工具返回从 `.kicad_pcb` 解析的**结构化 JSON**。
| 工具 | 参数 | 描述 |
|------|------------|-------------|
| `get_component_footprint` | `project_dir`, `ref` | 焊盘尺寸/形状/层/网络，庭院，制造轮廓，丝印，绝对焊盘中心 |
| `get_component_placement` | `project_dir` | 放置表：ref，value，footprint，side，X/Y，rotation，DNP，bounding box |
| `get_board_geometry` | `project_dir`, `layers?`, `include_graphics?` | Tracks，vias，copper zones，board graphics; 可选层过滤器，例如 `F.Cu,B.Cu` |
| `analyze_copper_pours` | `project_dir` | 区域填充状态，层，网络，hatch，thermal 设置，轮廓，filled islands |
| `analyze_net_routing` | `project_dir`, `net_name` | Segments，vias，zones，pads，connectivity islands，IPC-2152 估计 |
**示例 — QFN MCU 的封装审查：**
```
get_component_footprint(
project_dir: "D:/path/to/project",
ref: "U4"
)
```
返回焊盘尺寸、暴露焊盘（EP）尺寸、庭院多边形和绝对坐标 — 可用于验证封装图案与数据手册建议的一致性。
### 制造工具
导出输出默认到 `<project_dir>/mcp_exports/<category>/`，除非指定 `output_dir`。
| 工具 | 参数 | 描述 |
|------|------------|-------------|
| `export_gerbers` | `project_dir`, `output_dir?`, `layers?` | 生成 Gerber 制造文件 |
| `export_drill_files` | `project_dir`, `output_dir?`, `format?`, `units?` | 生成 Excellon 或 Gerber 钻孔文件 |
| `export_position_file` | `project_dir`, `output_dir?`, `format?`, `side?`, `units?`, `exclude_dnp?` | 贴装 / 重心文件（CSV、ASCII 或 Gerber） |
| `export_ipc_d356` | `project_dir`, `output_dir?` | 用于电气测试的 IPC-D-356 网表 |
| `inspect_manufacturing_exports` | `project_dir`, `output_dir?` | 列出 gerbers、drill、position 和 ipc_d356 文件夹下的文件 |
默认导出布局：
```
<project_dir>/mcp_exports/
gerbers/
drill/
position/
ipc_d356/
```
### 跨领域工具
| 工具 | 描述 |
|------|-------------|
| `compare_sch_pcb_nets` | 比较原理图和 PCB 网络名称；标记仅在原理图或 PCB 上的网络 |
### 组件库工具
搜索分销商目录中的零件（Mouser 和 DigiKey）。
| 工具 | 描述 |
|------|-------------|
| `get_component_provider_status` | 显示 Mouser / DigiKey 提供商的凭证状态 |
| `set_component_provider_credentials` | 设置 Mouser API 密钥或 DigiKey OAuth 客户端凭证；可选持久化到磁盘 |
| `clear_component_provider_credentials` | 清除会话或持久化凭证 |
| `search_components_by_keyword` | 关键字搜索（Mouser 或 DigiKey） |
| `search_components_by_part_number` | 零件编号 / MPN 搜索，附带制造商过滤器 |
**Mouser 设置**
1. 在 [Mouser API Hub](https://api.mouser.com/api/docs/ui/index) （我的账户 → API）注册搜索 API 密钥。
2. 通过环境变量或 MCP 工具配置：
```powershell
$env:MOUSER_API_KEY = "your-search-api-key"
```
或在运行时：
```
set_component_provider_credentials(provider="mouser", api_key="...", persist=false)
```
凭证也可以保存到 `%APPDATA%\kicad-mcp\credentials.json` （Windows）或 `~/.config/kicad-mcp/credentials.json`，当 `persist=true` 时。
**示例 — 关键字搜索**
```
search_components_by_keyword(
keyword: "100nF 0402 X7R capacitor 25V",
provider: "mouser",
records: 10,
search_options: "InStock"
)
```
**示例 — 零件编号查找**
```
search_components_by_part_number(
part_number: "STM32F407VGT6",
provider: "mouser",
match_mode: "Exact"
)
```
**DigiKey 设置**
1. 在 [developer.digikey.com](https://developer.digikey.com/) 创建生产或沙盒应用程序，并订阅 **产品信息 V4**。
2. 配置 OAuth2 客户端凭证：
```powershell
$env:DIGIKEY_CLIENT_ID = "your-client-id"
$env:DIGIKEY_CLIENT_SECRET = "your-client-secret"
# 可选：测试时使用沙盒主机
$env:DIGIKEY_SANDBOX = "true"
```
或在运行时：
```
set_component_provider_credentials(
provider="digikey",
client_id="your-client-id",
client_secret="your-client-secret",
persist=false
)
```
**示例 — DigiKey 零件查找**
```
search_components_by_part_number(
part_number: "MIMX9352CVVXMAB",
provider: "digikey",
manufacturer: "NXP",
match_mode: "Exact"
)
```
返回规范化的 JSON 记录：MPN、分销商 PN、制造商、描述、库存、交货时间、RoHS、价格断点、数据手册 URL。
### ECAD 库工具
使用免费账户凭证从 ECAD 提供商下载 KiCad 符号、封装和 3D 模型。
支持的提供商：
- `samacsys` — [SamacSys 组件搜索引擎](https://componentsearchengine.com/)
- `ultralibrarian` — [Ultra Librarian](https://www.ultralibrarian.com/)
| 工具 | 描述 |
|------|-------------|
| `get_ecad_provider_status` | 显示 SamacSys / Ultra Librarian 凭证状态 |
| `set_ecad_provider_credentials` | 设置提供商用户名/密码；可选持久化到磁盘 |
| `clear_ecad_provider_credentials` | 清除会话或持久化提供商凭证 |
| `search_ecad_components` | 搜索具有可下载 KiCad 库的精确 MPN 匹配 |
| `download_ecad_component_library` | 下载并可选提取 KiCad 库文件 |
| `debug_ultralibrarian_session` | 诊断 Ultra Librarian SSO 连接性和会话 cookie |
**SamacSys 设置**
1. 在 [componentsearchengine.com/register](https://componentsearchengine.com/register) 注册。
2. 配置凭证：
```powershell
$env:SAMACSYS_USERNAME = "your@cse.account"
$env:SAMACSYS_PASSWORD = "your-password"
```
或在运行时：
```
set_ecad_provider_credentials(
provider="samacsys",
username="your@cse.account",
password="your-password",
persist=false
)
```
**示例 — 搜索然后下载**
```
search_ecad_components(query="0201WMF220JTEE", manufacturer="Royalohm")
download_ecad_component_library(
part_number="0201WMF220JTEE",
manufacturer="Royalohm",
output_dir="D:/Workspace/HW/libs/samacsys",
extract=true
)
```
**Ultra Librarian 设置**
1. 在 [ultralibrarian.com](https://www.ultralibrarian.com/) 注册。
2. 安装 Playwright 和 Chromium 浏览器（登录和下载所需）：
```powershell
uv sync --extra playwright
uv run playwright install chromium
```
3. 配置凭证：
```powershell
$env:ULTRALIBRARIAN_USERNAME = "your@ul.account"
$env:ULTRALIBRARIAN_PASSWORD = "your-password"
# 下载可能需要 60–120 秒；增加如果 MCP 调用超时：
$env:KICAD_MCP_ULTRALIBRARIAN_PLAYWRIGHT_TIMEOUT = "300"
```
或在运行时（可选 `persist=true` 保存到 `%APPDATA%\kicad-mcp\credentials.json`）：
```
set_ecad_provider_credentials(
provider="ultralibrarian",
username="your@ul.account",
password="your-password",
persist=false
)
```
Ultra Librarian 使用 **两步 Playwright 流程**（匹配 Ultra Librarian 网页界面）：
1. **SSO 登录** 从首页（`#Email` / `#Password`），保存浏览器会话状态。
2. **认证下载** — 搜索 → 零件详情 → *下载现在* → 展开 KiCAD 折页 → 选择 **KiCad v6+** → 设置导出选项 → 点击 `a#submit-export`。
Ultra Librarian **搜索** 使用匿名 HTTP。**下载和登录** 使用 Playwright 的无头 Chromium。
**示例 — 搜索然后下载**
```
search_ecad_components(
query="STM32F479NIH6",
manufacturer="STMicroelectronics",
provider="ultralibrarian"
)
download_ecad_component_library(
part_number="STM32F479NIH6",
manufacturer="STMicroelectronics",
provider="ultralibrarian",
part_view_url="https://app.ultralibrarian.com/details/...",
extract=true,
overwrite=true
)
```
SamacSys 下载默认到 `%APPDATA%\\kicad-mcp\\samacsys-downloads`。
Ultra Librarian 下载默认到 `%APPDATA%\\kicad-mcp\\ultralibrarian-downloads`。
Ultra Librarian 导出仅支持 **KiCad v6+**，优先使用 **功能** 符号排序（在需要时回落到 **顺序**）和 **公制（毫米）** 封装单位。
当省略 `output_dir` 时，提取的布局为：
```
<output_dir>/<library_name>/
<library_name>.kicad_sym
<library_name>.pretty/*.kicad_mod
<library_name>.3dshapes/*.{stp,wrl}
```
### MCP 提示
| 提示 | 描述 |
|--------|-------------|
| `schematic_review_checklist` | 引导式原理图审查工作流程 |
| `layout_review_checklist` | 引导式布局、几何和制造审查 |
| `full_design_review` | 端到端原理图 + 布局 + 制造就绪审查 |
## 安装
需要 **Python 3.10+** 和 **KiCad 9 或 10**，并在 PATH 上安装 `kicad-cli`（或设置 `KICAD_CLI`）。
**核心服务器**（原理图/PCB 审查 + SamacSys ECAD 搜索/下载）：
```powershell
uv sync
uv run kicad-mcp
```
**完整服务器**（包括 Ultra Librarian Playwright 登录/下载）：
```powershell
uv sync --extra playwright
uv run playwright install chromium
uv run --extra playwright kicad-mcp
```
替代入口点：
```powershell
uv run --extra playwright python -m kicad_mcp
```
停止服务器（Windows PowerShell）：
```powershell
Stop-Process -Id (Get-NetTCPConnection -LocalPort 8500).OwningProcess -Force
```
在升级代码或更改环境变量后重启 MCP 服务器，以便工具处理程序拾取更改。
## 配置
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `KICAD_CLI` | 自动检测 | `kicad-cli` 路径 |
| `KICAD_MCP_HOST` | `127.0.0.1` | HTTP 绑定地址 |
| `KICAD_MCP_PORT` | `8500` | HTTP 端口 |
| `MOUSER_API_KEY` | — | Mouser 搜索 API 密钥（别名：`MOUSER_SEARCH_API_KEY`） |
| `DIGIKEY_CLIENT_ID` | — | DigiKey OAuth2 客户端 ID |
| `DIGIKEY_CLIENT_SECRET` | — | DigiKey OAuth2 客户端密钥 |
| `DIGIKEY_ACCESS_TOKEN` | — | 可选的预先颁发的 DigiKey 承载令牌 |
| `DIGIKEY_SANDBOX` | `false` | 当 `true` 时使用 `sandbox-api.digikey.com` |
| `DIGIKEY_LOCALE_SITE` | `US` | DigiKey 本地站点标头 |
| `DIGIKEY_LOCALE_LANGUAGE` | `en` | DigiKey 本地语言标头 |
| `DIGIKEY_LOCALE_CURRENCY` | `USD` | DigiKey 本地货币标头 |
| `SAMACSYS_USERNAME` | — | 组件搜索引擎登录（别名：`SAMACSYS_CSE_USERNAME`） |
| `SAMACSYS_PASSWORD` | — | 组件搜索引擎密码（别名：`SAMACSYS_CSE_PASSWORD`） |
| `ULTRALIBRARIAN_USERNAME` | — | Ultra Librarian 登录（别名：`UL_USERNAME`） |
| `ULTRALIBRARIAN_PASSWORD` | — | Ultra Librarian 密码（别名：`UL_PASSWORD`） |
| `KICAD_MCP_SAMACSYS_DOWNLOAD_DIR` | OS 默认 | 重写 SamacSys 下载输出目录 |
| `KICAD_MCP_ULTRALIBRARIAN_DOWNLOAD_DIR` | OS 默认 | 重写 Ultra Librarian 下载输出目录 |
| `KICAD_MCP_ULTRALIBRARIAN_PLAYWRIGHT_TIMEOUT` | `240` | Playwright 步骤超时（SSO + 下载），单位：秒 |
| `KICAD_MCP_ULTRALIBRARIAN_PLAYWRIGHT_HEADLESS` | `true` | 设置为 `false` 以在调试时显示浏览器窗口 |
| `KICAD_MCP_CONFIG_DIR` | OS 默认 | 重写凭证/配置目录 |
`kicad-cli` 在 Windows、macOS 和 Linux 上自动检测。KiCad 10 版本仅支持名称的网络（例如，pads 上的 `(net "GND")`），由 PCB 解析器支持。
## 游标 MCP 配置
将以下内容添加到您的 Cursor MCP 设置中：
```json
{
"mcpServers": {
"kicad-hardware-agent": {
"url": "http://localhost:8500/mcp"
}
}
}
```
升级后重启 MCP 服务器，以便新的工具被注册。
## 建议的审查工作流程
1. **发现** — `get_project_info`, `scan_project_structure`
2. **原理图** — `check_schematic_erc`, `get_clean_component_list`, `get_electrical_netlist`
3. **布局检查** — `check_pcb_drc`, `get_board_stats`, `compare_sch_pcb_nets`, `list_project_nets`
4. **几何** — `get_component_footprint`（关键 IC），`get_component_placement`, `get_board_geometry`, `analyze_copper_pours`
5. **网络** — `analyze_net_routing` 或 `inspect_net_trace` 在电源轨和关键接口（GND, VDD, USB, RF, SWD, SPI）
6. **制造** — `export_gerbers`, `export_drill_files`, `export_position_file`, `inspect_manufacturing_exports`
或调用 `full_design_review` MCP 提示以获取引导式检查清单。
## 开发
### 单元测试
```powershell
uv run python -m unittest discover -s tests -v
```
Ultra Librarian 测试（模拟 Playwright；无需浏览器）：
```powershell
uv run --extra playwright python -m unittest tests.test_ultralibrarian -v
```
### KiCad CLI 烟雾测试（无 MCP 服务器）
```powershell
uv run python -u tests/smoke_test.py
```
### MCP 集成测试
启动服务器，通过 MCP 锻炼工具，然后停止：
```powershell
uv run python -u tests/integration_test.py
```
使用特定项目：
```powershell
uv run python -u tests/integration_test.py --project-dir "D:\path\to\project" --port 8500
```
## 许可证
查看存储库许可证文件（如果存在）。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器