mcp-server-kicad

<!-- mcp-name: io.github.ProductOfAmerica/mcp-server-kicad -->

<div align="center">

<img src="https://raw.githubusercontent.com/ProductOfAmerica/mcp-server-kicad/main/.github/assets/logo.png" alt="mcp-server-kicad" width="128">

# mcp-server-kicad

**Let an AI assistant edit real KiCad projects without corrupting them.**

109 MCP tools covering schematic capture, PCB layout, symbol and footprint
libraries, ERC and DRC, and manufacturing exports. No screenshots, no
copy-paste, no hand-edited s-expressions: the model calls tools, KiCad files
change on disk.

[![PyPI](https://img.shields.io/pypi/v/mcp-server-kicad?style=flat-square&logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/mcp-server-kicad/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-server-kicad?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/mcp-server-kicad/)
[![KiCad](https://img.shields.io/badge/KiCad-9%20%7C%2010-314CB0?style=flat-square&logo=kicad&logoColor=white)](https://www.kicad.org/)
[![Tests](https://img.shields.io/github/actions/workflow/status/ProductOfAmerica/mcp-server-kicad/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=tests)](https://github.com/ProductOfAmerica/mcp-server-kicad/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue?style=flat-square)](LICENSE)

[Quick start](#quick-start) •
[What you get](#what-you-get) •
[Configuration](#configuration) •
[Tool reference](#tool-reference) •
[Requirements](#requirements) •
[Contributing](#contributing)

</div>

---

## What it looks like

```text
"Add a 100 nF decoupling cap on U1's VCC pin, then check ERC."

  get_pin_positions            locate U1's VCC and GND pins
  auto_place_decoupling_cap    place C3 and wire both pins to their nets
  run_erc                      report what the change broke

"Now push the netlist to the board and route it."

  update_pcb_from_schematic    sync footprints and pad nets onto the PCB
  autoroute_pcb                route with Freerouting
  run_drc                      clearance, width, and unconnected checks
```

Every tool works on the real file, and a write changes only the bytes you asked
it to. An edit that cannot be done correctly is refused with the file intact.
KiCad itself writes a design file in just two places: the library upgrades, and
`autoroute_pcb`'s routed copy, a new board that leaves yours untouched.

## Quick start

### Claude Code

Install the plugin. It wires up the server and ships the design skills with it:

```bash
claude plugin marketplace add ProductOfAmerica/mcp-server-kicad
claude plugin install kicad
```

### Claude Desktop

Download `kicad-<version>.mcpb` from the [latest release][latest] and install it
from Settings, then Extensions. Claude Desktop fetches Python and the package
itself; you need KiCad installed, plus Java for `autoroute_pcb`.

Desktop does not run from your project directory, so fill in the schematic,
board, and export paths it asks for. Leave the `kicad-cli` field blank unless
KiCad is installed somewhere unusual. The design skills are Claude Code only.

[latest]: https://github.com/ProductOfAmerica/mcp-server-kicad/releases/latest

### Everything else

```bash
pip install mcp-server-kicad
```

Then point your MCP client at the unified server and set `cwd` to a KiCad
project directory so paths resolve themselves:

```json
{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad"],
      "cwd": "/path/to/your/kicad/project"
    }
  }
}
```

That single entry registers all 109 tools. Prefer to split them across five
smaller servers? See [Configuration](#configuration).

## What you get

### Five tool servers

Run them as one unified server, or separately when you want a smaller tool
surface in context.

| Server | Tools | What it does |
|--------|:-----:|--------------|
| `mcp-server-kicad-schematic` | 42 | Schematic read/write, net tracing, ERC, exports (PDF, SVG, DXF, netlist, BOM) |
| `mcp-server-kicad-pcb` | 34 | Board read/write, netlist import, zones, DRC, autorouting, exports (Gerber, drill, 3D, pick-and-place) |
| `mcp-server-kicad-project` | 24 | Project scaffolding, hierarchical sheets, hierarchy validation, annotation, cross-sheet net tracing |
| `mcp-server-kicad-symbol` | 5 | Symbol library browsing, authoring, SVG export, format upgrade |
| `mcp-server-kicad-footprint` | 4 | Footprint library browsing, SVG export, format upgrade |

### Six design skills (Claude Code plugin)

Tools alone let a model click every button. The bundled skills teach it which
buttons, in what order, and what "done" looks like.

| Skill | Kicks in when |
|-------|---------------|
| [`using-kicad`](skills/using-kicad/SKILL.md) | Any electronics or EDA conversation starts. Routes to the right skill below |
| [`circuit-design`](skills/circuit-design/SKILL.md) | Choosing topology, regulators, and component values, before any file exists |
| [`schematic-plan`](skills/schematic-plan/SKILL.md) | Planning exact placement coordinates and wiring. Pure planning, no writes |
| [`schematic-design`](skills/schematic-design/SKILL.md) | Executing that plan, or modifying an existing schematic |
| [`pcb-layout`](skills/pcb-layout/SKILL.md) | Placing footprints, routing, zones, stackup, trace widths |
| [`verification`](skills/verification/SKILL.md) | ERC and DRC failures, unconnected nets, export prep |

The design skills hand their artifacts to independent reviewer subagents
([`agents/`](agents/)) before moving on, so a bad BOM or a bad placement plan
gets caught before it becomes a schematic.

## Configuration

### Split servers

Five entries instead of one, when you want to load only part of the tool
surface:

<details>
<summary><b>Five-server MCP config</b></summary>

```json
{
  "mcpServers": {
    "kicad-schematic": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-schematic"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-pcb": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-pcb"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-symbol": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-symbol"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-footprint": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-footprint"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-project": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-project"],
      "cwd": "/path/to/your/kicad/project"
    }
  }
}
```

Each is also runnable directly:

```bash
uvx --from mcp-server-kicad mcp-server-kicad-schematic
```

</details>

### How paths resolve

Highest priority wins:

1. **Tool parameters.** Every tool accepts an explicit path.
2. **Environment variables.** They override anything auto-detected.
3. **Auto-detect.** The working directory is scanned for a `.kicad_pro`, and
   the schematic, board, and library paths are derived from it.

| Variable | Points at |
|----------|-----------|
| `KICAD_SCH_PATH` | a `.kicad_sch` schematic file |
| `KICAD_PCB_PATH` | a `.kicad_pcb` board file |
| `KICAD_SYM_LIB` | a `.kicad_sym` symbol library file |
| `KICAD_FP_LIB` | a `.pretty` footprint library directory |
| `KICAD_OUTPUT_DIR` | where exports and reports are written |

## Requirements

- **Python 3.11+**
- **KiCad 9.x or 10.x**, only for the tools that call KiCad:
  - `kicad-cli`: ERC, DRC, exports, jobsets, `get_version`, the library
    upgrades and `update_pcb_from_schematic`
  - `pcbnew` Python bindings: `fill_zones` and `autoroute_pcb` (which also
    needs Java)
  - KiCad's stock libraries: placing a stock symbol or footprint

  Every other tool parses files directly and needs no KiCad.

CI covers Linux (KiCad 9 and 10), macOS and Windows (KiCad 10), and Python
3.11 to 3.14.

### Finding your KiCad install

A stock install needs no configuration. `kicad-cli` is found on `PATH`, then in
`/Applications/KiCad/KiCad.app` on macOS, then under `Program Files` and
`AppData` on Windows, newest first. The stock libraries and `pcbnew`'s Python
are found relative to it. For an unusual install:

| Variable | Overrides |
|----------|-----------|
| `KICAD_CLI_PATH` | the `kicad-cli` executable, and everything derived from its location |
| `KICAD_SYMBOL_DIR` | the directory holding the stock `.kicad_sym` libraries |
| `KICAD_PYTHON` | the interpreter used for `pcbnew` (`fill_zones`, `autoroute_pcb`), as an absolute path or a name on `PATH` |

Without `kicad-cli`, the tools that need it stay listed and fail with a message
naming `KICAD_CLI_PATH`.

### KiCad 10 files

The server's own reads and writes handle KiCad 9 and 10 schematics, boards,
symbol libraries and footprints alike, and never change bytes you did not ask to
change (see
[docs/adr-cst-substrate.md](docs/adr-cst-substrate.md)). Work handed to KiCad
itself only succeeds if your install can load the file, and KiCad 9 cannot load
a KiCad 10 board:

- **`fill_zones` and `autoroute_pcb`** refuse a KiCad 10 board on a KiCad 9
  `pcbnew` before starting; install KiCad 10 or point `KICAD_PYTHON` at one.
  `autoroute_pcb` on a KiCad 9 board through KiCad 10's `pcbnew` works but
  warns that the routed copy comes back in KiCad 10 format. It never touches
  the original board.
- **`upgrade_symbol_lib` and `upgrade_footprint_lib`** let KiCad rewrite your
  files, by design. Each file is replaced atomically and only if it changed, so
  an interrupted upgrade leaves none damaged. A backup goes to `<name>.bak`,
  overwritten every run.

### Windows: Controlled Folder Access

Defender's Controlled Folder Access blocks unrecognised apps from writing under
Documents, where KiCad keeps its data. `kicad-cli` then crashes at startup
(exit `3221225477`) on every call, `--version` included