kicad

KiCad MCP Server

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:

# 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. Configure Your Environment

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
vim .env

In the .env file, add your custom project directories:

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

3. Run the Server

Once the environment is set up, you can run the server:

python main.py

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:

# 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

2. Add the KiCad MCP server to the configuration:

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

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: