📌Overview

Purpose: The KiCad MCP Server aims to facilitate communication and enhance productivity for KiCad users by allowing any MCP-compliant client to interact with KiCad projects through the Model Context Protocol.

Overview: The KiCad MCP Server is a versatile tool designed to provide seamless integration of various functionalities within KiCad, enabling users to manage projects, analyze designs, and interact through natural language. Though primarily optimized for macOS, it offers basic support for other platforms.

Key Features:

Project Management: Enables listing, examining, and opening KiCad projects for efficient organization and access.
PCB Design Analysis: Allows users to gain insights into PCB designs and schematics, supporting better design decisions.
Netlist Extraction: Facilitates the extraction and analysis of connections in schematics, aiding in the understanding of component relationships.
BOM Management: Generates and exports detailed Bills of Materials, vital for project documentation and procurement.
Design Rule Checking: Runs design rule checks with historical tracking, enhancing design integrity over time.
PCB Visualization: Offers visual representations of PCB layouts, making it easier to present and review designs.
Circuit Pattern Recognition: Identifies common circuit patterns in schematics, helping users to understand their designs better.

Each feature is designed to simplify complex tasks, making the design process more intuitive and integrated for users.

KiCad MCP Server

⚠️ WARNING: This project was quickly hacked together and is largely untested. Expect things to break. Use at your own risk. Improvements are planned over time; please report bugs or submit fixes.

⚠️ WARNING: This project is optimized for Mac. Basic support exists for Windows and Linux, but not all functionality is guaranteed.

This guide helps you set up a Model Context Protocol (MCP) server for KiCad. The server is compatible with any MCP-compliant client, including Claude Desktop or custom MCP clients.

Prerequisites

macOS, Windows, or Linux with KiCad installed
Python 3.10 or higher
KiCad 9.0 or higher
Claude Desktop (or another MCP client)
Basic familiarity with the terminal

Installation Steps

1. Set Up Your Python Environment

# 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 dependencies
pip install -r requirements.txt

2. Configure Your Environment

Create and edit a .env file:

cp .env.example .env
vim .env

Add your KiCad project directories (comma-separated):

KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

3. Run the Server

# Run in development mode
python -m mcp.dev main.py

# Or run directly
python main.py

4. Configure an MCP Client

For example, configure Claude Desktop by creating/editing:

mkdir -p ~/Library/Application\ Support/Claude
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the MCP server 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 your actual project path.

5. Restart Your MCP Client

Close and reopen your MCP client to apply the new configuration.

Understanding MCP Components

MCP defines three types of capabilities:

Resources

Read-only data sources, similar to GET endpoints
Provide information without computation
Used when the LLM needs data
Accessed programmatically by clients
Example: kicad://projects returns KiCad projects list

Tools

Functions performing actions or computations, similar to POST/PUT endpoints
Can have side effects (e.g., opening KiCad, generating files)
Invoked directly by the LLM (usually with user approval)
Example: open_project() launches KiCad with a specified project

Prompts

Reusable conversation templates
Help users articulate questions or tasks
Usually invoked by user choice (e.g., menu selections)
Example: debug_pcb_issues prompt assists in troubleshooting PCB problems

Feature Highlights

Project Management: List, examine, and open KiCad projects
PCB Design Analysis: Get insights about PCB designs and schematics
Netlist Extraction: Analyze component connections from schematics
BOM Management: Analyze and export Bills of Materials
Design Rule Checking: Run DRC checks and track progress (KiCad 9.0+ compatible)
PCB Visualization: Generate visual thumbnails of PCB layouts
Circuit Pattern Recognition: Identify common circuit patterns in schematics

More examples and details are available in the documentation.

Natural Language Interaction

You can interact naturally with the MCP server without specifying full file paths. For example:

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?

The server will understand your intent and may ask for clarification if needed.

Documentation

Detailed documentation is available in the docs/ directory for:

Project Management
PCB Design Analysis
Netlist Extraction
Bill of Materials (BOM)
Design Rule Checking (DRC)
PCB Visualization
Circuit Pattern Recognition
Prompt Templates

Configuration

Configure the server using environment variables or a .env file:

Environment Variable	Description	Example
`KICAD_SEARCH_PATHS`	Paths to search for KiCad projects	`~/pcb,~/Electronics,~/Projects`
`KICAD_USER_DIR`	Override the default KiCad user directory	`~/Documents/KiCadProjects`
`KICAD_APP_PATH`	Override default KiCad application path	`/Applications/KiCad7/KiCad.app`

Development Guide

Project Structure

kicad-mcp/
├── README.md               # Documentation
├── main.py                 # Server entry point
├── requirements.txt        # Dependencies
├── .env.example            # Example environment config
├── kicad_mcp/              # Main package
│   ├── __init__.py
│   ├── server.py           # Server setup
│   ├── config.py           # Configuration settings
│   ├── context.py          # Shared context management
│   ├── resources/          # Resource handlers
│   ├── tools/              # Tool handlers
│   ├── prompts/            # Prompts
│   └── utils/              # Utilities
├── docs/                   # Documentation
└── tests/                  # Unit tests

Adding New Features

Determine feature type: resource, tool, or prompt
Implement in the corresponding module
Register feature in the register function
Test with development tools

Troubleshooting

Server Not Appearing in MCP Client

Verify client configuration
Confirm paths to Python interpreter and project are correct
Ensure Python can access the mcp package
Check KiCad installation detection

Server Errors

Watch terminal output in development mode
Check log files (e.g., ~/Library/Logs/Claude/mcp-server-kicad.log)

Working Directory Issues

Use absolute paths in configuration and .env
CLI testing uses current working directory

Contributing

Contributions are welcome! To contribute:

Fork the repo
Create a feature branch
Add your changes
Submit a pull request

Focus areas include:

Expanding component pattern recognition
Improving documentation
Adding or enhancing features
Fixing bugs and improving error handling

Future Development Ideas

3D Model Visualization
PCB Review Annotation Tools
Manufacturing File Generation (Gerber files)
Component Search across KiCad libraries
BOM supplier integration and pricing
Interactive Design Checks
Web UI for configuration and monitoring
Automated Circuit Analysis
Test coverage improvements
Expand Circuit Pattern Recognition database

License

This project is open source under the MIT license.