KiCad MCP集成

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.10+](https://www.python.org/downloads/) ![KiCad 9.0+](https://www.kicad.org/) ](https://github.com/Pablomonte/MCP-KiCad/releases/tag/v1.0.0) ![Tests](#testing) ![Code style: black](https://github.com/psf/black)

人工智能使用模型上下文协议（MCP）和拟人克劳德辅助KiCad PCB设计。

概述

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

特性

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

建筑

┌─────────────┐         ┌─────────────┐         ┌──────────┐
│   You       │ ───────▶│  AI Client  │ ───────▶│  Claude  │
│  (User)     │  Chat   │  (Python)   │   API   │   AI     │
└─────────────┘         └─────────────┘         └──────────┘
                              │
                              │ MCP Protocol
                              ▼
                        ┌─────────────┐         ┌──────────┐
                        │ MCP Server  │ ───────▶│  KiCad   │
                        │  (Python)   │ pcbnew  │ PCBNew   │
                        └─────────────┘         └──────────┘

先决条件

KICAD 9.0+ （建议安装Flatpak）
Python 3.10+
无烟煤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

第二步：安装KiCad Flatpak

flatpak install flathub org.kicad.KiCad

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

./kicad_flatpak_setup.sh

此脚本会自动安装所需的Python包(mcp, anthropic, python-dotenv)KiCad Flatpak容器内。

步骤4：配置API密钥

cp .env.example .env
nano .env  # or your preferred editor

添加您的Anthropic API密钥：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx

从以下位置获取API密钥：https://console.anthropic.com/

第五步：你准备好了！

使用以下命令运行服务器：

./run_with_flatpak.sh  # Uses extended server (12 tools) by default

方法2：原生Python（高级）

用于KiCad本地安装或开发目的。

步骤1-3：与Flatpak方法相同

克隆存储库并配置API密钥。

步骤4：创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate  # On 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 example
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（推荐）：

# Extended server - recommended (includes fabrication tools)
./run_with_flatpak.sh

# Basic server only
./run_with_flatpak.sh kicad_mcp_server.py

使用原生Python：

# If using virtual environment
source venv/bin/activate
python kicad_mcp_server_extended.py  # or kicad_mcp_server.py for basic

# Or with KiCad's Python
/usr/lib/kicad/bin/python3 kicad_mcp_server_extended.py

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

备注：如果pcbnew不可用，服务器将在 模拟模式 用于测试。

3.运行客户端

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

python kicad_mcp_client.py kicad_mcp_server.py

您应该看到：

Connected to KiCad MCP Server
Available tools: place_component, read_netlist, list_components, get_board_info

======================================================================
KiCad AI Assistant
======================================================================

You can ask me to help with your PCB design!
...

You:

4.与董事会互动

尝试以下示例查询：

基本操作：

You: List all components on the board
You: Place R1 at position 10, 20 mm
You: Move capacitor C1 to 15, 25 mm with 90 degree rotation
You: Show me the netlist
You: What's the board size?
You: Give me layout suggestions for an LED circuit

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

You: Export Gerber files to ./gerber
You: Generate drill files in Excellon format
You: Create a complete fabrication package for JLCPCB
You: Export the Bill of Materials (BOM)
You: Generate pick-and-place position file
You: Run Design Rule Check
You: Fill all copper zones

AI将：

了解您的自然语言要求
通过MCP调用相应的KiCad工具
在PCB上执行更改或导出
提供对所做工作的反馈

5.验证KiCad中的更改

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

点击PCB画布
按 F5 或使用View→ 刷新

可用工具

该项目包括两种MCP服务器变体：

服务器比较

功能	基本服务器	扩展服务器
脚本	`kicad_mcp_server.py`	`kicad_mcp_server_extended.py`
工具数量	4个工具	12个工具
用例	组件放置和查询	完整的制造工作流程
推荐	测试和学习	生产使用

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

这两台服务器都包含以下基本工具：

地点组件

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

参数:

reference （string）：组件引用（例如，“R1”、“U1”）
x_mm （数字）：X位置，单位为毫米
y_mm （数字）：Y位置，单位为毫米
rotation_deg （数字，可选）：旋转角度（度）

列表_组件

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

退货：包含引用、值、位置、旋转和层的JSON组件数组

read_netlist

从电路板读取网表信息。

退货：包含名称和网络代码的JSON网络数组

get_board_info

获取有关PCB的一般信息。

退货：电路板尺寸、层数、组件数量、文件名

扩展服务器附加工具（另外8个工具）

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

制造工具（5个工具）

export_gerber

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

参数:

output_dir （string）：输出目录路径
layers （数组，可选）：要导出的特定图层

退货：生成的Gerber文件列表

导出钻孔文件

以Excellon格式导出钻孔文件。

参数:

output_dir （string）：输出目录路径
merge_pth_npth （布尔值，可选）：将PTH和NPTH合并到一个文件中

退货：生成的钻孔文件路径

出口_制造_包装

将完整的制造包创建为ZIP文件。

参数:

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

退货：包路径和包含的文件列表

export_bom

以CSV格式导出物料清单。

参数:

output_path （string）：CSV文件输出路径
include_dnp （布尔值，可选）：包括“不填充”组件

退货：BOM文件路径和组件计数

export_position_file

导出拾取和放置机器的组件位置。

参数:

output_path （string）：CSV文件输出路径
side （字符串，可选）：“前”、“后”或“两者”

退货：定位文件路径和组件计数

验证工具（1个工具）

run_drc

在PCB上运行设计规则检查。

参数:

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

退货：DRC状态、错误计数、警告计数

布局工具（2个工具）

填充区

填充PCB上的铜区域。

参数:

zone_names （数组，可选）：要填充的特定区域（默认值：全部）

退货：已填充的区域数量

获取跟踪信息

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

参数:

net_name （字符串，可选）：按网络名称筛选

退货：轨道计数、总长度、层分布

可用资源

board://schematic

电路板原理图中所有组件的JSON列表

board://info

一般PCB板信息和设置

可用提示

简单电路

获取简单电路的人工智能布局指南。

参数:

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

退货：指定电路类型的布局指南和最佳实践

项目结构

MCP-KiCad/
├── kicad_mcp_server.py      # MCP server exposing KiCad tools
├── kicad_mcp_client.py      # AI client using Claude
├── requirements.txt          # Python dependencies
├── .env.example             # Example environment configuration
├── .env                     # Your API keys (not in git)
├── .gitignore              # Git ignore rules
└── README.md               # This file

已知限制

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个工具仍能正常工作

有关详细信息，请参阅制造.md.

故障排除

“pcbnew模块不可用”

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

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

“KiCad中当前没有打开PCB板”

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

“找不到ANTHROPIC_API_KEY”

创建 .env 文件来自 .env.example
添加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上处理带有通孔的电路板时
API在 PCB_VIA::GetWidth() 方法签名
警告出现在 get_track_info 运营

影响：

⚠️ get_track_info 可能会回来 None 为了 total_length_mm
✅ 所有其他工具工作正常
✅ 制造出口（Gerber、钻头、BOM）不受影响
✅ 部件操作正常

决心

无需任何操作-这是KiCad 9.x上的正常行为
如果您需要总轨道长度，请使用KiCad内置的轨道长度测量等外部工具
服务器优雅地处理这些警告并继续运行

测试： 已成功使用Olivia Control v0.2板（38个通孔）进行测试，所有12个工具均正常工作。

有关更多详细信息，请参阅制造.md.

高级用法

使用xAI Grok（克劳德的替代品）

使用Grok代替Claude：

从获取xAI API密钥https://x.ai/
修改 kicad_mcp_client.py:

# Replace Anthropic client with xAI client
from openai import OpenAI  # xAI uses OpenAI-compatible API

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

更新API调用以使用xAI的模型名称（例如“grok-beta”）

独立运行服务器

MCP服务器可供任何兼容MCP的客户端使用：

python kicad_mcp_server.py

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

使用更多工具进行扩展

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

在中定义工具 list_tools() 处理器
实现工具功能（例如。， _route_traces())
在中添加工具调用处理程序 call_tool()

