KiCad MCP 服务器

⚠️ 警告: 此项目是快速拼凑而成，并且在很大程度上未经测试。预计会出现问题。使用风险自负。我计划随着时间的推移对其进行改进，但如果您发现错误，请提交 issue 或 pull request 来修复它们（请参阅下面的“贡献”部分）。

⚠️ 警告: 此项目针对 Mac 进行了优化。虽然存在对 Windows 和 Linux 的一些基本支持，但不能保证所有功能都能正常工作。

本指南将帮助您为 KiCad 设置模型上下文协议 (MCP) 服务器。虽然本指南中的示例经常引用 Claude Desktop，但该服务器与任何符合 MCP 规范的客户端兼容。您可以将其与 Claude Desktop、您自己的自定义 MCP 客户端或任何其他实现模型上下文协议的应用程序一起使用。

目录

• 先决条件
• 安装步骤
• 了解 MCP 组件
• 功能亮点
• 自然语言交互
• 文档
• 配置
• 开发指南
• 故障排除
• 贡献
• 未来发展思路
• 许可证

先决条件

• 安装了 KiCad 的 macOS、Windows 或 Linux
• Python 3.10 或更高版本
• KiCad 9.0 或更高版本
• Claude Desktop（或其他 MCP 客户端）
• 熟悉终端的基本知识

安装步骤

1. 设置您的 Python 环境

首先，让我们安装依赖项并设置我们的环境：

# 克隆存储库
git clone https://github.com/lamaalrajih/kicad-mcp.git .

# 创建一个虚拟环境并激活它
python3 -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安装 MCP SDK 和其他依赖项
pip install -r requirements.txt

2. 配置您的环境

创建一个 .env 文件来自定义服务器查找您的 KiCad 项目的位置：

# 复制示例环境变量文件
cp .env.example .env

# 编辑 .env 文件
vim .env

在 .env 文件中，添加您的自定义项目目录：

# 添加 KiCad 项目的路径（逗号分隔）
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

3. 运行服务器

设置好环境后，您可以运行服务器：

# 在开发模式下运行
python -m mcp.dev main.py

# 或者直接运行
python main.py

4. 配置 MCP 客户端

现在，让我们配置 Claude Desktop 以使用我们的 MCP 服务器：

1. 创建或编辑 Claude Desktop 配置文件：

# 如果目录不存在，则创建该目录
mkdir -p ~/Library/Application\ Support/Claude

# 编辑配置文件
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 将 KiCad MCP 服务器添加到配置中：

{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
            ]
        }
    }
}

将 /ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp 替换为您的项目目录的实际路径。

5. 重新启动您的 MCP 客户端

关闭并重新打开您的 MCP 客户端以加载新配置。

了解 MCP 组件

模型上下文协议 (MCP) 定义了提供功能的三个主要方式：

资源 vs 工具 vs 提示

资源是 LLM 可以引用的只读数据源：

• 类似于 REST API 中的 GET 端点
• 提供数据而不执行重要的计算
• 当 LLM 需要读取信息时使用
• 通常由客户端应用程序以编程方式访问
• 示例：kicad://projects 返回所有 KiCad 项目的列表

工具是执行操作或计算的函数：

• 类似于 REST API 中的 POST/PUT 端点
• 可以有副作用（例如打开应用程序或生成文件）
• 当 LLM 需要在世界中执行操作时使用
• 通常由 LLM 直接调用（经用户批准）
• 示例：open_project() 使用特定项目启动 KiCad

提示是用于常见交互的可重用模板：

• 预定义的对话启动器或说明
• 帮助用户表达常见问题或任务
• 由用户选择调用（通常从菜单中）
• 示例：debug_pcb_issues 提示帮助用户排除 PCB 问题

功能亮点

KiCad MCP 服务器提供几个关键功能，每个功能都有详细的文档：

• 项目管理: 列出、检查和打开 KiCad 项目

  • 示例: "显示我所有最近的 KiCad 项目" → 列出所有按修改日期排序的项目

• PCB 设计分析: 获取有关您的 PCB 设计和原理图的见解

  • 示例: "分析我的温度传感器板的元件密度" → 提供元件间距分析

• 网络表提取: 从原理图中提取和分析元件连接

  • 示例: "我的 Arduino 扩展板中哪些元件连接到 MCU？" → 显示与微控制器的所有连接

• BOM 管理: 分析和导出物料清单

  • 示例: "为我的智能手表项目生成 BOM" → 创建详细的物料清单

  • 设计规则检查: 运行 DRC 检查并跟踪您随时间的进展

  • 示例: "在我的电源板上运行 DRC 并与上周进行比较" → 显示修复违规的进展

  • KiCad 9.0+ 兼容: 自动使用新的 KiCad CLI 或 IPC API

• PCB 可视化: 生成 PCB 布局的可视化表示

  • 示例: "显示我的音频放大器 PCB 的缩略图" → 显示电路板的可视化渲染

