KiCAD-MCP-服务器

Name: KiCAD-MCP-服务器
Author: mixelpixx

作者：mixelpixx143 星标更新：2025-11-19

安装使用来源：spider==github.com

项目介绍

KiCAD MCP Server

一款生产就绪的模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够与KiCAD进行交互，实现PCB设计自动化。该服务器基于MCP 2025-06-18规范构建，提供了全面的工具模式和实时项目状态访问，以支持智能PCB设计工作流程。

概述

模型上下文协议是由Anthropic提出的一个开放标准，允许AI助手安全地连接到外部工具和数据源。此实现提供了一个标准化的桥梁，连接AI助手和KiCAD，使得可以通过自然语言控制专业的PCB设计操作。

关键能力：

52个完全文档化的工具，带有JSON模式验证
8个动态资源，暴露项目状态
完全符合MCP 2025-06-18协议
跨平台支持（Linux, Windows, macOS）
实时KiCAD UI集成
全面的错误处理和日志记录

v2.1.0 新特性

全面的工具模式

每个工具现在都包括完整的JSON模式定义，包括：

详细的参数描述和约束
类型检查的输入验证
必需参数与可选参数的指定
分类输入的枚举值
清晰的文档说明每个工具的功能

资源能力

无需执行工具即可访问项目状态：

kicad://project/current/info - 项目元数据
kicad://project/current/board - 板属性
kicad://project/current/components - 组件列表（JSON）
kicad://project/current/nets - 电气网络
kicad://project/current/layers - 层堆栈配置
kicad://project/current/design-rules - 当前DRC设置
kicad://project/current/drc-report - 设计规则违规报告
kicad://board/preview.png - 板预览图（PNG）

协议合规性

更新至MCP SDK 1.21.0（最新版）
完整支持JSON-RPC 2.0
正确的能力协商
符合标准的错误代码

可用工具

服务器提供了52个工具，按功能类别组织：

项目管理（4个工具）

create_project - 初始化新的KiCAD项目
open_project - 加载现有项目文件
save_project - 保存当前项目状态
get_project_info - 获取项目元数据

板操作（9个工具）

set_board_size - 配置PCB尺寸
add_board_outline - 创建板边缘（矩形、圆形、多边形）
add_layer - 向堆栈添加自定义层
set_active_layer - 切换工作层
get_layer_list - 列出所有板层
get_board_info - 获取板属性
get_board_2d_view - 生成板预览图像
add_mounting_hole - 放置安装孔
add_board_text - 添加文本注释

组件放置（10个工具）

place_component - 放置单个组件及其封装
move_component - 移动现有组件
rotate_component - 旋转组件
delete_component - 从板上移除组件
edit_component - 修改组件属性
get_component_properties - 查询组件详情
get_component_list - 列出所有已放置的组件
place_component_array - 创建组件网格或图案
align_components - 对齐多个组件
duplicate_component - 复制现有组件

布线及网络（8个工具）

add_net - 创建电气网络
route_trace - 布设铜箔轨迹
add_via - 放置过孔以过渡层
delete_trace - 删除轨迹
get_nets_list - 列出所有网络
create_netclass - 定义具有规则的网络类
add_copper_pour - 创建铜箔区域或填充
route_differential_pair - 布设差分信号

库管理（4个工具）

list_libraries - 列出可用的封装库
search_footprints - 搜索封装
list_library_footprints - 列出库中的封装
get_footprint_info - 获取封装详情

设计规则（4个工具）

set_design_rules - 配置DRC参数
get_design_rules - 获取当前规则
run_drc - 执行设计规则检查
get_drc_violations - 获取DRC错误报告

导出（5个工具）

export_gerber - 生成Gerber制造文件
export_pdf - 导出PDF文档
export_svg - 创建SVG矢量图形
export_3d - 生成3D模型（STEP/VRML）
export_bom - 生成物料清单

原理图设计（6个工具）

create_schematic - 初始化新的原理图
load_schematic - 打开现有原理图
add_schematic_component - 放置符号
add_schematic_wire - 连接组件引脚
list_schematic_libraries - 列出符号库
export_schematic_pdf - 导出原理图PDF

UI管理（2个工具）

check_kicad_ui - 检查KiCAD是否正在运行
launch_kicad_ui - 启动KiCAD应用程序

