一、准备环境与先决条件
在开始之前，确保系统中已安装以下软件：
KiCAD 10.0+（或 8.x+，推荐最新稳定版）：[点击下载]
Windows 默认路径一般为
C:\Program Files\KiCad\10.0\macOS 默认路径为
/Applications/KiCad/KiCad.app
Node.js：18.0 或更高版本（用于运行 MCP 服务的 TypeScript/Node 端）[点击下载]
Python：3.11 或更高版本，以及
pipGit：用于克隆仓库
二、克隆仓库与构建
打开终端（Terminal 或 PowerShell），执行以下命令：
Bash
# 1. 克隆稳定分支 (stable)
git clone --branch stable https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
# 2. 安装 Node 依赖并构建项目
npm install
npm run build
# 3. 安装 Python 核心依赖
pip install -r requirements.txt
自动化脚本提示：仓库根目录下自带一键设置脚本：
Windows（管理员身份在 PowerShell 中执行）：
.\setup-windows.ps1macOS：
chmod +x setup-macos.sh && ./setup-macos.shLinux：
chmod +x setup-linux.sh && ./setup-linux.sh
三、配置 AI 客户端
根据你使用的客户端，将 MCP 服务添加进对应配置文件中：
方案 A：配置 Claude Desktop
打开 Claude Desktop 的配置文件：
Windows：
%APPDATA%\Claude\claude_desktop_config.jsonmacOS / Linux：
~/.config/claude/claude_desktop_config.json
在 mcpServers 对象中添加配置（注意将路径替换为您本机的实际绝对路径）：
Windows 示例：
JSON
{
"mcpServers": {
"kicad": {
"command": "node",
"args": [
"C:\\Users\\workstation\\kicad-mcp-server\\dist\\index.js"
],
"env": {
"KICAD_CLI_PATH": "D:\\Program Files\\KiCad\\10.0\\bin\\kicad-cli.exe",
"PYTHON_PATH": "D:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
"PYTHONPATH": "D:\\Program Files\\KiCad\\10.0\\bin;D:\\Program Files\\KiCad\\10.0\\bin\\Lib\\site-packages",
"PATH": "D:\\Program Files\\KiCad\\10.0\\bin;C:\\Program Files\\nodejs;C:\\WINDOWS\\system32;C:\\WINDOWS"
}
}
},
"coworkUserFilesPath": "C:\\Users\\workstation\\Claude",
"preferences": {
"coworkBrowserToolsEnabled": true,
"coworkPreferredBrowser": "built_in",
"launchPreviewPersistedWorkspaces": [],
"launchPreviewSessionScopedSessions": [],
"coworkLegacyRootGrantsPruned": true,
"coworkScheduledTasksEnabled": true,
"coworkHipaaRestricted": false,
"orgWorkAcrossAppsDisabled": false,
"ccdScheduledTasksEnabled": true,
"httpCacheZstdLatched": true,
"userDataOutsidePackageAnswer": true,
"sidebarMode": "epitaxy",
"bypassPermissionsGateByAccount": {
"95314ac1-4fcb-42e2-b316-2abb7d272f0b": false,
"e6fe2fbb-4b42-4b31-a144-df00a0663f2b": false
},
"coworkWebSearchEnabled": true,
"coworkModelAutoFallbackByAccount": {
"95314ac1-4fcb-42e2-b316-2abb7d272f0b": true,
"e6fe2fbb-4b42-4b31-a144-df00a0663f2b": true
},
"remoteToolsDeviceName": "jackye-workstation",
"epitaxyPrefs": {
"starred-local-code-sessions": [],
"starred-cowork-spaces": [],
"starred-session-groups": [],
"desktop-frame.paneStore.v1": {
"state": {
"extraPanesByMode": {},
"colWeightsByMode": {},
"rowSplit": 0.5,
"draftNonce": 0,
"lastPrimaryCodeSession": {
"id": "local_adae4b5f-4cc4-4583-b1d8-f9809d7a6d9b",
"type": "local"
}
},
"version": 4
},
"ccd-sessions-filter": {
"state": {
"selectedProjects": []
},
"version": 0
},
"dframe-group-scopes": {},
"dframe-local-slice": {
"pinnedOrder": [],
"homeProjectsPinnedOrder": []
},
"starred-local-routines": [],
"dframe-code-sections": {
"e6fe2fbb-4b42-4b31-a144-df00a0663f2b/1e016acf-d462-4f6b-9b9b-747e58060061": {
"sections": [
{
"id": "pinned",
"kind": "pinned",
"v": 2,
"name": "",
"order": 0,
"sortBy": "recency",
"ascending": false,
"show": {
"metadata": false,
"emptyGroups": false,
"sideChats": false,
"slack": true
},
"collapsed": false,
"shown": true
},
{
"id": "routines",
"kind": "routines",
"v": 2,
"name": "",
"order": 1,
"sortBy": "recency",
"ascending": false,
"show": {
"metadata": false,
"emptyGroups": false,
"sideChats": false,
"slack": true
},
"collapsed": true,
"shown": false
},
{
"id": "sessions",
"kind": "sessions",
"v": 2,
"name": "",
"order": 2,
"sortBy": "recency",
"ascending": false,
"show": {
"metadata": false,
"emptyGroups": false,
"sideChats": false,
"slack": true
},
"collapsed": false,
"shown": true
}
],
"migratedFrom": 1,
"prefsSeeded": true
}
},
"epitaxy-auto-default-notice-seen.e6fe2fbb-4b42-4b31-a144-df00a0663f2b": true
}
}
}macOS / Linux 示例：
JSON
{
"mcpServers": {
"kicad-mcp": {
"command": "node",
"args": [
"/Users/username/KiCAD-MCP-Server/build/index.js"
],
"env": {
"PYTHONPATH": "/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.11/site-packages"
}
}
}
}
方案 B：配置 VS Code (GitHub Copilot / Cline / Roo Code)
如果使用 VS Code，进入你的工程工作区或仓库：
在项目根目录创建
.vscode/mcp.json。填入以下配置：
JSON
{
"servers": {
"kicad-mcp": {
"command": "node",
"args": [
"${workspaceFolder}/KiCAD-MCP-Server/build/index.js"
]
}
}
}
四、验证与使用
重启客户端：保存配置后，彻底退出并重启 Claude Desktop 或 VS Code。
检查 MCP 工具：
在 Claude Desktop 输入框右下角查看是否有小锤子图标（Tools）。
查看列表中是否出现了 KiCAD 相关的工具（如
create_project、add_component、route_track、run_drc等）。
初次测试指令： 在聊天窗口中直接向 AI 发送指令：
"创建一个名为
esp32_sensor_board的 KiCAD 工程，并在原理图中放置一个 ESP32-WROOM 模块和两个上拉电阻。"
五、常见问题与注意事项
Python SWIG / 模块找不到错误 (
ModuleNotFoundError: No module named pcbnew)： KiCAD 的 Python 绑定（pcbnew）通常位于 KiCAD 自带的 Python 环境中。如果报找不到模块，必须确保配置文件的env.PYTHONPATH指向 KiCAD 安装目录下的site-packages。路径转义问题（Windows）： 在 JSON 文件中书写 Windows 路径时，反斜杠
\必须转义为双反斜杠\\，否则会导致 JSON 解析失败。自动布线支持： 若需要使用 Freerouting 自动布线功能，系统需安装 Java 运行环境（JRE 17+）或配置好 Docker 环境。
评论区