# mcp-kicad-cli

Model Context Protocol server for KiCad CLI automation.

`mcp-kicad-cli` exposes KiCad's command-line tooling to MCP clients for ERC, DRC, BOM export, netlist export, Gerbers, drill files, STEP, IPC-2581, and GLB output. It is local-first: no cloud API key is required, but KiCad must be installed on the machine running the server.

> [!NOTE]
> This is an alpha extraction from the SpectraSynq K1 hardware automation stack. It wraps KiCad CLI commands; it does not bundle KiCad or board design files.

## Quickstart

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
```

Verify KiCad CLI is available:

```bash
kicad-cli version
```

Run the server:

```bash
export KICAD_CLI="$(command -v kicad-cli)"
mcp-kicad-cli
```

## Honest terminal demo

After install, this copy-paste check exercises the package through the same command runner used by the MCP tool:

```bash
python - <<'PY'
from mcp_kicad_cli.server import version
print(version()["stdout"].strip())
PY
```

Expected output is your installed KiCad CLI version, for example `9.0.6`.

## MCP client config

After installing the package in the Python environment used by your MCP client, add:

```json
{
  "mcpServers": {
    "kicad-cli": {
      "command": "mcp-kicad-cli",
      "args": [],
      "env": {
        "KICAD_CLI": "/opt/homebrew/bin/kicad-cli"
      }
    }
  }
}
```

See [examples/claude_desktop_config.json](examples/claude_desktop_config.json).

## Tools

- `version()` — return the installed KiCad CLI version.
- `sch_erc(schematic, out="erc.json", format="json", exit_code_violations=True)` — run ERC on a `.kicad_sch`.
- `sch_export_bom(schematic, out_csv="bom.csv", fields="*")` — export a CSV BOM.
- `sch_export_netlist(schematic, out_net="project.net", fmt="kicadsexpr")` — export a schematic netlist.
- `pcb_drc(board, out="drc.json", format="json", exit_code_violations=True)` — run DRC on a `.kicad_pcb`.
- `pcb_export_gerbers(board, out_dir="fab/gerbers")` — export Gerbers.
- `pcb_export_drill(board, out_dir="fab/drill")` — export drill files.
- `pcb_export_step(board, out_file="mechanical/board.step")` — export STEP.
- `pcb_export_ipc2581(board, out_file="fab/board.ipc")` — export IPC-2581.
- `pcb_export_glb(board, out_file="mechanical/board.glb")` — export GLB.

KiCad returns exit code `5` when violations are found; DRC/ERC wrappers treat `0` and `5` as command-level success and report the violation counts in `summary` when JSON output exists.

## Provenance

Extracted from `SpectraSynq/K1.hardware` commit `9e0b80beec0840162d3c3946f38c5c83af259790`; see [docs/provenance.md](docs/provenance.md).

This repo is now the canonical home for the KiCad CLI MCP server.

## License

Apache-2.0 — see [LICENSE](LICENSE).