KiCad MCP 服务器

⚠️警告：本项目是快速拼凑的，大部分内容未经测试。请做好出错的准备。使用风险自负。我计划逐步改进，但如果您发现任何 bug，请提交 issue 或 pull request 来修复（请参阅下方的“贡献”部分）。

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

本指南将帮助您为 KiCad 设置模型上下文协议 (MCP) 服务器。虽然本指南中的示例通常引用 Claude Desktop，但该服务器与任何符合 MCP 标准的客户端兼容。您可以将其与 Claude Desktop、您自己的自定义 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 服务器：

创建或编辑 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

将 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) 定义了提供功能的三种主要方式：

资源、工具和提示

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

类似于 REST API 中的 GET 端点
无需进行大量计算即可提供数据
当法学硕士需要阅读信息时使用
通常由客户端应用程序以编程方式访问
示例： 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 的缩略图”→显示电路板的视觉渲染
电路模式识别：自动识别原理图中的常见电路模式
- 示例： “我的物联网设备使用什么电源拓扑？” → 识别降压、升压或线性稳压器

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

自然语言交互

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

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/目录中找到：

配置

可以使用环境变量或.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                       # 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 服务器添加新功能，请按照以下步骤操作：

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

请参阅开发指南以了解更多详细信息。

故障排除

如果您遇到问题：

服务器未出现在 MCP 客户端中：
- 检查客户端的配置文件是否有错误
- 确保项目和 Python 解释器的路径正确
- 确保 Python 可以访问mcp包
- 检查是否检测到您的 KiCad 安装
服务器错误：
- 在开发模式下运行服务器时检查终端输出
- 检查 Claude 日志：
  - ~/Library/Logs/Claude/mcp-server-kicad.log （服务器特定日志）
  - ~/Library/Logs/Claude/mcp.log （常规 MCP 日志）
工作目录问题：
- 通过客户端配置启动的服务器的工作目录可能未定义
- 始终在配置和 .env 文件中使用绝对路径
- 对于通过命令行测试服务器，工作目录将是您运行命令的位置

请参阅故障排除指南以了解更多详细信息。

贡献

想要为 KiCad MCP 服务器做出贡献吗？您可以通过以下方式帮助改进此项目：

分叉存储库
创建功能分支
添加您的更改
提交拉取请求

贡献的关键领域：

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

请参阅CONTRIBUTING.md了解详细的贡献指南。

未来发展思路

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

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

执照

该项目根据 MIT 许可证开源。

KiCad MCP Server

Integrations