<a name="top"></a>

<div align="center"> <img src="resources/images/KiCAD-MCP-Server-rust.svg" alt="KiCad Agentic MCP logo" height="240" />

KiCad Agentic MCP

</div>

KiCad Agentic MCP is an MCP server and an agentic control layer for KiCad 10. An MCP client — Claude Desktop, Claude Code, or anything else that speaks the Model Context Protocol — can place and wire schematic symbols, place and route footprints in the running PCB editor, run ERC and DRC, search parts, and produce manufacturing output.

What sits between the model and your design files is the reason this project exists. A model states an intent; a typed plan is compiled and reference-checked before anything is written; execution is deterministic code run as a transaction with revision checks and rollback; and the verdict on whether a change is correct comes from KiCad — kicad-cli ERC/DRC, or the design read back — never from the model's own account of what it did. Task state, evidence and diffs are held server-side, outside any model's context.

The model is asked to reason where reasoning helps: turning a vague request into a plan. Everything that has to be exact is code.

Status: v1.2.0, AGPL-3.0. The server binary is called konnect. Every figure below traces to docs/benchmark.md or to the document named beside it; what was missed is stated as missed. Issues and PRs are welcome — CONTRIBUTING.md, naming conventions.

The control model

User intent
    │
    ▼
LLM planning                      where reasoning is useful
    │
    ▼
Plan IR                           typed, reference-checked
    │
    ▼
Deterministic compile + refusal   a plan that cannot finish never starts
    │
    ▼
Transactional execution           revisions, idempotency, rollback
    │
    ▼
KiCad
    │
    ▼
Independent validation + evidence  kicad-cli, and the design read back

The bottom half runs whether or not a model was involved: a client that calls tools directly gets the same compilation, transaction and validation path.

KiCad 10 offers three access routes, and the layer uses each for what it can actually do — this is fixed by KiCad, not chosen by preference:

                          ┌── Schematic ──→ S-expression engine (atomic writes, no running KiCad)
Agentic control layer ────┼── PCB ────────→ KiCad IPC API (NNG + protobuf, KiCad must be running)
                          └── Verify /
                              export ─────→ kicad-cli (ERC, DRC, Gerber, drill, BOM, PDF, 3D)

Schematic IPC is empty on KiCad 10 — schematic_commands.proto declares no commands — so the S-expression engine is the only path that exists, not a workaround. Details and the KiCad-11 re-evaluation are in RELEASE_NOTES.md.

AI where useful, determinism where required

| Responsibility | Owner | |---|---| | Turn an ambiguous or high-level request into a plan | An LLM — your client's model, or an opt-in local model | | Resolve the current project state | Deterministic — an indexed project graph built from the files and the board | | Check that a plan's references exist and resolve | Deterministic — the plan compiler refuses before the first mutation | | Compute coordinates | Deterministic — every coordinate the op library emits is grid-snapped | | Apply the mutation | Deterministic tool handlers | | Concurrency, idempotency, rollback | Deterministic — revisions, an idempotency ledger, a snapshot journal | | ERC / DRC | KiCad, through kicad-cli | | Decide whether the operation succeeded | Validators and evidence records, not model prose |

The LLM row is the only one a model owns, and it is optional: by default the planning model is whatever your MCP client runs. Nothing in the server calls a model unless you ask it to.

What one prompt does

<table> <tr><th width="50%">Before</th><th width="50%">After</th></tr> <tr> <td><img src="resources/images/demo-before.png" alt="Three footprints on the board, two capacitors sitting away from the regulator, no copper" /></td> <td><img src="resources/images/demo-after.png" alt="The two capacitors placed either side of the regulator, three nets closed in copper" /></td> </tr> </table>

One prompt, on the starting board committed in examples/demo/ — reproducible from the same files, not an illustration. The prompt asks for the two capacitors to be placed within 5 mm of the regulator, three nets routed, and DRC run.

The verdict is KiCad's: kicad-cli pcb drc reports 5 unconnected items on the pre-state and 0 afterwards, with 11 track segments and no errors. Run twice from the same state, it produced the same circuit both times at different coordinates. Board edits arrive through KiCad's IPC API, so Ctrl+Z walks them back like any manual edit.

Two numbers, because they measure two different things: the board changes land in under a second (0.686 s and 0.773 s of server time), while the prompt around them takes 6 to 7 minutes, because the model routes one segment per turn. Both runs, call by call, are in demo-run-2.md and demo-run-3.md; they were run against the published v1.1.0 binary.

How execution is controlled

