KiCad PCB Design Assistant MCP Server

Installation Guide

Prerequisites

Before installing the KiCad PCB Design Assistant, ensure you have:

• Python 3.10 or higher installed
• KiCad 9.0 or higher installed
• An MCP-compliant client (such as Claude Desktop or another application that implements the Model Context Protocol)

Step 1: Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/lamaalrajih/kicad-mcp.git
cd kicad-mcp

Step 2: Set Up Python Environment

Create and activate a virtual environment, then install the required dependencies:

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Environment Settings

Create a .env file to customize where the server looks for your KiCad projects:

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

# Edit the .env file with your preferred text editor

In the .env file, add paths to your KiCad project directories:

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

Step 4: Configure Your MCP Client

Add the KiCad MCP server to your MCP client's configuration. For Claude Desktop, edit the configuration file:

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

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

Add the following configuration, replacing the paths with absolute paths to your installation:

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

Step 5: Start Using the KiCad PCB Design Assistant

1. Restart your MCP client to load the new configuration
2. Start a conversation with your AI assistant
3. Ask questions about your KiCad projects using natural language

Usage Examples

Here are some examples of how you can interact with the KiCad PCB Design Assistant:

Project Management

• "Show me all my recent KiCad projects"
• "What's the status of my temperature sensor project?"
• "Open my Arduino shield project in KiCad"

PCB Analysis

• "Analyze the component density of my smart watch PCB"
• "What's the layer stack-up in my power supply board?"
• "How many components are on my IoT device PCB?"

Design Rule Checking

• "Run a DRC check on my audio amplifier project"
• "Are there any design rule violations in my temperature sensor board?"
• "Compare current DRC results with last week's report"

BOM Management

• "Generate a bill of materials for my Arduino shield"
• "Which components in my project are most expensive?"
• "Are there any hard-to-source components in my design?"

Circuit Analysis

• "What power supply topologies am I using in my IoT device?"
• "Identify the microcontroller connections in my smart watch"
• "Show me all the decoupling capacitors in my design"

Configuration Options

The KiCad PCB Design Assistant can be customized through the .env file:

• KICAD_SEARCH_PATHS: Comma-separated list of directories to search for KiCad projects
• KICAD_EXECUTABLE_PATH: Custom path to the KiCad executable (if not in standard location)
• LOG_LEVEL: Set to DEBUG, INFO, WARNING, or ERROR to control logging verbosity

Troubleshooting

If you encounter issues:

1. Server won't start: Ensure Python 3.10+ is installed and all dependencies are installed correctly
2. Projects not found: Check your KICAD_SEARCH_PATHS in the .env file
3. KiCad not launching: Verify the KiCad installation path or set KICAD_EXECUTABLE_PATH in your .env file
4. MCP client can't connect: Check the paths in your MCP client configuration and ensure they're absolute paths

For more detailed troubleshooting, check the server logs or run with LOG_LEVEL=DEBUG in your .env file.