KiCad MCP 服务器

⚠️ 警告: 此项目是快速拼凑而成的，且未经充分测试。可能会出现各种问题。使用风险自负。我计划随着时间推移改进它，但如果你发现错误，请打开一个 issue 或提交 pull request 来修复它们（见下文贡献部分）。

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

本指南将帮助你为 KiCad 设置一个 Model Context Protocol (MCP) 服务器。尽管本指南中的示例经常引用 Claude Desktop，但该服务器与任何符合 MCP 的客户端兼容。你可以将其与 Claude Desktop、自定义的 MCP 客户端或任何实现 Model Context Protocol 的应用程序一起使用。

目录

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

先决条件

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

安装步骤

1. 设置你的 Python 环境

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

# Clone the repository
git clone https://github.com/lamaalrajih/kicad-mcp.git .

# Create a virtual environment and activate it
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the MCP SDK and other dependencies
pip install -r requirements.txt

2. 配置你的环境

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

# Copy the example environment file
cp .env.example .env

# Edit the .env file
vim .env

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

# Add paths to your KiCad projects (comma-separated)
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

3. 运行服务器

一旦环境设置好，你可以运行服务器：

# Run in development mode
python -m mcp.dev main.py

# Or run directly
python main.py

4. 配置 MCP 客户端

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

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

# Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Edit the configuration file
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

1. 将 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 组件

Model Context Protocol (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" → 创建详细的物料清单

  • 设计规则检查：运行 DRC 检查并跟踪您的进度

  • 示例: "对我的电源板进行 DRC 检查，并与上周的结果比较" → 显示修复违规情况的进展

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

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

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

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

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

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

自然语言交互

虽然我们的文档经常展示类似以下的例子：

Show me the DRC report for /Users/username/Documents/KiCad/my_project/my_project.kicad_pro

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

例如，您可以简单地询问：

Can you check if there are any design rule violations in my Arduino shield project?

或者：

I'm working on the temperature sensor circuit. Can you identify what patterns it uses?

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

文档

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

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

配置

KiCad MCP 服务器可以通过环境变量或 .env 文件进行配置：

主要配置选项

环境变量	描述	示例
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                       # Project documentation
├── main.py                         # Entry point that runs the server
├── requirements.txt                # Python dependencies
├── .env.example                    # Example environment configuration
├── kicad_mcp/                      # Main package directory
│   ├── __init__.py
│   ├── server.py                   # MCP server setup
│   ├── config.py                   # Configuration constants and settings
│   ├── context.py                  # Lifespan management and shared context
│   ├── resources/                  # Resource handlers
│   ├── tools/                      # Tool handlers
│   ├── prompts/                    # Prompt templates
│   └── utils/                      # Utility functions
├── docs/                           # Documentation
└── tests/                          # Unit 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. 分叉仓库
2. 创建一个功能分支
3. 添加您的更改
4. 提交拉取请求

主要贡献领域：

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

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

未来开发想法

有兴趣贡献吗？这里有一些未来开发的想法：

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

许可证

本项目是开源的，并遵循MIT许可证。