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

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+.

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:

{
  "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.