使用说明

KiCAD MCP服务器

一个生产就绪的模型上下文协议（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/下载
必须包含Python模块（pcbnew）

验证安装：

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

Node.js 18或更高版本

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

Python 3.10或更高版本

通常包含在KiCAD中
所需软件包（自动安装）：
- kicad跳过>=0.1.0（原理图支持）
- 枕头>=9.0.0（图像处理）
- cairosvg>=2.7.0（SVG渲染）
- colorlog>=6.7.0（日志记录）
- pydantic>=2.5.0（验证）
- 请求>=2.32.5（HTTP客户端）
- python dotenv>=1.0.0（环境）

MCP客户端 选择一个：

克劳德桌面 -官方Anthropic桌面应用程序
克劳德代码 -官方CLI工具
克莱恩 -VSCode扩展

支持平台

Linux （Ubuntu 22.04+、Fedora、Arch）-主要平台，经过全面测试
Windows 10/11 -完全支持自动设置
macOS -实验支持

安装

Linux（Ubuntu/Debian）

# Install 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

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

# Clone and build
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

# Verify
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

# Install KiCAD 9.0 from kicad.org/download/macos

# Install Node.js
brew install node@20

# Clone and build
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

配置

克劳德桌面

编辑配置文件：

Linux/macOS： ~/.config/Claude/claude_desktop_config.json
窗户： %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
窗户： 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会自动检测当前目录中的MCP服务器。无需额外配置。

用法示例

基本PCB设计工作流程

Create a new KiCAD project named 'LEDBoard' in my Documents folder.
Set the board size to 50mm x 50mm and add a rectangular outline.
Place a mounting hole at each corner, 3mm from the edges, with 3mm diameter.
Add text 'LED Controller v1.0' on the front silkscreen at position x=25mm, y=45mm.

元件布局

Place an LED at x=10mm, y=10mm using footprint LED_SMD:LED_0805_2012Metric.
Create a grid of 4 resistors (R1-R4) starting at x=20mm, y=20mm with 5mm spacing.
Align all resistors horizontally and distribute them evenly.

路由

Create a net named 'LED1' and route a 0.3mm trace from R1 pad 2 to LED1 anode.
Add a copper pour for GND on the bottom layer covering the entire board.
Create a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.

设计验证

Set design rules with 0.15mm clearance and 0.2mm minimum track width.
Run a design rule check and show me any violations.
Export Gerber files to the 'fabrication' folder.

使用资源

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

Show me the current component list.
What are the current design rules?
Display the board preview.
List all electrical nets.

建筑

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
命令/： 模块化命令实现
- project.py -项目运营
- board.py -董事会操纵
- component.py -组件放置
- routing.py -跟踪路由和网络
- design_rules.py -刚果民主共和国行动
- export.py -文件生成
- schematic.py -方案设计
- library.py -足迹库

KiCAD集成

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

发展

从源头构建

# Install dependencies
npm install
pip3 install -r requirements.txt

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

运行测试

# TypeScript tests
npm run test:ts

# Python tests
npm run test:py

# All tests with coverage
npm run test:coverage

装订和格式化

# Lint TypeScript and Python
npm run lint

# Format code
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-阿尔法

生产就绪功能：

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

开发中：

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

路线图：

人工智能辅助组件选择
设计模式库（Arduino屏蔽、RPi HAT）
交互式设计评审模式
自动生成文档
多板项目

看 ROADMAP.md 了解详细的开发时间表。

贡献

欢迎投稿！请遵循以下指南：

报告错误： 打开一个关于复制步骤的问题
建议功能： 描述用例和预期行为
提交拉取请求：
- 分叉存储库
- 创建要素分支
- 遵循现有代码样式
- 添加新功能的测试
- 更新文档
- 提交带有清晰描述的PR

看贡献.md 详细指南。

许可证

该项目根据MIT许可证获得许可。看许可证了解详情。

致谢

建立在模型上下文协议通过Anthropic
由...驱动基卡德开源PCB设计软件
用途基卡德-跳过用于原理图操作

引用

如果您在研究或出版物中使用此项目，请引用：

@software{kicad_mcp_server,
  title = {KiCAD MCP Server: AI-Assisted PCB Design},
  author = {mixelpixx},
  year = {2025},
  url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
  version = {2.1.0-alpha}
}

使用说明

KiCAD MCP服务器

概述

v2.1.0的新增功能

综合工具架构

资源能力

协议遵从

可用工具

项目管理（4个工具）

董事会运营（9种工具）

组件放置（10个工具）

路由和网络（8个工具）

图书馆管理（4个工具）

设计规则（4个工具）

导出（5个工具）

方案设计（6个工具）

UI管理（2个工具）

先决条件

所需软件

支持平台

安装

Linux（Ubuntu/Debian）

Windows 10/11

macOS

配置

克劳德桌面

Cline（VSCode）

克劳德代码

用法示例

基本PCB设计工作流程

元件布局

路由

设计验证

使用资源

建筑

MCP协议层

TypeScript服务器(src/)

Python接口(python/)

KiCAD集成

发展

从源头构建

运行测试

装订和格式化

故障排除

服务器未出现在客户端中

Python模块导入错误

工具执行失败

Windows特定问题

获取帮助

项目状态

贡献

许可证

致谢

引用

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

Markdown微信排版发布工具

TypeScript服务器(`src/`)

Python接口(`python/`)