Skip to main content
Glama
kicad-mcp
by nmlsports

kicad-mcp

An MCP server that gives coding agents a compact view of KiCad projects (measurements, component and net queries, DRC/ERC summaries, BOM, and renders) without dumping 20k-line .kicad_pcb / .kicad_sch files into context, and lets them edit the board open in KiCad.

It does not reimplement KiCad. It sits on the four machine interfaces KiCad already ships:

Surface

Used for

pcbnew Python module (KiCad's bundled Python)

board geometry: footprints, pads, nets, tracks, zones, distances

kicad-cli

DRC, ERC, netlist export, SVG/3D renders

netlist XML (from kicad-cli sch export netlist)

schematic symbols, pins, nets, BOM

IPC API (kicad-python, running KiCad)

live board edits: move/rotate/flip, fields, tracks, vias, selection

Architecture

agent ──MCP stdio──> kicad_mcp/server.py   (Python 3.10+, mcp SDK)
                        ├─ worker_client ──JSON lines──> worker/board_worker.py  (KiCad's Python 3.9, imports pcbnew)
                        ├─ cli.py           ──subprocess──> kicad-cli  (DRC/ERC/netlist/render, cached by mtime)
                        ├─ netlist.py       parses the netlist XML
                        └─ edit_tools.py ── ipc.py ──socket──> running KiCad  (kicad-python; edits the open board)

The pcbnew module is compiled against KiCad's own Python (3.9 on macOS), and the MCP SDK needs 3.10+, so board queries run in a persistent worker subprocess under KiCad's interpreter. Boards are cached in the worker and reloaded when the file changes.

Related MCP server: pcb-mcp

Tools

All tools take path: a project directory, .kicad_pro, .kicad_pcb or .kicad_sch (default: current directory). Units are mm, KiCad coordinates (y down).

Tool

What it returns

project_info

files, board size/counts, schematic sheets. Start here.

board_summary

outline, layers, counts, zones, design rules, netclasses

list_components

footprints with position/rotation/side; filters by ref/value/footprint/side/dnp

get_component

one footprint: bbox, courtyard, fields, 3D model, every pad with its net

measure

distance between refs, pads (U7.3) or points (120,44): centre, dx/dy, edge gap

neighbors

footprints within a radius, with courtyard gap and direction

net_info

pads, track length per layer, widths, vias, zones, netclass for one net

list_nets

nets with pad count, routed length, via count

items_in_region

what lies in a rectangle, optionally on one layer

search

where a string appears: refs, values, fields, nets, silkscreen

drc / erc

counts per violation type; type= lists individual findings

render_3d

PNG of the board (top/bottom/…)

render_layers

SVG (+PNG on macOS) of chosen layers

schematic_summary

sheets, symbol counts, nets, DNP

sch_components / sch_component

symbols; one symbol with every pin and its net

sch_nets / sch_net

schematic nets and their pins

bom

grouped bill of materials with part-number fields

Editing tools (KiCad IPC API)

These change the board that is open in a running KiCad, through the official IPC API (kicad-python). Each call is one undo step in the editor. Nothing touches the file until save_board, so the file-based read tools see edits only after saving.

Tool

What it does

kicad_status

is the API reachable, which boards/schematics are open

move_component / move_components

absolute or relative move, rotate, flip, lock; batch is one undo step

set_component_attributes

DNP, exclude from BOM / position files, locked

set_component_field

value, datasheet or description text on the board footprint

add_track / add_via

draw segments through points on a layer for a net; place a via (netclass defaults)

ripup_net

delete a net's tracks (and vias), optionally one layer

get_selection / select_components

read what the user selected; highlight parts for them

refill_zones, save_board, live_component

housekeeping and live position lookup

Setup: in KiCad, Preferences → Preferences… → Plugins → Enable KiCad API, restart KiCad, open the board in the PCB editor. Only an open PCB editor registers the document handlers; the project manager alone answers "no handler available". The server tries KICAD_API_SOCKET, then the default socket (/tmp/kicad/api.sock), then per-process sockets (api-<pid>.sock) that standalone editors create, and picks the instance that has the requested board open. On macOS a board can be opened headlessly for an agent with open -n -a /Applications/KiCad/KiCad.app/Contents/Applications/pcbnew.app --args <file.kicad_pcb>.

Batches that both flip and move a part flip first and compute the move from the flipped item, because changes staged in an open commit are not visible to later calls until it is pushed.

Footprint edits and what KiCad 10.0.x's API loses:

  • KiCad rebuilds every footprint it receives through UpdateItems from the API message, and the children travel in absolute coordinates, so the client moves them. kicad-python's position/orientation setters drop 3D models on rotation, never move text boxes or dimensions, and truncate (1 nm errors that DRC reports as lib_footprint_mismatch). kicad_mcp/fpgeom.py does the move instead: it keeps every child, is exact for multiples of 90°, and uses KiCad's rounding otherwise. Footprints that end up where they were, such as a flip and flip back, are not sent at all.

  • The API message has no field for a footprint's (units ...) (symbol unit → pins, for gate swapping) or for pad fabrication properties (pad_prop_bga, ...). Any footprint edit drops them. save_board compares the saved file with the one it replaced (kicad_mcp/pcbfile.py), copies those blocks back (matched by UUID) and reloads the board in the editor, which clears its undo history. It warns about other lost footprint data (models, embedded files, groups...).

  • Cosmetic round-trip changes that remain (KiCad bugs): polygons lose a repeated closing point, keepout zones inside footprints get default min-thickness/thermal settings, and a default stroke is saved as solid. The first two show up as lib_footprint_mismatch; Update Footprints from Library clears them.

Schematic editing over IPC needs KiCad 11 (the kipy.schematic module is marked as such); KiCad 10 exposes only the board.

Install

Requires KiCad 9+ (tested with 10.0.6 on macOS) and Python 3.10+.

python3 -m venv .venv && .venv/bin/pip install -e .

Register with Claude Code (user scope, so it is available in every hardware project):

claude mcp add --scope user kicad -- /ABS/PATH/kicad-mcp/.venv/bin/python -m kicad_mcp

or add to ~/.claude.json:

{"mcpServers": {"kicad": {"type": "stdio", "command": "/ABS/PATH/kicad-mcp/.venv/bin/python", "args": ["-m", "kicad_mcp"]}}}

Environment overrides: KICAD_APP (macOS .app bundle), KICAD_CLI, KICAD_PYTHON (interpreter that can import pcbnew), KICAD_MCP_CACHE (default ~/.cache/kicad-mcp), KICAD_MCP_DEBUG=1 to print worker tracebacks to stderr.

Tests

KICAD_MCP_TEST_PROJECT=/path/to/a/kicad/project .venv/bin/pytest
# live editing tests, against a scratch copy open in the PCB editor:
KICAD_MCP_LIVE_PCB=/path/to/scratch/copy.kicad_pcb .venv/bin/pytest tests/test_live.py

Roadmap

  • Schematic editing once KiCad 11's IPC schematic API is available.

  • Region-cropped renders.

  • Live (unsaved) variants of measure / net_info over IPC.

License

MIT

Available Tools

33 tools
add_trackA
Destructive

Draw track segments through points (JSON list of [x, y] in mm) on layer for net. Width defaults to the net's netclass. No DRC is run; check with drc after saving.

Inputs: net, path, layer, width, +1 more. Returns: result

add_viaA
Destructive

Place a through via at (x, y) mm on net. Diameter/drill default to the netclass.

Inputs: x, y, net, path, +2 more. Returns: result

board_summaryB
Read-onlyIdempotent

Board overview: outline, layers, footprint/net/track/via counts, zones, design rules and netclasses.

Inputs: path. Returns: result

bomC
Read-onlyIdempotent

Bill of materials grouped by value (and footprint): quantity, references, and part-number fields.

Inputs: path, include_dnp, group_by_footprint. Returns: result

drcA
Read-onlyIdempotent

Run DRC (cached until the board changes). Without type: counts per violation type. With type: individual findings with positions. severity = error | warning. parity=true also checks against the schematic.

Inputs: path, type, limit, parity, +2 more. Returns: result

ercA
Read-onlyIdempotent

Run ERC on the schematic (cached until it changes). Without type: counts per type. With type: individual findings with sheet and position. severity = error | warning.

Inputs: path, type, limit, severity, +1 more. Returns: result

get_componentA
Read-onlyIdempotent

Full detail for one footprint by reference: position, bbox, courtyard, fields, 3D model, every pad with net.

Inputs: ref, path. Returns: result

get_selectionA
Read-only

What the user currently has selected in the PCB editor (footprints, tracks, vias...). Useful when they say "this part" or "these tracks".

Inputs: path. Returns: result

items_in_regionA
Read-onlyIdempotent

What lies inside a rectangle (mm corners): footprints, tracks per net/layer, vias, zones, text. Optional layer name (e.g. "F.Cu", "B.Silkscreen") restricts the answer.

Inputs: x1, x2, y1, y2, +2 more. Returns: result

kicad_statusA
Read-only

Is KiCad running with its API enabled, and which boards/schematics are open? Call before any editing tool. Editing tools work on the board open in the KiCad PCB editor.

Inputs: path. Returns: result

list_componentsA
Read-onlyIdempotent

List footprints on the board with position (mm), rotation, side. Filters are case-insensitive substrings, or globs if they contain * ? [ (e.g. ref="C*", value="10k", footprint="0402", side="F").

Inputs: dnp, ref, path, side, +4 more. Returns: result

list_netsB
Read-onlyIdempotent

Nets on the board with pad count, routed length and via count. sort = pads | length | name.

Inputs: path, sort, limit, filter. Returns: result

live_componentA
Read-only

Current position/rotation/side of a footprint as shown in the editor (including unsaved edits).

Inputs: ref, path. Returns: result

measureA
Read-onlyIdempotent

Distance between two items. Each of a/b is a footprint ref ("U7"), a pad ("U7.3" or "J1:A6"), or a point in mm ("120.5,44"). Returns dx/dy, centre distance, compass direction, and edge-to-edge gap (courtyard-to-courtyard for footprints, copper-to-copper for pads).

Inputs: a, b, path. Returns: result

move_componentA
Destructive

Move/rotate/flip one footprint in the open board (one undo step). x/y set an absolute position in mm; dx/dy nudge relative to it; rotation sets degrees, rotate_by adds; flip moves it to the other side.

Inputs: x, y, dx, dy, +5 more. Returns: result

move_componentsA
Destructive

Move several footprints as one undo step. moves is a JSON list of objects with keys ref (required) and any of x, y, dx, dy, rotation, rotate_by, flip, locked. Example: [{"ref":"C1","x":120.5,"y":44,"rotation":90},{"ref":"R2","dx":-1.27}]

Inputs: path, moves. Returns: result

neighborsB
Read-onlyIdempotent

Footprints within radius mm of a footprint, nearest first, with courtyard gap and direction.

Inputs: ref, path, limit, radius. Returns: result

net_infoA
Read-onlyIdempotent

Everything on one net: pads (with pin names), track length per layer, widths, vias, zones, netclass rules. Net name may be exact, case-insensitive, or a unique substring.

Inputs: net, path. Returns: result

project_infoA
Read-onlyIdempotent

Overview of a KiCad project folder: files, board size and counts, schematic sheets. Start here.

Inputs: path. Returns: result

refill_zonesA
Destructive

Refill all copper zones in the open board (needed after moving parts or routing near zones).

Inputs: path. Returns: result

render_3dA
Read-onlyIdempotent

Render the board to a PNG (raytraced-lite) and return its path so you can view it. side = top | bottom | left | right | front | back. zoom > 1 magnifies the centre.

Inputs: path, side, zoom, output. Returns: result

render_layersA
Read-onlyIdempotent

2D plot of chosen layers (comma-separated, e.g. "F.Cu,F.Silkscreen,Edge.Cuts") fitted to the board. Returns the SVG path and, on macOS, a PNG path you can view. mirror=true for looking at the bottom.

Inputs: path, layers, mirror, output. Returns: result

ripup_netA
Destructive

Delete all tracks (and vias unless vias=false) of a net, optionally only on one layer. Undoable in the editor.

Inputs: net, path, vias, layer. Returns: result

save_boardA
Destructive

Save the open board to disk so file-based tools (measure, drc, render...) see the edits.

Inputs: path. Returns: result

sch_componentB
Read-onlyIdempotent

One schematic symbol: fields, library part, sheet, and every pin with the net it is on (blank = unconnected).

Inputs: ref, path. Returns: result

sch_componentsB
Read-onlyIdempotent

List schematic symbols with value, footprint, sheet and DNP flag. Filters are substrings or globs.

Inputs: ref, path, limit, sheet, +1 more. Returns: result

schematic_summaryA
Read-onlyIdempotent

Schematic overview from the exported netlist: sheets, symbol counts by prefix, nets, power nets, DNP parts.

Inputs: path. Returns: result

sch_netB
Read-onlyIdempotent

All pins on a schematic net (exact, case-insensitive, or unique-substring name).

Inputs: net, path. Returns: result

sch_netsB
Read-onlyIdempotent

Schematic nets with pin counts, largest first. filter is a case-insensitive substring.

Inputs: path, limit, filter. Returns: result

select_componentsA
Destructive

Select footprints in the PCB editor so the user can see which ones you mean. refs is a JSON list of references. add=true keeps the existing selection.

Inputs: add, path, refs. Returns: result

set_component_attributesB
Destructive

Set DNP / exclude-from-BOM / exclude-from-position-files / locked flags on a footprint.

Inputs: dnp, ref, path, locked, +2 more. Returns: result

set_component_fieldB
Destructive

Set the value, datasheet or description text of a footprint on the board (not the schematic).

Inputs: ref, path, field, value. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools map cleanly to a distinct resource and action, with clear board-vs-schematic prefixes (list_components vs sch_components, net_info vs sch_net). A few overlaps exist—project_info/board_summary both report board counts, and live_component/get_component both describe a footprint—but the descriptions resolve the boundaries.

    Naming Consistency4/5

    The set uses consistent snake_case and useful prefixes: list_/get_ for reads, sch_ for schematic tools, and move_/set_/add_/ripup_ for edits. It deviates with bare acronyms and noun-only names like erc, drc, bom, board_summary, and kicad_status, but the overall pattern remains predictable.

    Tool Count2/5

    33 tools exceeds the 25+ threshold and makes agent tool selection noticeably harder. The breadth reflects KiCad's complexity, but several summary/query tools could be consolidated without losing capability.

    Completeness3/5

    The toolset thoroughly covers board/schematic inspection, selection, rendering, ERC/DRC, BOM, and common layout edits. Gaps remain: there is no component creation/deletion, no schematic editing, and track editing is limited to adding segments or ripping up whole nets rather than editing existing tracks.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    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
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI agents to create and edit real KiCad schematics and projects, run ERC/DRC validation, generate BOMs, and produce schematic/PCB/3D renders via kicad-cli, with SKiDL support and automatic backups.
      28
      -