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.