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

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

Verify KiCad CLI is available:

kicad-cli version

Run the server:

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:

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:

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

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

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

License

Apache-2.0 — see LICENSE.