kicad-mcp

An MCP server that lets Claude analyze, review, and export KiCad 9 designs — and (with a running KiCad) edit boards live. Its differentiator is a built-in design-review engine encoding the teachings of Rick Hartley and Phil Salmony (Phil's Lab): stackup, return paths, grounding, decoupling, crosstalk, SMPS layout, mixed-signal partitioning, and DFM — with anti-myth guards so it never nags about 90° corners or "shield" moats.

Status: All phases (0–6) implemented. Headless analysis/verify/export, a 23-rule review engine across 10 families (with anti-myth guards), live board editing via IPC (verified against KiCad 9.0.8), experimental schematic writes, symbol/footprint/JLCPCB search, an async task queue, a tool router, and review history. 45 tools + 4 router tools, 4 prompts, 173 tests. See docs/architecture.md, PLAN.md §8, and CLAUDE.md.

The review engine (the differentiator)

review_design audits a board against a cited rule catalog and returns findings grouped by severity — each with a rule ID, a one-line physics rationale, a citation, and the exact location. v1 covers five families:

Anti-myth by construction: no rule fires on 90° corners, guard traces, via fill, or length-in-mm. A golden test asserts a board full of 90° corners produces zero findings. Use set_design_context to supply rise times / clocks / target impedances the files can't contain.

Related MCP server: Universal Netlist MCP Server

Tools

Foundation: get_server_status · list_projects · get_project_info · create_project · get_board_info · get_board_stackup · list_schematic_components · list_schematic_nets · trace_net · run_erc · run_drc · export_gerbers · export_bom · export_netlist · export_step · render_board · export_fab_package

Review engine: review_design · review_topic · set_design_context (+ the review_board prompt)

Live editing (needs a running KiCad with the IPC API enabled): get_live_board_status · list_live_footprints · move_footprint · rotate_footprint · route_trace · add_via · route_differential_pair · add_zone · refill_zones · save_board

The visual loop: edit live → save_board → render_board → inspect the PNG → edit again. Every mutation is one undo step (Cmd/Ctrl-Z reverts it in the GUI).

Architecture

One Python process (FastMCP, stdio). Three backends behind one capability interface, selected at runtime with graceful degradation:

If the GUI is down, editing tools return actionable errors while analysis/review/export keep working headless.

Install (dev)

uv venv
uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .

Or with stock tooling:

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check .

Run

python -m kicad_mcp        # stdio MCP server
# or the installed console script:
kicad-mcp

The first tool to call is get_server_status, which reports which backends are live, what capabilities are available, and the detected KiCad version.

Configuration (KICAD_MCP_*)

kicad-cli is discovered at the platform default (/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli on macOS, C:\Program Files\KiCad\9.0\bin\kicad-cli.exe on Windows, kicad-cli on PATH on Linux), overridable via KICAD_MCP_CLI_PATH.

License

MIT — see LICENSE.