预备条件

必要软件

KiCAD 9.0 或更高版本

从kicad.org/download下载
必须包含Python模块（pcbnew）

验证安装：

python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Node.js 18 或更高版本

从nodejs.org下载
验证：node --version 和 npm --version

Python 3.10 或更高版本

通常随KiCAD一起提供
所需包（自动安装）：
- kicad-skip >= 0.1.0（原理图支持）
- Pillow >= 9.0.0（图像处理）
- cairosvg >= 2.7.0（SVG渲染）
- colorlog >= 6.7.0（日志记录）
- pydantic >= 2.5.0（验证）
- requests >= 2.32.5（HTTP客户端）
- python-dotenv >= 1.0.0（环境变量）

MCP客户端 选择一个：

Claude Desktop - 官方Anthropic桌面应用
Claude Code - 官方CLI工具
Cline - VSCode扩展

支持的平台

Linux (Ubuntu 22.04+，Fedora，Arch) - 主要平台，经过充分测试
Windows 10/11 - 完全支持，带有自动化设置
macOS - 实验性支持

安装

Linux (Ubuntu/Debian)

# 安装KiCAD 9.0
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt-get update
sudo apt-get install -y kicad kicad-libraries

# 安装Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 克隆并构建
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

# 验证
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Windows 10/11

自动化设置（推荐）：

git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
.\setup-windows.ps1

脚本将：

检测KiCAD安装
验证前置条件
安装依赖项
构建项目
生成配置
运行诊断

手动设置： 参见Windows安装指南获取详细步骤。

macOS

# 从kicad.org/download/macos下载KiCAD 9.0

# 安装Node.js
brew install node@20

# 克隆并构建
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

配置

Claude Desktop

编辑配置文件：

Linux/macOS: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/path/to/kicad/python",
        "LOG_LEVEL": "info"
      }
    }
  }
}

特定平台的PYTHONPATH：

Linux: /usr/lib/kicad/lib/python3/dist-packages
Windows: C:\Program Files\KiCad\9.0\lib\python3\dist-packages
macOS: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages

Cline (VSCode)

编辑：~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

使用与Claude Desktop相同的配置格式。

Claude Code

Claude Code会自动检测当前目录下的MCP服务器。不需要额外配置。

使用示例

基本PCB设计工作流

在我的文档文件夹中创建一个新的名为“LEDBoard”的KiCAD项目。
将板尺寸设置为50mm x 50mm，并添加一个矩形轮廓。
在每个角落放置一个安装孔，距离边缘3mm，直径3mm。
在前面丝印层的位置x=25mm，y=45mm处添加文本“LED控制器v1.0”。

组件放置

使用封装LED_SMD:LED_0805_2012Metric在位置x=10mm，y=10mm处放置一个LED。
从位置x=20mm，y=20mm开始创建一个间距为5mm的4个电阻（R1-R4）网格。
水平对齐所有电阻并均匀分布它们。

布线

创建一个名为“LED1”的网络，并从R1的第2个焊盘到LED1的阳极布设一条0.3mm宽的轨迹。
在底部层创建一个覆盖整个板的GND铜箔填充。
创建一个宽度为0.2mm，间隙为0.15mm的USB_P和USB_N差分对。

设计验证

设置设计规则，最小间距为0.15mm，最小导线宽度为0.2mm。
执行设计规则检查并显示任何违规。
将Gerber文件导出到“fabrication”文件夹。

使用资源

资源提供只读访问项目状态：

给我显示当前的组件列表。
当前的设计规则是什么？
显示板预览。
列出所有电气网络。

架构

MCP协议层

JSON-RPC 2.0传输： 通过STDIO进行双向通信
协议版本： MCP 2025-06-18
能力： 工具（52），资源（8）
错误处理： 标准的JSON-RPC错误代码

TypeScript服务器（`src/`）

实现MCP协议规范
管理Python子进程生命周期
处理消息路由和验证
提供日志记录和错误恢复

Python接口（`python/`）

kicad_interface.py： 主入口点，MCP消息处理器
schemas/tool_schemas.py： 所有工具的JSON模式定义
resources/resource_definitions.py： 资源处理器和URI
commands/： 模块化命令实现
- project.py - 项目操作
- board.py - 板操作
- component.py - 组件放置
- routing.py - 轨迹布线和网络
- design_rules.py - DRC操作
- export.py - 文件生成
- schematic.py - 原理图设计
- library.py - 封装库

