# kicad-mcp

MCP stdio server for creating and editing KiCad projects — schematics,
PCBs, ERC/DRC checks, and exports — driven by `kicad-cli`.

## Tools

| tool | purpose |
|---|---|
| `kicad_new_project` | scaffold `.kicad_pro` / `.kicad_sch` / `.kicad_pcb` |
| `kicad_read_file` | read a `.kicad_sch` / `.kicad_pcb` (S-expression text) |
| `kicad_sch_add_symbol` | place a symbol by library id (e.g. `Device:R`) |
| `kicad_sch_add_wire` | add a wire segment (mm coordinates, Y down) |
| `kicad_sch_add_label` | add a net label |
| `kicad_pcb_add_footprint` | place a footprint by library id |
| `kicad_pcb_add_track` | add a polyline of track segments |
| `kicad_pcb_assign_net` | declare/rename a net in the netlist |
| `kicad_list_symbols` | search symbol libraries |
| `kicad_list_footprints` | search footprint libraries |
| `kicad_erc` / `kicad_drc` | run the checkers, return reports |
| `kicad_export` | pdf / svg / netlist / bom / step / dxf / gerbers / drill |
| `kicad_version` | kicad-cli version + detected file-format versions |

## Requirements

- Python ≥ 3.10, [uv](https://docs.astral.sh/uv/)
- KiCad with `kicad-cli` on `PATH` (calibrated against KiCad 10.x)
- KiCad standard symbol/footprint libraries at `/usr/share/kicad/`
  (override via `~/.kicad-mcp.json`, see `_settings()`)

## Install

```sh
uv sync   # or: uv venv && uv pip install -e .
```

## Run

Add to your MCP client config (e.g. Claude Code / any MCP host):

```json
{
  "mcpServers": {
    "kicad": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/kicad-mcp", "kicad-mcp"]
    }
  }
}
```

## Smoke test

```sh
bun smoke.mjs    # or: node smoke.mjs
```

Drives the server over raw stdio MCP: creates a project, places a resistor
(schematic + PCB), wires/labels, runs ERC + DRC, and exports netlist, SVG,
gerbers, and drill files. Prints `SMOKE: N/N passed`.

## License

MIT