kicad-mcp

An MCP (Model Context Protocol) server that lets an LLM agent operate KiCad directly — read schematics and PCBs in a token-efficient format, place footprints, draw copper, run an autorouter, validate with ERC/DRC, and export manufacturing files — through 32 purpose-built tools instead of raw file editing.

Status: past MVP. The full PCB write loop (placement → outline → zones/GND plane → autorouting → DRC → export) has been closed and re-validated against real KiCad 10.0.4 for months. It is now in a pre-release consolidation phase: a structured Validation Suite exercises the flow against real open-hardware projects to find where it actually breaks, on purpose, before anyone else does. See Known limitations below — this README leads with them rather than burying them.

What it does

kicad-mcp automates the canonical KiCad PCB flow: place footprints → draw board outline → add copper zones/GND plane → route with Freerouting (headless autorouter) → refill zones and re-run DRC → export gerbers/BOM/renders. State is exposed to the LLM agent as TOON, a compact encoding designed to keep token usage low across many small tool calls rather than re-serializing the whole board every time.

It talks to a running KiCad instance over KiCad's own local IPC API (kicad-python) for live edits, and shells out to kicad-cli for DRC/ERC/export — it does not parse or hand-edit .kicad_pcb/.kicad_sch files itself for PCB work (schematic editing is the one exception, see limitation 7 below).

Validated scale, stated plainly: the flow has completed end-to-end, with results within the project's own acceptance thresholds, on boards up to 63 footprints / 48 nets / 2 layers. It was also run against a 437-footprint / 380-net / 4-layer board (HackRF One) specifically to find the scaling ceiling — the autorouter did not complete on that board (see limitation 2). Treat "small-to-medium 2-layer board" as the demonstrated sweet spot today, not "any KiCad project."

Related MCP server: KiCAD Schematic Manipulation MCP Server

Quickstart

git clone https://github.com/Gato513/kicad-mcp.git
cd kicad-mcp
uv sync                                   # install dependencies (uv, https://docs.astral.sh/uv/)
python3 scripts/verificar_entorno.py      # environment check — run this before anything else
uv run pytest -m "not integration"        # offline unit + golden tests (394 passing today)

verificar_entorno.py tells you exactly what's missing for the mode you're in (plain unit tests vs. tests that need a running KiCad) and prints the fix, so start there rather than guessing at env vars.

To actually drive KiCad you need:

• KiCad ≥ 9.0 installed, 10.0.4 is the validated target (see ADR-0002), with Preferences → Plugins → Enable API server turned on and KiCad restarted.

• KICAD_MCP_PROJECT set to the .kicad_pro you want the server to operate on.

• KICAD_MCP_FREEROUTING_JAR set to a local freerouting-*.jar if you want route_board to actually autoroute (Java ≥ 17 required).

• KICAD_API_SOCKET only if your KiCad API socket isn't at the default ipc:///tmp/kicad/api.sock.

Then register the server with an MCP client (uv run kicad-mcp runs it over stdio) or probe it by hand with the official inspector:

npx @modelcontextprotocol/inspector uv run kicad-mcp

A minimal first call once connected: health() to confirm the bridge can see your KiCad instance, then run_drc() against a project you don't mind DRC-checking.

Known limitations

This section exists because a colleague who tries this on their own board deserves to know where it stops working before they hit it, not after. Each item links to the session or document where it was found and verified — nothing here is a guess.

• Validated up to 63 footprints / 2 layers; a 437-footprint / 4-layer board found the scaling ceiling, not a routed result. See docs/analisis/validation-suite-sintesis-A-B-C.md for the full three-point comparison (13 fp → 63 fp → 437 fp).

• Freerouting 2.1.0 can enter an internal crash-loop on large/complex boards (observed on the 437-footprint board: repeated internal NullPointerExceptions, no routing progress for a full hour). This is an upstream Freerouting issue, not a kicad-mcp bug — route_board itself behaved correctly on the timeout (no corrupted state). See docs/BACKLOG.md (F-V3-ROUTER-TIMEOUT-HARD).

• add_zone(fill=true) can crash KiCad after 3-4 consecutive calls on large boards. Root cause is not conclusively identified — code analysis found no bridge-side cause, and the failure signature (zone fragmentation) looks like a pcbnew fill behavior at scale, but this wasn't confirmed by reproduction this cycle. Workaround: call fill_zones() once at the end instead of fill=true per zone. Full writeup: docs/analisis/auditoria-contratos-bridge.md §4.