KiCAD集成

pcbnew API： 直接的Python绑定到KiCAD
kicad-skip： 原理图文件操作
平台检测： 跨平台路径处理
UI管理： 自动启动/检测KiCAD UI

开发

从源码构建

# 安装依赖项
npm install
pip3 install -r requirements.txt

# 构建TypeScript
npm run build

# 开发模式监视
npm run dev

运行测试

# TypeScript测试
npm run test:ts

# Python测试
npm run test:py

# 包含覆盖率的所有测试
npm run test:coverage

代码检查和格式化

# 检查TypeScript和Python代码
npm run lint

# 格式化代码
npm run format

故障排除

服务器未出现在客户端

症状： MCP服务器在Claude Desktop或Cline中未出现

解决方案：

验证构建完成：ls dist/index.js
检查配置路径是绝对路径
完全重启MCP客户端
检查客户端日志中的错误信息

Python模块导入错误

症状： ModuleNotFoundError: No module named 'pcbnew'

解决方案：

验证KiCAD安装：python3 -c "import pcbnew"
检查配置中的PYTHONPATH与KiCAD安装匹配
确保KiCAD安装时带有Python支持

工具执行失败

症状： 工具执行失败，错误信息不明确

解决方案：

检查服务器日志：~/.kicad-mcp/logs/kicad_interface.log
验证在运行板操作之前加载了项目
确保文件路径是绝对路径，而不是相对路径
检查工具参数类型是否符合模式要求

Windows特定问题

症状： 服务器在Windows上无法启动

解决方案：

运行自动化诊断：.\setup-windows.ps1
验证Python路径使用双反斜杠：C:\\Program Files\\KiCad\\9.0
检查Windows事件查看器中的Node.js错误
参见Windows故障排除指南

获取帮助

查看GitHub问题
查阅服务器日志：~/.kicad-mcp/logs/kicad_interface.log
打开新问题，包含：
- 操作系统及其版本
- KiCAD版本（python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"）
- Node.js版本（node --version）
- 完整的错误消息和堆栈跟踪
- 相关的日志摘录

项目状态

当前版本： 2.1.0-alpha

生产就绪功能：

项目创建和管理
板轮廓和尺寸
层管理
组件放置（需要库集成）
安装孔和文本注释
设计规则检查
导出到Gerber、PDF、SVG、3D
原理图创建和编辑
UI自动启动
完全符合MCP协议

开发中：

JLCPCB零件集成
Digikey API集成
高级布线算法
通过IPC API实现实时UI同步
智能BOM管理

路线图：

AI辅助组件选择
设计模式库（Arduino屏蔽板，RPi HATs）
交互式设计审查模式
自动生成文档
多板项目

详见ROADMAP.md获取详细的开发时间表。

贡献

欢迎贡献！请遵循以下指南：

报告Bug： 打开一个包含复现步骤的问题
建议功能： 描述使用场景和预期行为
提交Pull Request：
- 分叉仓库
- 创建功能分支
- 遵循现有的代码风格
- 为新功能添加测试
- 更新文档
- 提交PR并附

KiCAD-MCP-服务器

项目介绍

KiCAD MCP Server

概述

v2.1.0 新特性

全面的工具模式

资源能力

协议合规性

可用工具

项目管理（4个工具）

板操作（9个工具）

组件放置（10个工具）

布线及网络（8个工具）

库管理（4个工具）

设计规则（4个工具）

导出（5个工具）

原理图设计（6个工具）

UI管理（2个工具）

预备条件

必要软件

支持的平台

安装

Linux (Ubuntu/Debian)

Windows 10/11

macOS

配置

Claude Desktop

Cline (VSCode)

Claude Code

使用示例

基本PCB设计工作流

组件放置

布线

设计验证

使用资源

架构

MCP协议层

TypeScript服务器（src/）

Python接口（python/）

KiCAD集成

开发

从源码构建

运行测试

代码检查和格式化

故障排除

服务器未出现在客户端

Python模块导入错误

工具执行失败

Windows特定问题

获取帮助

项目状态

贡献

TypeScript服务器（`src/`）

Python接口（`python/`）