| Mechanism | What it does | |---|---| | Plan IR (preview_plan / apply_plan) | One operation expands into many tool calls, and a later one may reference an earlier one's output. A reference that does not resolve is refused before the first mutation; preview_plan returns the exact calls and changes nothing. | | Gateway (kicad_describe / kicad_invoke) | Calls any tool by name without adding it to tools/list, so the client is never forced to re-fetch the catalogue. kicad_invoke takes a batch, stops at the first failure by default, and reports failed_at and not_run. | | Transactions and rollback | A batch runs against a directory snapshot; a partial failure restores the before-images. Every mutation leaves an entry in an append-only run journal. | | Optimistic concurrency and idempotency | base_revisions are content-addressed, so an edit made in another window is detected instead of overwritten; an operation_id ledger returns the first result on a retry. changes_since reports what happened after a revision token. | | Editor-lock refusal | A .kicad_sch KiCad has open is refused (error_kind: conflict), re-checked immediately before the commit, leaving the file byte-identical. | | Semantic diff and evidence handles | Changes are reported by stable item key; snapshots and diffs are addressable MCP resources (kicad://snapshot/N, 64 entries). Validator findings carry stable ids, so a fix is an id that disappeared. | | Task state outside the context | Objective, constraints, verified facts, failed attempts and evidence live server-side and survive a context compaction or a model swap. | | Project graph | An indexed world model with filtered lookups and spatial neighbours, so a query replaces dumping a whole design. | | Operating modes | ReadOnly, Write (default), Manufacturing, Experimental, enforced before a handler runs so a refusal has nothing to roll back. | | Structured refusal | A check that could not run is reported as an error, never as a check that passed. |

Architecture, crate by crate, is in DEV.md.

Measured results

Against current upstream, on live PCB work: see docs/benchmark-pcb-live-v2.md — five live PCB workflows (schematic → PCB sync, live ≠ saved, zone + net change, flip + via, schematic parity), the same intention given to this fork and to Konnect v0.13.0, judged by KiCad 10.0.6 alone. That document, not the table below, is the basis for any comparison with Konnect as it stands today.

What the table below measured (token and call cost at the fork point, not live PCB correctness, and not today's upstream). Seven scripted tasks (schematic authoring, hierarchical sheets, a template, exports, inspection, and a recovery task where five wrong inputs must each fail loudly), each starting from an empty directory, five repeats. Run on 2026-08-24 on one machine — Windows 11, Ryzen 7 9800X3D, KiCad 10.0.3 — against mixelpixx/Konnect v0.2.2 at commit 5cd6454, unmodified, driven by the same scripted oracle. Success is decided by kicad-cli ERC and by reading the design back, never by a model's prose. Full method, artefacts and the reproduction commands: docs/benchmark.md.

| | Konnect v0.2.2 baseline | This fork, gateway route | |---|---|---| | runs passed | 35/35 | 35/35 | | MCP calls, median per task | 11 | 4 | | external tokens, median per task | 14 337 | 2 249 | | wall clock, P50 | 77 ms | 86 ms |

"External tokens" is tool output plus the tools/list refreshes the server forces on the client — a cost the caller cannot decline, and the reason the two columns differ so much: the gateway route adds nothing to tools/list.

What the same run missed, unmoved:

• Wall clock is worse: 86 ms against 77 ms. The fork loses where it guarantees something — the recovery task, which exercises the journal, the snapshot manifest and the evidence store, costs +109 ms — and wins where there is nothing to guarantee (inspection, 14 → 6 ms).
• External tokens missed their own target (≤ 2 000, measured 2 249), and startup tools/list missed its target (≤ ~1 000, measured 2 831 tokens for 21 tools).
• Success rate is equal, not ahead. A scripted route succeeds by construction on both servers; what this measures is what the route costs.
• The baseline column was run with one extra toolset loaded, because this fork moved export_bom between toolsets. Without that, upstream fails the export task outright on a taxonomy difference rather than a missing capability; both runs are in the benchmark document.

What this does not measure. One machine, one KiCad version, scripted routes, and schematic and export paths only — the golden suite contains no PCB task, because PCB work needs a running KiCad. It says what a surface costs on that suite. It does not predict success on an arbitrary KiCad project, and it is not a statement about Konnect as it stands today.

The local-model runtime (kicad_agent) is the opt-in path where the server itself calls a model on loopback: the caller states an objective, the model writes a Plan IR, and the server compiles, applies and verifies it, with kicad-cli returning the verdict. It has built two of the benchmark designs end to end, one run each — no success rate is claimed from that. Where it was measured with a sample big enough to carry a number, gpt-oss-20b at medium reasoning wrote a fully correct plan on 16 of 60 one-shot attempts and a compilable one on 53 of 60. Treat it as working and early, not as a hands-off autopilot.

Capabilities

| Area | What it covers | |---|---| | Schematic | Symbols, wires, junctions, net labels, power symbols, buses; pin-to-pin connection by name; hierarchical sheets and sheet pins; batch edits | | PCB | Footprint placement, alignment and duplication; traces, vias, copper pours, net classes, differential pairs; outline, layers, zones, mounting holes, silkscreen | | Inspection | Net connectivity, pin queries, trace paths, overlap and orphan detection, project-graph queries | | Validation | ERC and DRC through kicad-cli; decoupling, connection, power-rail, DFM and BOM-health audits | | Fabrication | Gerber, drill, pick-and-place, BOM, netlist, PDF, SVG, 3D, DXF/GenCAD/IPC-2581/ODB++; a fab package with cost estimation and fab-house validation | | Parts and libraries | Library search and registration, footprint creation and graphics editing, a local JLCPCB parts cache, datasheet lookup, Freerouting autoroute | | Reference circuits | USB-C, LDO, buck converter, STM32, I2