• Most write tools don't save to disk by themselves. Tools like add_track, add_via, move_footprint mutate the live, in-memory board and expect the caller to invoke save_board() explicitly. The tools that guarantee disk == memory when they return successfully are route_board, fill_zones, add_zone(fill=true), and delete_tracks_bulk when the board has copper zones — see ADR-0012.

• delete_tracks_bulk behaves differently depending on the board. If the board contains at least one copper zone — a board-wide check, not a geometric test of whether the deletion actually touched that zone — it refills zones, re-enforces hole clearance and saves to disk before returning, raising POST_ZONE_PERSIST_FAILED if that save fails rather than succeeding silently. On a board with no copper zone it stays in-memory like the tools above, and save_board() is the caller's job. delete_zone and add_keepout_zone don't recompute neighboring zone fills on their own — tracked as A2/A3 in docs/analisis/auditoria-contratos-bridge.md §5.2.

• Freerouting doesn't treat a GND copper plane as an exclusion zone for nets it doesn't own — it only routes to the plane's own net, not around it. A specific same-layer variant of the resulting orphaned-via pattern isn't fixed by the existing post-route stitching yet. See F-D5-01-B in docs/BACKLOG.md.

• Schematic editing is direct file mutation (kicad-skip), not IPC — KiCad 10 doesn't expose a schematic API. This also means the schematic write tools (add_symbol, set_value, set_footprint, connect_pins) are purely additive today: there's no delete_wire or similar, so an agent can build a schematic but not clean one up. See docs/guias/guia-paleta.md for the one real hazard this creates (never edit a schematic file while KiCad's own editor has it open).

• Long-running tool calls (e.g. a full autoroute) can exceed an MCP client's idle timeout (~1818s observed) before KiCad/Freerouting finishes. This is a client-side limitation, not a kicad-mcp bug — driving the call from a detached process (nohup + disown) works around it. See docs/historico/sesiones/33-reporte.md.

• GUI-dependent tests require a human with KiCad open and are not automated — this is a constraint of KiCad's IPC API on this version, not a project shortcut. See docs/guias/pruebas-gui.md for the manual protocol.

• Practically Linux-only (ADR-0005). KiCad 10.0.4 is the validated target; 9.0 is the documented minimum (ADR-0002).

Documentation

• docs/analisis/validation-suite-sintesis-A-B-C.md — the cross-board evidence behind the scale claims above.

• docs/analisis/auditoria-contratos-bridge.md — full audit of every write tool's persistence/error/sync/reload contract.

• docs/adr/ — one architectural decision record per file (why KiCad 10, why stdio-only, why no database, the route_board persistence contract, etc.).

• docs/architecture-for-contributors.md — start here if you're new: real process topology, tool taxonomy, and how to navigate the ADRs/specs/session-report layers below.

• docs/DECISIONES.md — index of ADRs plus informal decisions not yet promoted to one.

• docs/investigacion/ — root-cause investigation reports for specific bugs.

• docs/glosario.md — EDA/KiCad domain glossary.

• docs/guias/guia-paleta.md — protocol for populating a schematic with add_symbol.

• docs/guias/pruebas-gui.md — manual test protocol for the GUI-dependent test suite.

• docs/INDEX.md — full documentation map, if you need something not linked above.

Contributing

Contributions are welcome. CONTRIBUTING.md covers setup, the project's write-tool contract (the 4 axes every write tool is checked against), and the review conventions that shaped the codebase — read it before opening a PR that touches anything under src/kicad_mcp/tools/ or src/kicad_mcp/bridge/.

License

Apache License 2.0 — see LICENSE. Runtime dependencies with other licenses (KiCad and Freerouting are GPL-3.0, invoked as external processes rather than linked; kicad-skip is LGPL-2.1) are listed in NOTICE.

Acknowledgments

• KiCad — the EDA platform this project automates, not replaces.

• Freerouting — the headless autorouter route_board drives. Its 2.1.0 crash-loop on large boards is a real, documented limitation (see above) — it's still the best open autorouter available for this integration.

• ANAVI Technology and Great Scott Gadgets — authors of the real open-hardware designs (anavi-dev-mic, anavi-macro-pad-12, hackrf-one) used as ground truth in the Validation Suite.

• Built with heavy use of Claude (Anthropic) as the agentic development environment throughout this project's write-tool implementation and validation cycles — noted here for transparency about how the codebase was produced, not as an endorsement of any particular workflow.

(También disponible en español.)