Skip to main content
Glama
openkonnect

openkonnect

by 2AMLogic

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 --version

2. 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 status

It 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 serve

For 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

session_status

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.

list_instances

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 listable: false. Sockets are probed one at a time, each bounded by the call timeout.

board_summary

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.

board_outline

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 outline or hole), the extents, the board-frame offset and KiCad's grid and drill origins in both frames. Arcs and circles are sampled into segments. No Edge.Cuts shapes is present: false; shapes that do not close are closed: false with the open chains and the gap that defeated them, never a rectangle.

list_footprints

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: refs, side, box (frame required), selected_only; a filter matching nothing is an empty list.

footprint_pads

LAY-03

Live pads of the footprints named in refs (R1 for all its pads, R1.2 for one), unsaved changes included: REF.PAD, number, net, position (file and board frames, with the offset), layers, shape and size. An unknown reference or pad is not_found; a net that cannot be read is net: null with net_state: "unknown" and a reason, never unconnected.

get_selection

SES-08

What is selected in the PCB editor, as file-level references kct accepts (reference designators, REF.PAD, nets), plus other items with session-scoped ids and the selection's bounding box. An empty selection is an ordinary result.

list_nets

LAY-04

The nets on the open board with each net's net class and pad count; optional glob pattern and net_class filters. include_items adds the items on each net (pads as REF.PAD, other copper with session ids) and needs KiCad 10.0.1, else unsupported_on_this_kicad.

list_copper

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 net, layer, box (frame required; keeps an item when any point it reports is inside) and locked_only filters; a filter matching nothing is an empty list, an unknown layer is invalid_argument.

list_zones

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 net and layer filters; a filter matching nothing is an empty list, an unknown layer is invalid_argument.

layers_and_stackup

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 epsilon_r/loss_tangent/thickness where KiCad gives them, plus the copper count and the total thickness. Lengths in millimetres; anything KiCad does not report is null.

show_findings

SES-09

Selects in the editor the items that kicad-tools findings (kct ... --format json) point at, and reports per finding what resolved, what did not and why, and which findings may be stale.

save_before_external_write

SES-04

Before a kct command touches the open board: each document's state before, the action taken (none, saved or refused), and the file and editor hashes to pass to sync_from_disk. Refuses a dirty or unknown board unless allow_save. See the handoff protocol.

sync_from_disk

SES-05

After a kct command wrote the board: per document, whether the editor was reloaded from the file and whether unsaved changes were discarded. Refuses, changing nothing, when the editor may hold unsaved work, unless discard_unsaved. See the handoff protocol.

run_kct_handoff

SES-06

Runs one allow-listed kct write command on the open board through the whole protocol (check, save, run, reload only on success) and reports each step and the command's result. See the handoff protocol.

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)

--timeout

OPENKONNECT_TIMEOUT

5

Bound on one IPC request (s)

--request-timeout

OPENKONNECT_REQUEST_TIMEOUT

2

Retries when KiCad is busy

--busy-retries

OPENKONNECT_BUSY_RETRIES

3

API socket

--socket

OPENKONNECT_SOCKET

discovered

Development

uv run ruff check . && uv run ruff format --check .
uv run pytest -rs

Unit 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-python bindings (MIT; see docs/ipc-client.md). No pcbnew SWIG 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 tools
board_summaryA
Read-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_selectionA
Read-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_handoffA
Destructive

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_statusA
Read-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_diskA
Destructive

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

    A4.3/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables 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.
      100
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      14
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to interact with KiCAD for PCB design automation, including schematic editing, component placement, routing, DRC/ERC, and export.
      100
      38 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      35
      3
      MIT