STARWARCLOUD STARWAR.AI
返回市场
MCP-KiCad天绘

MCP-KiCad天绘

作者：Pablomonte2 星标更新：2025-11-08
安装使用来源：spider==github.com

项目介绍

KiCad MCP 集成

MIT 许可证 Python 3.10+ KiCad 9.0+ 版本 测试 代码风格：black

使用模型上下文协议（MCP）和 Anthropic Claude 进行基于人工智能的 KiCad PCB 设计。

概述

该项目提供了一个 MCP 服务器，该服务器将 KiCad PCB 设计工具暴露给 AI 助手，使您能够以自然语言与您的 PCB 设计进行交互。您可以要求 AI 放置组件、读取网络列表并获得布局建议。

特性

  • 自然语言 PCB 设计：使用纯英文与 KiCad 交互
  • 组件放置：要求 AI 在特定坐标处放置组件
  • 板分析：查询组件列表、网络列表和板信息
  • 布局指导：获得常见电路类型的 AI 布局建议
  • 实时更新：更改会立即反映在 KiCad 中

架构

┌─────────────┐         ┌─────────────┐         ┌──────────┐
│   您       │ ───────▶│  AI 客户端  │ ───────▶│  Claude  │
│  （用户）     │  聊天   │  （Python）   │   API   │   AI     │
└─────────────┘         └─────────────┘         └──────────┘
                              │
                              │ MCP 协议
                              ▼
                        ┌─────────────┐         └──────────┘
                        │ MCP 服务器  │ ───────▶│  KiCad   │
                        │  （Python）   │ pcbnew  │ PCBNew   │
                        └─────────────┘         └──────────┘

先决条件

  1. KiCad 9.0+（推荐使用 Flatpak 安装）
  2. Python 3.10+
  3. Anthropic API 密钥（或用于 Grok 的 xAI API 密钥）

安装

方法 1：Flatpak（推荐）

适用于 KiCad 9.0+ Flatpak 安装。这是经过测试并推荐的方法。

步骤 1：克隆仓库

cd ~/repos
git clone https://github.com/Pablomonte/MCP-KiCad.git
cd MCP-KiCad

步骤 2：安装 KiCad Flatpak

flatpak install flathub org.kicad.KiCad

步骤 3：在 Flatpak 中安装依赖项

./kicad_flatpak_setup.sh

此脚本会自动在 KiCad Flatpak 容器内安装所需的 Python 包（mcp、anthropic、python-dotenv）。

步骤 4：配置 API 密钥

cp .env.example .env
nano .env  # 或您喜欢的编辑器

添加您的 Anthropic API 密钥：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx

从 https://console.anthropic.com/ 获取您的 API 密钥。

步骤 5：准备就绪！

运行服务器：

./run_with_flatpak.sh  # 默认使用扩展服务器（12 个工具）

方法 2：本地 Python（高级）

适用于原生 KiCad 安装或开发目的。

步骤 1-3：同 Flatpak 方法

克隆仓库并配置 API 密钥。

步骤 4：创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # 在 Linux/Mac 上
# 或
venv\Scripts\activate  # 在 Windows 上

步骤 5：安装依赖项

pip install -r requirements.txt

步骤 6：设置 KiCad Python 环境

MCP 服务器需要访问 KiCad 的 pcbnew 模块。

选项 A：使用 KiCad 的 Python

找到并使用 KiCad 的 Python 安装：

# Linux
/usr/lib/kicad/bin/python3 kicad_mcp_server_extended.py

# Mac
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 kicad_mcp_server_extended.py

# Windows
"C:\Program Files\KiCad\9.0\bin\python.exe" kicad_mcp_server_extended.py

选项 B：链接 pcbnew 到虚拟环境

# Linux 示例
ln -s /usr/lib/python3/dist-packages/pcbnew.py venv/lib/python3.*/site-packages/
ln -s /usr/lib/python3/dist-packages/_pcbnew.so venv/lib/python3.*/site-packages/

注意：确切路径因系统而异。检查您的 KiCad 安装目录。

使用

1. 打开 KiCad PCBNew

首先，在 KiCad PCBNew 中打开您的 PCB 项目：

kicad path/to/your/project.kicad_pcb

确保 PCB 编辑器（PCBNew）是打开的，而不仅仅是项目管理器。

2. 运行 MCP 服务器

选择基本服务器（4 个工具）或扩展服务器（12 个工具，推荐）：

使用 Flatpak（推荐）：

# 扩展服务器 - 推荐（包括制造工具）
./run_with_flatpak.sh

# 只有基本服务器
./run_with_flatpak.sh kicad_mcp_server.py

使用本地 Python：