• 电路模式识别: 自动识别原理图中的常见电路模式

  • 示例: "我在我的 IoT 设备中使用什么电源拓扑？" → 识别降压、升压或线性稳压器

有关每个功能的更多示例和详细信息，请参阅文档中的专用指南。

自然语言交互

虽然我们的文档经常显示如下示例：

显示 /Users/username/Documents/KiCad/my_project/my_project.kicad_pro 的 DRC 报告

您无需键入文件的完整路径！ LLM 可以理解更自然的语言请求。

例如，您可以简单地问：

你能检查一下我的 Arduino 扩展板项目是否有任何设计规则冲突吗？

或者：

我正在研究温度传感器电路。 你能识别它使用什么模式吗？

LLM 将理解您的意图并从 KiCad MCP 服务器请求相关信息。 如果需要澄清您指的是哪个项目，它会询问。

文档

每个功能的详细文档都可以在 docs/ 目录中找到：

• 项目管理
• PCB 设计分析
• 网络表提取
• 物料清单 (BOM)
• 设计规则检查 (DRC)
• PCB 可视化
• 电路模式识别
• 提示模板

配置

可以使用环境变量或 .env 文件配置 KiCad MCP 服务器：

主要配置选项

环境变量	描述	示例
KICAD_SEARCH_PATHS	用于搜索 KiCad 项目的目录的逗号分隔列表	~/pcb,~/Electronics,~/Projects
KICAD_USER_DIR	覆盖默认的 KiCad 用户目录	~/Documents/KiCadProjects
KICAD_APP_PATH	覆盖默认的 KiCad 应用程序路径	/Applications/KiCad7/KiCad.app

有关更多详细信息，请参阅 配置指南。

开发指南

项目结构

KiCad MCP 服务器被组织成一个模块化结构：

kicad-mcp/
├── README.md                       # 项目文档
├── main.py                         # 运行服务器的入口点
├── requirements.txt                # Python 依赖项
├── .env.example                    # 示例环境配置
├── kicad_mcp/                      # 主包目录
│   ├── __init__.py
│   ├── server.py                   # MCP 服务器设置
│   ├── config.py                   # 配置常量和设置
│   ├── context.py                  # 生命周期管理和共享上下文
│   ├── resources/                  # 资源处理程序
│   ├── tools/                      # 工具处理程序
│   ├── prompts/                    # 提示模板
│   └── utils/                      # 实用函数
├── docs/                           # 文档
└── tests/                          # 单元测试

添加新功能

要向 KiCad MCP 服务器添加新功能，请按照以下步骤操作：

1. 确定您的功能的类别（资源、工具或提示）
2. 将您的实现添加到相应的模块
3. 在相应的注册函数中注册您的功能
4. 使用开发工具测试您的更改

有关更多详细信息，请参阅 开发指南。

故障排除

如果您遇到问题：

1. 服务器未出现在 MCP 客户端中：

   • 检查客户端的配置文件是否存在错误
   • 确保项目和 Python 解释器的路径正确
   • 确保 Python 可以访问 mcp 包
   • 检查是否检测到您的 KiCad 安装

2. 服务器错误：

   • 在开发模式下运行服务器时检查终端输出
   • 检查 Claude 日志：
     • ~/Library/Logs/Claude/mcp-server-kicad.log（服务器特定日志）
     • ~/Library/Logs/Claude/mcp.log（常规 MCP 日志）

3. 工作目录问题：

   • 通过客户端配置启动的服务器的工作目录可能未定义
   • 始终在您的配置和 .env 文件中使用绝对路径
   • 对于通过命令行测试服务器，工作目录将是您运行命令的位置

有关更多详细信息，请参阅 故障排除指南。

贡献

想要为 KiCad MCP 服务器做出贡献吗？ 以下是如何帮助改进此项目的方法：

1. Fork 存储库
2. 创建一个功能分支
3. 添加您的更改
4. 提交 pull request

贡献的关键领域：

• 在电路模式识别系统中添加对更多元件模式的支持
• 改进文档和示例
• 添加新功能或增强现有功能
• 修复错误并改进错误处理

有关详细的贡献指南，请参阅 CONTRIBUTING.md。

未来发展思路

有兴趣贡献吗？ 以下是一些未来发展的想法：

1. 3D 模型可视化 - 实施工具以可视化 PCB 的 3D 模型
2. PCB 审查工具 - 为设计审查创建注释功能
3. 制造文件生成 - 添加对生成 Gerber 文件和其他制造输出的支持
4. 元件搜索 - 为 KiCad 库中的元件实施搜索功能
5. BOM 增强 - 添加供应商集成以进行元件采购和定价
6. 交互式设计检查 - 开发用于检查设计质量的交互式工具
7. Web UI - 创建一个简单的 Web 界面用于配置和监控
8. 电路分析 - 添加自动电路分析功能
9. 测试覆盖率 - 提高整个代码库的测试覆盖率
10. 电路模式识别 - 使用更多元件类型和电路拓扑扩展模式数据库

许可证

本项目在 MIT 许可证下开源。