# KiCad MCP Server

[![MCPAmpel](https://img.shields.io/endpoint?url=https://mcpampel.com/badge/fsbondtec/kicad-mcp.json)](https://mcpampel.com/repo/fsbondtec/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](#prerequisites)
- [Build](#build)
- [Understanding MCP Components](#understanding-mcp-components)
- [Feature Highlights](#feature-highlights)
- [Natural Language Interaction](#natural-language-interaction)
- [Documentation](#documentation)
- [Configuration](#configuration)
- [Development Guide](#development-guide)
- [Troubleshooting](#troubleshooting)
- [License](#license)

## Prerequisites

- Windows
- Python 3.10 or higher
- KiCad 9.0 or higher
- [uv](https://docs.astral.sh/uv/) 0.8.0 or higher **or** Miniconda/Anaconda
- Claude Desktop (or another MCP client)

## Build

### 1. Set Up Your Python Environment

First, let's install dependencies and set up our environment. Pick either `uv` (uses `pyproject.toml`/`uv.lock`) or `conda` (uses `environment.yml`), both are fully supported.

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

**Option A: uv**

```bash
# Create the virtual environment and install dependencies
uv sync

# Run all tests
uv run pytest tests/ -v

# run server
uv run kicad-mcp
```

**Option B: conda**

```bash
# Create the environment from environment.yml
conda env create -f environment.yml

# Activate the environment
conda activate kicad-mcp

# Install package in editable mode
pip install -e .

# Run all tests
pytest tests/ -v

# run server
kicad-mcp
```

### 2. Configure Your Environment

`KICAD_USER_DIR` and `KICAD_APP_PATH` default to platform-specific paths and are stored in `kicad-mcp-config.json`, auto-created on first run under Claude's "Claude Extensions Settings" folder (`%APPDATA%\Claude\Claude Extensions Settings\` on Windows). Edit that file to point at a different KiCad user/app directory, or change the hardcoded defaults directly in `kicad_mcp/config.py`.

Additional project search directories can be set via the `KICAD_SEARCH_PATHS` environment variable - see [Configuration](#configuration).


### 3. Configure an MCP Client

Now, let's configure Claude Desktop to use our MCP server:

1. Create or edit the Claude Desktop configuration file:

```
mkdir %APPDATA%\Claude
notepad %APPDATA%\Claude\claude_desktop_config.json
```

Or change with Claude Desktop under:
- Files -> Settings -> Developer -> Edit Config 

2. Add the KiCad MCP server to the configuration:

```json
{
    "mcpServers": {
        "kicad": {
            "command": "C:/Users/{user}/AppData/Local/miniconda3/envs/kicad-mcp/python.exe",
            "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. If you set up the environment with `uv` instead of `conda`, point `command` at the interpreter uv created instead, e.g. `/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/Scripts/python.exe`.

### 4. 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://project/{project_path}` returns details about a specific KiCad project

**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_kicad_project(project_path)` 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)

For more information on resources vs tools vs prompts, read the [MCP docs](https://modelcontextprotocol.io/docs/concepts/architecture).

## Feature Highlights

The KiCad MCP Server provides several key features, each with detailed documentation:

- **Project Management**: List, and examine KiCad projects
  - *Example:* "Show me all my recent KiCad projects" → Lists all projects claude has access to
  
- **Schematic Design Analysis**: Get insights about your schematics
  - *Example:* "Analyze the High Voltage Part of my Circuit" → Provides high voltage 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
  
- **Design Rule Checking**: Run DRC checks using the KiCad CLI and track your progress over time
  - *Example:* "Run DRC on my power supply board and compare to last week" → Shows progress in fixing violations

- **Datasheet RAG Search**: Automatically indexes component datasheets and lets Claude answer technical questions about your components
  - *Example:* "What is the I2C address of U3?" → Searches the indexed datasheet and returns the relevant section

- **Schematic and PCB path visualisation in SVG files**: Generate visual representation of paths in schematic and PCB SVG plotting
  - *Example*: "Can you find the high voltage path through my project and highlight it in schematic and pcb?" → Plots with kicad-cli all schematics to SVG and then all PCB layers in one SVG file, highlights the connections

For more examples and details on each feature, see the dedicated guides in the documentation. You can also ask the LLM what tools it has access to!

## Natural Language Interaction

While our documentation often shows examples like:

```
Show me the DRC report for C:/Users/username/Documents/KiCad/my_project/my_project.kicad_pro
```

You don't need to type the full path to your files! The LLM can understand more natural language requests.

For example, instead of the formal command above, you can simply ask:

```
Can you check if there are any design rule violations in my Arduino shield project?
```

The LLM will understand your intent and request the relevant information from the KiCad MCP Server. If it needs clarification about which project you're referring to, it will ask.

## Documentation

Detailed documentation for each feature is available in the `docs/` directory:

- [Project Management](docs/project_guide.md)
- [PCB Design Analysis](docs/analysis_guide.md)
- [Design Rule Checking (DRC)](docs/drc_guide.md)
- [Highlighting Path in plotted PCB](docs/visualize_path.md)
- [Highlight Path in plotted schematic file](docs/visualize_path_schematic.md)
- [Datasheet RAG Search](docs/rag_guide.md)

## Configuration

| Setting | How it's set | Description | Example |
|---------|-------------|-------------|---------|
| `KICAD_SEARCH_PATHS` | Environment variable or `.env` file | Comma-separated list of additional directories to search for KiCad projects | `~/pcb,~/Electronics,~/Projects` |
| `KICAD_USER_DIR` | `kicad-mcp-config.json` or `kicad_mcp/config.py` | Override the default KiCad user directory | `~/Documents/KiCadProjects` |
| `KICAD_APP_PATH` | `kicad-mcp-config.json` or `kicad_mcp/config.py` | Override the default KiCad application path | `C:/Program Files/KiCad/9.0` |

`KICAD_USER_DIR` and `KICAD_APP_PATH` are **not** environment variables - see [Configure Your Environment](#2-configure-your-environment) for where to change them.

See [Configuration Guide](docs/configuration.md) for more details.

## Development Guide

### Project Structure

The KiCad MCP Server is organized into a modular structure:

```
kicad-mcp/
├── README.md                       # Project documentation
├── main.py                         # Entry point that runs the server
├── pyproject.toml / uv.lock        # Python dependencies (uv)
├── environment.yml                 # Python dependencies (conda)
├── 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
```

### Adding New Features

To add new features to the KiCad MCP Server, follow these steps:

1. Identify the category for your feature (resource, tool, or prompt)
2. Add your implementation to the appropriate module
3. Register your feature in the corresponding register function
4. Test your changes with the development tools

See [Development Guide](docs/development.md) for more details.

## Troubleshooting

If you encounter issues:

1. **Server Not Appearing in MCP Client:**
   - Check your client's configuration file for errors
   - Make sure the path to your project and Python interpreter is correct
   - Ensure Python can access the `mcp` package
   - Check if your KiCad installation is detected

2. **Server Errors:**
   - Check the terminal output when running the server in development mode
   - Check Claude logs at:
     - `%APPDATA%\Claude\logs\mcp-server-kicad.log` (server-specific logs)
     - `%APPDATA%\Claude\logs\mcp.log` (general MCP logs)

3. **Working Directory Issues:**
   - The working directory for servers launched via client configs may be undefined
   - Always use absolute paths in your configuration and .env files
   - For testing servers via command line, the working directory will be where you run the command

See [Troubleshooting Guide](docs/troubleshooting.md) for more details.

If you're still not able to troubleshoot, please open a Github issue. 

## License

This project is open source under the MIT license.