# 如果使用虚拟环境
source venv/bin/activate
python kicad_mcp_server_extended.py  # 或 kicad_mcp_server.py 用于基本

# 或使用 KiCad 的 Python
/usr/lib/kicad/bin/python3 kicad_mcp_server_extended.py

服务器将连接到当前打开的 KiCad 板，并等待 MCP 请求。

注意：如果 pcbnew 不可用，服务器将以“模拟模式”运行以供测试。

3. 运行客户端

在另一个终端（激活虚拟环境）中：

python kicad_mcp_client.py kicad_mcp_server.py

您应该看到：

已连接到 KiCad MCP 服务器
可用工具：place_component, read_netlist, list_components, get_board_info

======================================================================
KiCad AI 助手
======================================================================

您可以问我帮助您设计 PCB！
...

您：

4. 与您的板互动

尝试这些示例查询：

基本操作：

您：列出板上的所有组件
您：将 R1 放置在 10, 20 毫米的位置
您：将电容器 C1 移动到 15, 25 毫米的位置并旋转 90 度
您：显示网络列表
您：板尺寸是多少？
您：为 LED 电路提供布局建议

制造操作（扩展服务器）：

您：将 Gerber 文件导出到 ./gerber
您：生成 Excellon 格式的钻孔文件
您：为 JLCPCB 创建完整的制造包
您：导出物料清单（BOM）
您：生成拾放位置文件
您：运行设计规则检查
您：填充所有铜区

AI 将：

  1. 理解您的自然语言请求
  2. 通过 MCP 调用适当的 KiCad 工具
  3. 在您的 PCB 上执行更改或导出
  4. 提供已完成工作的反馈

5. 在 KiCad 中验证更改

AI 进行更改后，请刷新 KiCad 视图以查看更新：

  • 点击 PCB 画布
  • 按 F5 或使用视图 → 刷新

可用工具

该项目包含两个 MCP 服务器变体：

服务器比较

功能基本服务器扩展服务器
脚本kicad_mcp_server.pykicad_mcp_server_extended.py
工具数量4 个工具12 个工具
使用场景组件放置及查询完整制造工作流
推荐测试及学习生产用途

基本服务器工具（4 个工具）

两个服务器都包含这些基本工具：

place_component

将组件移动到 PCB 上的特定位置。

参数：

  • reference（字符串）：组件参考（例如，“R1”，“U1”）
  • x_mm（数字）：毫米单位的 X 位置
  • y_mm（数字）：毫米单位的 Y 位置
  • rotation_deg（数字，可选）：旋转角度（度）

list_components

列出 PCB 上的所有组件及其当前位置。

返回值：包含参考、值、位置、旋转和层的 JSON 组件数组

read_netlist

从板上读取网络列表信息。

返回值：包含名称和网络代码的 JSON 网络数组

get_board_info

获取有关 PCB 的一般信息。

返回值：板尺寸、层数、组件数、文件名

扩展服务器附加工具（8 个更多工具）

扩展服务器增加了这些制造和验证工具：

制造工具（5 个工具）

export_gerber

导出 Gerber 文件（RS-274X 格式）用于 PCB 制造。

参数：

  • output_dir（字符串）：输出目录路径
  • layers（数组，可选）：要导出的具体层

返回值：生成的 Gerber 文件列表

export_drill_files

导出 Excellon 格式的钻孔文件。

参数：

  • output_dir（字符串）：输出目录路径
  • merge_pth_npth（布尔值，可选）：合并 PTH 和 NPTH 至一个文件

返回值：生成的钻孔文件路径

export_fabrication_package

创建一个完整的制造包作为 ZIP 文件。

参数：

  • output_path（字符串）：ZIP 文件输出路径

返回值：包路径和包含文件列表

export_bom

导出物料清单（CSV 格式）。

参数：

  • output_path（字符串）：CSV 文件输出路径
  • include_dnp（布尔值，可选）：包含“不安装”组件

返回值：BOM 文件路径和组件数量

export_position_file

导出用于拾放机器的组件位置。

参数：

  • output_path（字符串）：CSV 文件输出路径
  • side（字符串，可选）：“front”、“back”或“both”

返回值：位置文件路径和组件数量

验证工具（1 个工具）

run_drc

对 PCB 运行设计规则检查。

参数：

  • report_path（字符串，可选）：DRC 报告路径

返回值：DRC 状态、错误数量、警告数量

布局工具（2 个工具）

fill_zones

填充 PCB 上的铜区。

参数：

  • zone_names（数组，可选）：要填充的具体区域（默认：全部）

返回值：填充的区域数量

get_track_info

获取关于 PCB 上的走线/轨迹的信息。

参数：

  • net_name（字符串，可选）：按网络名称过滤

