openkonnect
openkonnect is an MCP server that lets an LLM inspect and safely drive a running KiCad 10 PCB editor through its IPC API.
Inspect whether KiCad is running, whether IPC is reachable, versions, project directory, open documents, dirty state, and supported tools.
Summarize the open board live, including unsaved changes: path, title block, layers, footprint/net/track/via/zone counts, outline size, and dirty state.
Read the PCB editor selection as kct-compatible references such as footprint refs, REF.PAD, nets, nets_of_footprints, plus other/undescribed items and bounding box; optionally filter by kind and include geometry.
Resolve kicad-tools findings against the live board and select affected items, reporting resolved/unresolved locators and stale findings; highlight/zoom report unsupported_on_this_kicad on KiCad 10.
Save a dirty or unknown-state board before an external kct write, with allow_save gating and file/editor hashes; schematic save is refused unless schematic_unverified_ok is set.
Reload the editor from disk after an external write, with safety checks, optional discard_unsaved, expected_hash/editor_hash validation, and manual_reload_required for schematics.
Run one allow-listed kct write command through the full handoff protocol: check session, save, run with timeout, and reload only on success/change.
Note KiCad 10 limitations: dirty state is always unknown, so treat it as dirty; no documented zoom/net-highlight API; schematic save/reload over IPC is unsupported.
Enables an LLM agent to drive a running KiCad 10 editor through KiCad's IPC API, supporting schematic, layout, placement, routing, design review, and manufacturing tools in live boards and schematics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openkonnect route the selected nets on my board and run a DRC check"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
openkonnect
An MIT-licensed MCP server that lets an LLM agent drive a running KiCad 10: schematic, layout, placement, routing, design review and manufacturing tools, through KiCad's IPC API.
Status: Phase 0 bootstrap. The MCP server runs and exposes read-only tools that inspect the session and the open board, plus the save, sync and handoff tools that write files or reload the editor (see Tools). See ROADMAP.md for the plan and spec/capabilities.md for what each tool does.
Quickstart
1. Install. You need uv and Python 3.10 or newer.
git clone https://github.com/rjwalters/openkonnect
cd openkonnect
uv sync
uv run openkonnect --version2. Turn on KiCad's API server. In KiCad 10, open Preferences > Plugins, check Enable KiCad API, and restart KiCad. The API is off by default. Then open your board in the PCB editor. Check the connection with:
uv run openkonnect statusIt prints session_status as JSON. "ipc_reachable": true means the server
can reach KiCad. Otherwise reason says what is wrong, for example
kicad_not_running or ipc_disabled.
3. Register the server with your MCP client. The server speaks MCP over stdio. For Claude Code, run:
claude mcp add openkonnect -- uv run --directory /path/to/openkonnect openkonnect serveFor clients configured with JSON (Claude Desktop, Cursor and similar):
{
"mcpServers": {
"openkonnect": {
"command": "uv",
"args": ["run", "--directory", "/path/to/openkonnect", "openkonnect", "serve"],
"env": { "OPENKONNECT_TIMEOUT": "5" }
}
}
}Tools
Tool | Spec | What it returns |
| SES-01 | Whether KiCad is running and its API reachable, versions, instance, project directory, open documents with dirty state, and which tools this instance supports. "Not running" and "API disabled" come back as data, not errors. |
| SES-02 | Every KiCad instance whose API socket can be found: endpoint, process id, whether it answered, KiCad version, open board path, and why not if it did not answer. No sockets is an empty list; a platform that cannot list sockets says |
| LAY-01 | Live overview of the open board, unsaved changes included: path, title block, layer counts, counts of footprints, nets, tracks, vias and zones, outline size, dirty state. |
| LAY-08 | The outline of the open board, unsaved changes included: the closed polygons that make it up (file frame, mm, each with a role of |
| LAY-02 | Live list of the board's footprints, unsaved changes included: refdes, value, library ID, position (file and board frames, with the offset between them), rotation, side, locked, attributes and fields. Optional filters: |
| LAY-03 | Live pads of the footprints named in |
| SES-08 | What is selected in the PCB editor, as file-level references |
| LAY-04 | The nets on the open board with each net's net class and pad count; optional glob |
| LAY-05 | The tracks, arcs and vias on the open board, unsaved changes included: session id, kind, net, layer (a via: its drill span), width, endpoints or centre in both frames, length (an arc's true arc length; a via has none), a via's diameter, drill and type, and locked state, plus the total length per net over the filtered items. Optional |
| LAY-06 | The copper zones and rule areas on the open board, unsaved changes included: session id, name, net, layers, priority, pad-connection style, filled and locked state; a rule area also lists what it keeps out. Optional |
| LAY-07 | The open board's enabled layers (canonical and user names) and its physical build-up as currently set in the editor, unsaved changes included: the stackup top to bottom, per row its kind, layer, user name, enabled flag, thickness and material, with the dielectric type and each sub-layer's |
| SES-09 | Selects in the editor the items that kicad-tools findings ( |
| SES-04 | Before a |
| SES-05 | After a |
| SES-06 | Runs one allow-listed |
On KiCad 10, dirty is always "unknown" with dirty_basis: "none": KiCad
10's API cannot report unsaved changes. Treat unknown as dirty.
Every failure is a structured error (code, message, retryable,
details), and every result carries meta with the time bound used and the
number of busy retries.
Setting | Flag | Environment | Default |
Bound on one tool call (s) |
|
| 5 |
Bound on one IPC request (s) |
|
| 2 |
Retries when KiCad is busy |
|
| 3 |
API socket |
|
| discovered |
Development
uv run ruff check . && uv run ruff format --check .
uv run pytest -rsUnit tests run against a fake IPC backend. Tests marked live_kicad drive
the open KiCad editor (they save, reload and change its selection), so they
are skipped unless pytest is given --live, whatever -m filter or test path
is passed; uv run pytest -rs (and CI) runs every other test and lists them as
skipped. To run them, start KiCad 10 with the API on and the fixture board
each test names open (tests/fixtures/board.kicad_pcb, or
tests/fixtures/selection.kicad_pcb for the selection test), then run
uv run pytest --live -m live_kicad -rs. With --live they still skip when
KiCad is not reachable or the wrong board is open.
Related MCP server: pcb-mcp
Why this exists
In October 2026 the open-source AGPL KiCad agent plugin Konnect was archived, and development moved to a commercial, closed-source successor. openkonnect is an independent, clean-room implementation of the same kind of tool, under a permissive license, so that a free live-editor agent interface for KiCad stays available.
openkonnect is not affiliated with, endorsed by, or derived from Konnect, Konnect-EDA or Orchis.ai LLC. It contains none of their code. See CLEANROOM.md for how that is kept true.
Design
Python, built on kicad-tools (MIT). File-level work (parsing, checks, netlists, exports) comes from kicad-tools. openkonnect adds what needs a live editor: the IPC session, selection and view state, and interactive edits in an open board or schematic.
KiCad 10 IPC API for the live editor, through KiCad's official
kicad-pythonbindings (MIT; see docs/ipc-client.md). NopcbnewSWIG bindings.MCP as the agent interface, usable from any MCP client.
License
MIT. See LICENSE. Third-party code reused with attribution is listed in NOTICE.
Available Tools
7 toolsboard_summaryARead-only
Summarize the board open in KiCad's PCB editor, live (including unsaved changes): path, title block, copper and total layer counts, counts of footprints, nets, tracks, vias and zones, outline size, and dirty state. Fails fast with a structured error when KiCad is unreachable or no board is open.
Inputs: no named parameters.
get_selectionARead-only
Read what is selected in KiCad's PCB editor, live, as stable file-level references that kct commands accept: footprints (reference designators), pads ('REF.PAD'), nets (of the selected copper, pads and zones), nets_of_footprints (nets reached through selected footprints' pads), other (tracks, vias, zones and graphics, with a session-scoped id and no_file_reference: true), undescribed (selected items this client cannot decode, counted, never dropped), and bbox (mm, file frame) with the board-frame offset. Optional kinds filter (e.g. ['footprint', 'pad']); include_geometry adds per-item positions and boxes. An empty selection is an ordinary empty result.
Inputs: kinds, include_geometry.
run_kct_handoffADestructive
Run one allow-listed kicad-tools write command (kct) on the board open in KiCad, following the handoff protocol: check the session, save the editor (allow_save=true is needed when dirty state is unknown, as on KiCad 10), run the command with a timeout, then reload the editor from the file only if the command succeeded and changed it. An edit made in KiCad while the command ran makes the reload refuse with document_dirty, and nothing is lost; discard_unsaved=true reloads anyway and discards that edit. command is an argv list without 'kct', and must contain the token {board}, which is replaced by the board's path, e.g. ["route", "{board}", "-o", "{board}"]. Board only on KiCad 10.
Inputs: command (required), documents, timeout_s, allow_save, +1 more.
save_before_external_writeA
Before a file-based tool (kct) touches a board open in KiCad, make the file on disk match the editor. A board proven clean is left alone. A dirty board, or one whose dirty state is unknown (always possible on KiCad 10), is refused unless allow_save=true; then it is saved and the file is checked to have changed. Returns each document's state before, the action (none/saved/refused) and the file SHA-256 plus editor_sha256 to pass to sync_from_disk. The schematic cannot be saved over KiCad 10's API: it is refused unless schematic_unverified_ok=true.
Inputs: documents, allow_save, schematic_unverified_ok.
session_statusARead-only
Report whether KiCad is running and its IPC API reachable, the KiCad and API versions, the instance, the project directory, the open documents with their dirty state, and which tools this instance supports. Always answers: 'not running' and 'API disabled' come back as data.
Inputs: no named parameters.
show_findingsA
Point the user at kicad-tools findings in KiCad's PCB editor: resolve each finding's locators (reference designators, 'REF.PAD', net names, a point) against the live board and select the affected items (replacing the selection). findings is the JSON a kct command printed with --format json (kct check, kct drc, kct detect-mistakes, kct net-status), or a list of its findings. mode: select | highlight | both; focus: 'all', a finding index, 'next' or 'previous'; zoom: true/false. On KiCad 10 there is no documented zoom or net-highlight API, so highlight and zoom report unsupported_on_this_kicad while the selection still happens. Per finding the result lists the resolved items, the locators that did not resolve with a reason, and the action taken, plus totals. Findings whose pcb_sha256 no longer matches the board are still resolved and flagged possibly_stale. A finding's location is optional: one with a null or missing location is resolved from its names and reported with has_point false.
Inputs: findings (required), mode, zoom, focus.
sync_from_diskADestructive
After a file-based tool (kct) wrote a board that is open in KiCad, reload the editor from the file. Refuses, changing nothing, if the editor may hold unsaved work: dirty or unknown (KiCad 10 has no dirty query) unless discard_unsaved=true. The board counts as clean only when openkonnect reads the editor's content now and it equals the file now (byte-identical, or on KiCad 10.0.7 equal token for token apart from KiCad's known save formatting); no hash you pass can prove it clean. editor_hash (editor_sha256 from save_before_external_write) lets openkonnect detect an edit made in KiCad since (document_dirty); unchanged, it stays unknown. expected_hash (the file hash after your tool wrote it) refuses an unexpected write with stale_input. The reload is not an undo step. The schematic cannot be reloaded over KiCad 10's API: it is reported as manual_reload_required.
Inputs: documents, editor_hash, expected_hash, discard_unsaved.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The read/inspect tools are clearly distinct, and save_before_external_write/sync_from_disk are explicitly framed as before/after steps. The main overlap is that run_kct_handoff orchestrates the same save-run-reload sequence as the manual save/sync pair, but the input shapes and descriptions make the intended use mostly clear.
All tools use snake_case and descriptive names, so the set is readable. The convention is not strictly uniform verb_noun: session_status and board_summary are noun phrases while the action tools use verbs, which is a minor but noticeable deviation.
Seven tools is well within the appropriate range for a focused KiCad editor integration server. Each tool covers a distinct part of the workflow: session inspection, board/selection reads, findings display, and safe external-write handoff.
The surface covers the core live-editor workflow: status, board summary, selection reading, findings display, save/reload primitives, and an orchestrated kct write path. Minor gaps remain, notably no way to run read-only kct commands that would generate findings and the explicitly manual schematic reload path.
Maintenance
Related MCP Connectors
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
Turn datasheets into source-backed JSON contracts, pinout matrices, and KiCad CAD for AI agents.
Design and revise PCBs from plain language, track jobs, and retrieve design artifacts.
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables LLMs to inspect, edit, analyze, and render PCB layouts in real-time using the KiCad IPC API, providing tools for board configuration, footprints, tracks, zones, nets, text, shapes, dimensions, exports, screenshots, and CLI automation.1001MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to read and modify KiCAD PCB designs through the KiCAD IPC API, providing tools for board queries, footprint placement, track creation, DRC, and export.14MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with KiCAD for PCB design automation, including schematic editing, component placement, routing, DRC/ERC, and export.10038 npm2MIT
- AlicenseAqualityCmaintenanceEnables MCP clients such as Claude Code to work on KiCad 10 designs by driving kicad-cli for ERC, DRC, netlists and fabrication exports, KiCad's IPC API for live board editing, and lossless edits of schematic and project files. It also provides design review, routing, parts and datasheet tooling so a board can be treated as data and checked against fab limits.353MIT