# kicad-mcp

An MCP server that gives an AI agent end-to-end control of KiCad 9+: rule checks, manufacturing exports, a production-readiness certification gate, live PCB-editor control, and netlist generation.

It is built around a simple split that mirrors how KiCad actually works:

- **`kicad-cli`** (headless, no running instance) handles DRC/ERC and every export (Gerbers, drill, position, BOM, STEP, PDF, SVG, netlist, PNG render).
- **`kipy`** (the KiCad 9 IPC API) handles live control of a board open in the PCB editor.
- A **built-in s-expression parser** reads `.kicad_pcb` / `.kicad_sch` files offline with zero dependencies, so inspection always works.
- **SKiDL** turns Python hardware descriptions into importable netlists.
- **`kicad_preflight`** ties the checks and exports together into a single pass/fail certification that only emits a fabrication package when the board actually passes.

## Surfaces and tools

| Surface | Tools |
|---|---|
| Headless checks & exports (`kicad-cli`) | `kicad_cli_info`, `kicad_run_drc`, `kicad_run_erc`, `kicad_export`, `kicad_generate_fab_package` |
| Certification workflow | `kicad_preflight` |
| Offline inspection & safe edits | `kicad_inspect_project`, `kicad_set_title_block`, `kicad_set_symbol_field` |
| Live IPC control (`kipy`) | `kicad_connect`, `kicad_board_summary`, `kicad_list_footprints`, `kicad_move_footprint`, `kicad_set_footprint_value`, `kicad_save_board` |
| Netlist generation (SKiDL) | `kicad_generate_netlist` |

`kicad_preflight` is the headline tool. Given a board (and ideally its schematic) it runs ERC, DRC with schematic parity, a fully-routed check, and a board-outline check as hard gates, plus soft checks for missing footprint values and unplaced parts. Only when every hard gate passes does it generate the Gerber/drill/position/BOM package (zipped), a STEP model, and PCB/schematic PDFs.

## Installation

Requires Python 3.10+ and KiCad 9.0+.

```bash
pip install -e .[all]
```

The base install depends only on `mcp` and `pydantic`. The optional bindings are pulled in by extras and each degrades gracefully — if one is missing, only its tools report an actionable install hint, and the rest of the server keeps working:

- `.[live]` → `kicad-python` (live IPC control)
- `.[edit]` → `kiutils` (offline field edits)
- `.[netlist]` → `skidl` (netlist generation)
- `.[all]` → everything

`kicad-cli` itself ships with KiCad; it is not a pip package. The server finds it automatically via the `KICAD_CLI` environment variable, then `PATH`, then the standard install locations:

- Windows: `C:\Program Files\KiCad\9.0\bin\kicad-cli.exe`
- macOS: `/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli`
- Linux: `/usr/bin/kicad-cli`

If it lives elsewhere, set `KICAD_CLI` to the full path.

## Enabling live control

The live tools talk to a running KiCad over its IPC API. In KiCad, open **Preferences → Plugins** and enable the **KiCad API**, then keep a board open in the PCB editor. The IPC API in KiCad 9/10 covers the PCB editor only and does not do exports — that is why exports go through `kicad-cli`.

## Claude Desktop configuration

Add the server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kicad": {
      "command": "python",
      "args": ["-m", "kicad_mcp"],
      "env": {
        "KICAD_CLI": "C:\\Program Files\\KiCad\\9.0\\bin\\kicad-cli.exe"
      }
    }
  }
}
```

On Windows, the config file location depends on how Claude Desktop was installed:

- Standard install: `%APPDATA%\Claude\claude_desktop_config.json`
- **MSIX / Microsoft Store install**: `%APPDATA%` is redirected into the package sandbox, so the file lives under
  `C:\Users\<you>\AppData\Local\Packages\<ClaudePackageFamilyName>\LocalCache\Roaming\Claude\claude_desktop_config.json`

The reliable way to avoid guessing is to open the file from inside the app (**Settings → Developer → Edit Config**), which always writes to the correct location for your install. Point `command` at the Python interpreter of the environment where you installed `kicad-mcp` (a full path to `python.exe` avoids `PATH` surprises under MSIX). A sample config is in `examples/claude_desktop_config.json`.

## Notes

- Tool inputs are validated with Pydantic; malformed calls fail fast with a clear message.
- Rule-check tools parse `kicad-cli`'s JSON reports, so violations come back as structured severity counts rather than scraped text.
- Live edits (`kicad_move_footprint`, `kicad_set_footprint_value`) apply to the open editor immediately but are not written to disk until `kicad_save_board`.
- `kicad_inspect_project` never needs KiCad installed at all.