返回值：走线数量、总长度、层分布

可用资源

board://schematic

来自板原理图的 JSON 组件列表

board://info

通用 PCB 板信息和设置

可用提示

simple_circuit

获得简单电路的 AI 布局指导。

参数：

  • type（字符串）：电路类型 - “LED”、“电源供应”、“放大器”等

返回值：指定电路类型的布局指南和最佳实践

项目结构

MCP-KiCad/
├── kicad_mcp_server.py      # 暴露 KiCad 工具的 MCP 服务器
├── kicad_mcp_client.py      # 使用 Claude 的 AI 客户端
├── requirements.txt          # Python 依赖项
├── .env.example             # 示例环境配置
├── .env                     # 您的 API 密钥（不在 git 中）
├── .gitignore              # Git 忽略规则
└── README.md               # 本文档

已知限制

KiCad 9.x API 兼容性

过孔宽度 API 更改：

  • get_track_info 可能返回 None 对于具有过孔的板上的 total_length_mm
  • 由 KiCad 9.x 更改 PCB_VIA::GetWidth() 方法签名引起
  • 影响：过孔长度计算可能不可用
  • 解决方法：其他所有功能正常工作，制造导出不受影响

可选字段：

  • 根据板配置，某些 get_board_info 字段可能会返回 None
  • 服务器优雅地处理 None 值

测试状态：

  • 已验证与 KiCad 9.0.5 Flatpak 在真实板上工作
  • 测试板：Olivia Control v0.2（51 个组件，2 层，56 个网络，38 个过孔）
  • 尽管有 API 警告，所有 12 个工具均功能正常

详细信息见 [FABRICATION.md](FABRICATION.md#via-width-api-change-kicad- 9x)。

故障排除

"pcbnew 模块不可用"

服务器将以模拟模式运行。要修复：

  • 确保已安装 KiCad
  • 使用 KiCad 的 Python 解释器（参见安装步骤 5）
  • 或将 pcbnew 链接到您的虚拟环境

"当前没有在 KiCad 中打开 PCB 板"

  • 在运行服务器之前，在 KiCad PCBNew 中打开一个 PCB 文件
  • 确保您在 PCB 编辑器中，而不仅仅是项目管理器

"未找到 ANTHROPIC_API_KEY"

  • 从 .env.example 创建 .env 文件
  • 添加您的 API 密钥：ANTHROPIC_API_KEY=sk-ant-...
  • 确保 .env 与脚本在同一目录中

组件未找到错误

  • 首先列出所有组件："列出所有组件"
  • 使用精确的参考设计符（区分大小写）
  • 确保组件在 PCB 上（而不仅仅是原理图）

更改未出现在 KiCad 中

  • 在 KiCad 中刷新视图（F5）
  • 检查控制台中的错误消息
  • 验证服务器正在运行并已连接

KiCad 9.x 过孔宽度警告

症状：

/run/build/kicad/pcbnew/pcb_track.cpp(381): assert "false" failed in GetWidth()

解释：

  • 当处理具有过孔的板时，在 KiCad 9.x 上出现这些警告是预期的
  • 由 PCB_VIA::GetWidth() 方法签名的 API 更改引起
  • 警告在 get_track_info 操作期间出现

影响：

  • ⚠️ get_track_info 可能返回 None 对于 total_length_mm
  • ✅ 所有其他工具正常工作
  • ✅ 制造导出（Gerber、钻孔、BOM）不受影响
  • ✅ 组件操作正常

解决方法：

  • 无需采取行动 - 这是在 KiCad 9.x 上的正常行为
  • 如果需要总走线长度，请使用外部工具如 KiCad 内置的走线长度测量工具
  • 服务器优雅地处理这些警告并继续运行

测试： 成功测试了 Olivia Control v0.2 板（38 个过孔） - 所有 12 个工具功能正常。

详细信息见 FABRICATION.md。

高级用法

使用 xAI Grok（Claude 的替代品）

要使用 Grok 而不是 Claude：

  1. 从 https://x.ai/ 获取 xAI API 密钥
  2. 修改 kicad_mcp_client.py：
# 用 xAI 客户端替换 Anthropic 客户端
from openai import OpenAI  # xAI 使用 OpenAI 兼容 API

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)
  1. 更新 API 调用以使用 xAI 的模型名称（例如，“grok-beta”）

单独运行服务器

任何 MCP 兼容客户端都可以使用 MCP 服务器：

python kicad_mcp_server.py

然后使用 stdio 传输连接到任何 MCP 客户端。

扩展更多工具

通过以下方式添加新工具：

  1. 在 list_tools() 处理程序中定义工具
  2. 实现工具函数（例如，`_route