lamaalrajih/kicad-mcp

This guide will help you set up a Model Context Protocol (MCP) server for KiCad. While the examples in this guide often reference Claude Desktop, the server is compatible with **any MCP-compliant client**. You can use it with Claude Desktop, your own custom MCP clients, or any other application that implements the Model Context Protocol.
Table of Contents
- Prerequisites
- Installation Steps
- Understanding MCP Components
- Feature Highlights
- Natural Language Interaction
- Documentation
- Configuration
- Development Guide
- Troubleshooting
- Contributing
- Future Development Ideas
- License
Prerequisites
- macOS, Windows, or Linux
- Python 3.10 or higher
- KiCad 9.0 or higher
- uv 0.8.0 or higher
- Claude Desktop (or another MCP client)
Installation Steps
1. Set Up Your Python Environment
First, let's install dependencies and set up our environment:
2. Configure Your Environment
Create a .env file to customize where the server looks for your KiCad projects:
In the .env file, add your custom project directories:
3. Run the Server
Once the environment is set up, you can run the server:
4. Configure an MCP Client
Now, let's configure Claude Desktop to use our MCP server:
1. Create or edit the Claude Desktop configuration file:
2. Add the KiCad MCP server to the configuration:
Replace /ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp with the actual path to your project directory.
5. Restart Your MCP Client
Close and reopen your MCP client to load the new configuration.
Understanding MCP Components
The Model Context Protocol (MCP) defines three primary ways to provide capabilities:
Resources vs Tools vs Prompts
**Resources** are read-only data sources that LLMs can reference:
- Similar to GET endpoints in REST APIs
- Provide data without performing significant computation
- Used when the LLM needs to read information
- Typically accessed programmatically by the client application
- Example: kicad://projects returns a list of all KiCad projects
**Tools** are functions that perform actions or computations:
- Similar to POST/PUT endpoints in REST APIs
- Can have side effects (like opening applications or generating files)
- Used when the LLM needs to perform actions in the world
- Typically invoked directly by the LLM (with user approval)
- Example: open_project() launches KiCad with a specific project
**Prompts** are reusable templates for common interactions:
- Pre-defined conversation starters or instructions
- Help users articulate common questions or tasks
- Invoked by user choice (typically from a menu)
- Example: The debug_pcb_issues prompt helps users troubleshoot PCB problems
For more information on resources vs tools vs prompts, read the MCP docs.
Feature Highlights
The KiCad MCP Server provides several key features, each with detailed documentation:
- **Project Management**: List, examine, and open KiCad projects
- *Example:* "Show me all my recent KiCad projects" → Lists all projects sorted by modification date
- **PCB Design Analysis**: Get insights about your PCB designs and schematics
- *Example:* "Analyze the component density of my temperature sensor board" → Provides component spacing analysis
- **Netlist Extraction**: Extract and analyze component connections from schematics
- *Example:* "What components are connected to the MCU in my Arduino shield?" → Shows all connections to the microcontroller
- **BOM Management**: Analyze and export Bills of Materials
- *Example:* "Generate a BOM for my smart watch project" → Creates a detailed bill of materials
- **Design Rule Checking**: Run DRC checks using the KiCad CLI and track your progress over time