KiCad MCP Server

KiCad MCP服务器

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

目录

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

先决条件

• macOS、Windows或Linux
• Python 3.10或更高版本
• KiCad 9.0或更高
• 紫外线0.8.0或更高
• Claude Desktop（或其他MCP客户端）

安装步骤

1.设置Python环境

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

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

# Install dependencies – `uv` will create a `.venv/` folder automatically
# (Install `uv` first: `brew install uv` on macOS or `pipx install uv`)
make install

# Optional: activate the environment for manual commands
source .venv/bin/activate

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.运行服务器

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

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组件

模型上下文协议（MCP）定义了提供功能的三种主要方式：

资源vs工具vs提示

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

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

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

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

鼓励 是用于常见交互的可重用模板：

• 预定义的对话开场白或说明
• 帮助用户阐明常见问题或任务
• 由用户选择调用（通常从菜单中调用）
• 示例：The debug_pcb_issues prompt帮助用户解决PCB问题

有关资源、工具和提示的更多信息，请阅读 MCP文件.

功能亮点

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

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

- *例子：* “显示我最近的所有KiCad项目”→ 列出按修改日期排序的所有项目

• PCB设计分析：了解您的PCB设计和原理图

- *例子：* “分析我的温度传感器板的组件密度”→ 提供元件间距分析

• 网表提取：从原理图中提取和分析组件连接

- *例子：* “Arduino屏蔽中的MCU连接了哪些组件？”→ 显示与微控制器的所有连接

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

- *例子：* “为我的智能手表项目生成物料清单”→ 创建详细的物料清单

- 设计规则检查：使用KiCad CLI运行DRC检查，并跟踪您的进度

- *例子：* “在我的电源板上运行DRC，并与上周进行比较”→ 显示修复违规行为的进展

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

- *例子：* “显示我的音频放大器PCB的缩略图”→ 显示电路板的视觉渲染

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

- *例子：* “我在物联网设备中使用了哪些电源拓扑？”→ 识别降压、升压或线性调节器

有关每个功能的更多示例和详细信息，请参阅文档中的专用指南。你也可以问LLM它可以使用哪些工具！

自然语言交互

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

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 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安装

1. 服务器错误：

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

1. 工作目录问题：

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

看 故障排除指南 了解更多详情。

如果您仍然无法排除故障，请打开Github问题。

贡献

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

1. 分叉存储库
2. 创建要素分支
3. 添加您的更改
4. 提交拉取请求

主要贡献领域：

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

看 贡献.md 详细的贡献指南。

未来发展思路

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

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

许可证

这个项目是MIT许可下的开源项目。