kicad-mcp
Summary: kicad-mcp gives coding agents a compact, read-only view of KiCad projects plus live editing of the board open in KiCad — no need to dump giant .kicad_pcb/.kicad_sch files into context.
Project & board overview —
project_info,board_summaryfor files, board size, layers, counts, design rules and netclasses.Component queries —
list_components(filters by ref/value/footprint/side/DNP),get_component(bbox, courtyard, fields, 3D model, pads/nets).Measurements & placement —
measure(distances between refs, pads, or points),neighbors,items_in_region.Nets & routing —
list_nets,net_info(pads, track lengths per layer, vias, zones, netclass).Search —
searchacross refs, values, fields, nets and silkscreen.Checks —
drc,erc, plusbomfor grouped bill of materials.Renders —
render_3d(PNG),render_layers(SVG/PNG of chosen layers).Schematic views —
schematic_summary,sch_components/sch_component,sch_nets/sch_net.Live editing (KiCad IPC) —
kicad_status,move_component(s),set_component_attributes,set_component_field,add_track,add_via,ripup_net,refill_zones,save_board,get_selection/select_components,live_component.
Provides tools for interacting with KiCad projects, including board measurements, component and net queries, DRC/ERC summaries, BOM generation, schematic inspection, renders, and board editing via KiCad's IPC API.
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., "@kicad-mcp Run a DRC on the open board and summarize the violations."
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.
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 |
| board geometry: footprints, pads, nets, tracks, zones, distances |
| DRC, ERC, netlist export, SVG/3D renders |
netlist XML (from | schematic symbols, pins, nets, BOM |
IPC API ( | 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 |
| files, board size/counts, schematic sheets. Start here. |
| outline, layers, counts, zones, design rules, netclasses |
| footprints with position/rotation/side; filters by ref/value/footprint/side/dnp |
| one footprint: bbox, courtyard, fields, 3D model, every pad with its net |
| distance between refs, pads ( |
| footprints within a radius, with courtyard gap and direction |
| pads, track length per layer, widths, vias, zones, netclass for one net |
| nets with pad count, routed length, via count |
| what lies in a rectangle, optionally on one layer |
| where a string appears: refs, values, fields, nets, silkscreen |
| counts per violation type; |
| PNG of the board (top/bottom/…) |
| SVG (+PNG on macOS) of chosen layers |
| sheets, symbol counts, nets, DNP |
| symbols; one symbol with every pin and its net |
| schematic nets and their pins |
| 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 |
| is the API reachable, which boards/schematics are open |
| absolute or relative move, rotate, flip, lock; batch is one undo step |
| DNP, exclude from BOM / position files, locked |
| value, datasheet or description text on the board footprint |
| draw segments through points on a layer for a net; place a via (netclass defaults) |
| delete a net's tracks (and vias), optionally one layer |
| read what the user selected; highlight parts for them |
| 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
UpdateItemsfrom the API message, and the children travel in absolute coordinates, so the client moves them. kicad-python'sposition/orientationsetters drop 3D models on rotation, never move text boxes or dimensions, and truncate (1 nm errors that DRC reports aslib_footprint_mismatch).kicad_mcp/fpgeom.pydoes 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_boardcompares 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
defaultstroke is saved assolid. The first two show up aslib_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_mcpor 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.pyRoadmap
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 toolsadd_trackADestructive
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_viaADestructive
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_summaryBRead-onlyIdempotent
Board overview: outline, layers, footprint/net/track/via counts, zones, design rules and netclasses.
Inputs: path. Returns: result
bomCRead-onlyIdempotent
Bill of materials grouped by value (and footprint): quantity, references, and part-number fields.
Inputs: path, include_dnp, group_by_footprint. Returns: result
drcARead-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
ercARead-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_componentARead-onlyIdempotent
Full detail for one footprint by reference: position, bbox, courtyard, fields, 3D model, every pad with net.
Inputs: ref, path. Returns: result
get_selectionARead-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_regionARead-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_statusARead-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_componentsARead-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_netsBRead-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_componentARead-only
Current position/rotation/side of a footprint as shown in the editor (including unsaved edits).
Inputs: ref, path. Returns: result
measureARead-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_componentADestructive
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_componentsADestructive
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
neighborsBRead-onlyIdempotent
Footprints within radius mm of a footprint, nearest first, with courtyard gap and direction.
Inputs: ref, path, limit, radius. Returns: result
net_infoARead-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_infoARead-onlyIdempotent
Overview of a KiCad project folder: files, board size and counts, schematic sheets. Start here.
Inputs: path. Returns: result
refill_zonesADestructive
Refill all copper zones in the open board (needed after moving parts or routing near zones).
Inputs: path. Returns: result
render_3dARead-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_layersARead-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_netADestructive
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_boardADestructive
Save the open board to disk so file-based tools (measure, drc, render...) see the edits.
Inputs: path. Returns: result
sch_componentBRead-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_componentsBRead-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_summaryARead-onlyIdempotent
Schematic overview from the exported netlist: sheets, symbol counts by prefix, nets, power nets, DNP parts.
Inputs: path. Returns: result
sch_netBRead-onlyIdempotent
All pins on a schematic net (exact, case-insensitive, or unique-substring name).
Inputs: net, path. Returns: result
sch_netsBRead-onlyIdempotent
Schematic nets with pin counts, largest first. filter is a case-insensitive substring.
Inputs: path, limit, filter. Returns: result
searchCRead-onlyIdempotent
Find where a string occurs on the board: references, values, footprint names, fields, net names, silkscreen text.
Inputs: path, limit, query. Returns: result
select_componentsADestructive
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_attributesBDestructive
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_fieldBDestructive
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
Scored across 33 tools
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.
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.
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.
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
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.
Verified KiCad footprints, symbols & 3D models for AI agents. No signup, CC-BY-4.0, quality-gated.
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
- FlicenseBqualityCmaintenanceEnables 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-