要添加的示例工具：

组件之间的路线轨迹
应用设计规则
生成铜浇注
导出Gerber文件
导入组件足迹

安全考虑

API密钥：从不承诺 .env 文件到版本控制
自动执行：AI可以直接修改您的PCB-仔细查看更改
备份：始终保留KiCad项目的备份
日志记录：工具调用会记录到控制台以提高透明度

发展

模拟模式下的测试

在模拟模式下运行，不使用KiCad进行测试：

python kicad_mcp_server.py  # pcbnew not available → mock mode
python kicad_mcp_client.py kicad_mcp_server.py

模拟模式返回用于测试的模拟数据。

添加日志记录

添加详细的调试日志记录：

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

代码的风格

遵循PEP 8风格指南
对所有函数使用类型提示
带有文档字符串的文档函数
优雅地处理错误

贡献

欢迎投稿！需要改进的地方：

支持更多KiCad功能（路由、DRC等）
更好的错误处理和恢复
单元测试和集成测试
支持其他AI模型
基于Web的用户界面
多板项目

许可证

这个项目是免费和开源的。随心所欲地使用它。

资源

基卡德: https://www.kicad.org/
KiCad Python API: https://docs.kicad.org/doxygen-python/namespacepcbnew.html
MCP协议: https://modelcontextprotocol.io/
人物克劳德: https://www.anthropic.com/
xAI Grok: https://x.ai/

支持

对于问题、疑问或建议：

检查存储库中的现有问题
阅读上面的故障排除部分
查看KiCad Python API文档

致谢

构建使用：

KiCad Python API（pcbnew）
Anthropic的模型上下文协议
克劳德3.5十四行诗
Python异步

______________________________________________________________________

使用AI进行PCB设计快乐！ 🤖🔌

MCP Kicad

快速接入

详细介绍