Report whether KiCad is reachable, its version, and which documents are open.

Use this first to confirm connectivity before other operations.

Return the connected KiCad version and the kicad-python API version.

Ping the KiCad API server. Returns 'pong' on success.

List all documents currently open in KiCad, grouped by type.

Save the currently open PCB to disk.

Save a copy of the open PCB to a new path.

Args: file_path: Destination .kicad_pcb path. overwrite: Overwrite if the file already exists. include_project: Also write the associated project file.

Discard unsaved changes and reload the open PCB from disk.

Run an arbitrary KiCad tool action by name (power user / unstable API).

Example actions: 'pcbnew.InteractiveRouter.routeSingleTrack', 'pcbnew.EditTool.Rotate', 'common.Control.zoomFitScreen'. Action names are not guaranteed stable across KiCad versions and may have side effects.

Args: action: The KiCad TOOL_ACTION name to invoke.

Return the full path to a bundled KiCad binary (e.g. 'kicad-cli').

Args: binary_name: Short binary name; '.exe' is assumed on Windows.

Return counts and basic metadata for the open PCB.

Includes element counts, copper layer count, board file name, and bounding box extents in millimetres.

List footprints on the open PCB.

Args: reference_filter: Case-insensitive substring match on the reference (e.g. 'R', 'U1'). value_filter: Case-insensitive substring match on the component value. include_pads: Include each footprint's pads (number, net, position).

Return full detail for a single footprint by reference designator.

Args: reference: Reference designator, e.g. 'U1'. include_pads: Include the footprint's pads.

List pads on the board, optionally filtered by footprint reference or net.

Args: reference: Only pads belonging to this footprint reference. net_filter: Case-insensitive substring match on the pad's net name.

List copper tracks and arc tracks on the board.

Args: layer: Restrict to a layer name, e.g. 'F.Cu'. net_filter: Case-insensitive substring match on the net name.

List vias on the board, optionally filtered by net.

List copper zones, rule areas, and graphic zones on the board.

List graphic shapes (lines, arcs, circles, rectangles, polygons) on the board.

Args: layer: Restrict to a layer name, e.g. 'Edge.Cuts' for the board outline.

Return all graphic shapes on the Edge.Cuts layer (the board outline).

List free text and text-box objects on the board.

List dimension annotations on the board.

List item groups on the board with their member item IDs.

Return KiCad-computed bounding boxes for the given item IDs.

Args: item_ids: Item KIID strings (from any list_* tool). include_text: Include child reference/value text in footprint boxes.

Move a footprint to an absolute position, optionally setting its rotation.

Args: reference: Reference designator, e.g. 'R1'. x_mm: Target X in millimetres. y_mm: Target Y in millimetres. angle_deg: Optional absolute rotation in degrees.

Set a footprint's absolute rotation in degrees.

Args: reference: Reference designator, e.g. 'U1'. angle_deg: Absolute angle in degrees (0, 90, 180, 270, ...).

Lock or unlock a footprint.

Args: reference: Reference designator. locked: True to lock, False to unlock.

Set the value field text of a footprint (e.g. '10k', '100nF').

Args: reference: Reference designator. value: New value string.

Move/rotate several footprints in a single undo step.

Args: moves: List of objects with keys 'reference', 'x_mm', 'y_mm', and optional 'angle_deg'. Example: [{"reference": "R1", "x_mm": 100, "y_mm": 95}, {"reference": "C1", "x_mm": 102, "y_mm": 95, "angle_deg": 90}]

Lock or unlock arbitrary board items by ID.

Args: item_ids: Item KIID strings. locked: True to lock, False to unlock.

Delete board items by their KIID strings (single undo step).

Args: item_ids: Item KIID strings from any list_* tool.

Select board items by ID in the PCB editor.

Args: item_ids: Item KIID strings. add_to_existing: Keep the current selection and add to it.

Clear the current selection in the PCB editor.

Return the items currently selected in the PCB editor (id + type).

Position, rotation, side, courtyard box, and every pad (number, net, position, size) of one footprint. Use this before placing or routing around a part.

Args: reference: Reference designator, e.g. 'U1'.

Place a footprint at an offset from another footprint's origin.

Args: reference: Footprint to move. anchor_reference: Footprint to measure from. dx_mm, dy_mm: Offset in mm (Y grows downward). angle_deg: Optional absolute rotation for the moved part.

Place a part right next to a specific pad, just outside the target part's courtyard and aligned with the pad. Ideal for decoupling capacitors, pull-ups, and series resistors.

Args: reference: Footprint to move, e.g. 'C3'. target_reference: Part that owns the pad, e.g. 'U2'. target_pad: Pad number on the target, e.g. '13'. side: 'left', 'right', 'up', 'down', or 'auto' (the courtyard edge nearest the pad). gap_mm: Courtyard-to-courtyard gap in mm. angle_deg: Optional absolute rotation for the moved part (applied first). auto_orient: If the moved part has a pad on the target pad's net, turn it 180 degrees when that makes the same-net pad face the target (so the connecting track doesn't cross the part's other pad).

Place a part against a board edge (connectors, sensors, switches).

Args: reference: Footprint to move. edge: 'left', 'right', 'top', or 'bottom' edge of the board outline. inset_mm: Distance from the board edge to the part's courtyard. along_mm: Absolute coordinate along the edge (X for top/bottom, Y for left/right). Defaults to the middle of that edge. angle_deg: Optional absolute rotation (applied first).

Line several parts up in a row or column in one undo step.

Args: references: Parts in order, e.g. ['R1', 'R2', 'R3']. start_x_mm, start_y_mm: Origin of the first part. pitch_mm: Fixed origin-to-origin spacing. If omitted, parts are packed courtyard-to-courtyard with gap_mm between them. direction: 'x' (row, left to right) or 'y' (column, top to bottom). gap_mm: Gap used when pitch_mm is omitted. angle_deg: Optional absolute rotation applied to every part.

Move a footprint to the other side of the board (front <-> back), mirrored in place.

Args: reference: Footprint to flip.

Score the current placement: courtyard overlaps, parts off the board, and total airwire (ratsnest) length. Lower airwire length usually means easier routing; compare before/after when moving parts.

Args: exclude_nets: Nets to ignore in the airwire total, typically ['GND'] when a ground pour will connect it. top_airwires: How many of the longest airwires to list.

Add a straight copper track segment. Prefer route_pads (connect pads by name) or add_track_path (multi-segment) - they avoid hand-copied coordinates.

Args: start_x_mm, start_y_mm: Start point in mm. end_x_mm, end_y_mm: End point in mm. width_mm: Track width in mm; default is the net's netclass width. layer: Copper layer name, e.g. 'F.Cu' or 'B.Cu'. net_name: Net to assign (must exist on the board).

Add a curved (arc) copper track defined by start, mid, and end points.

Args: start_x_mm, start_y_mm: Arc start in mm. mid_x_mm, mid_y_mm: A point on the arc between start and end, in mm. end_x_mm, end_y_mm: Arc end in mm. width_mm: Track width in mm. layer: Copper layer name. net_name: Optional net to assign.

Add a through via at a position, sized from the net's netclass by default, and report clearance problems with other nets on the outer layers.

Args: x_mm, y_mm: Via centre in mm. diameter_mm: Copper diameter in mm; default from netclass. drill_mm: Drill diameter in mm; default from netclass. net_name: Net to assign (must exist on the board).

Add a copper zone (filled pour) bounded by a polygon outline.

Args: points: Outline vertices, each {"x_mm": .., "y_mm": ..} or [x, y]. >= 3 points. layers: Layer names the zone exists on, e.g. ['F.Cu']. net_name: Net to connect the pour to (e.g. 'GND'). Empty for no net. name: Optional zone name. priority: Fill priority (higher fills first). refill: Refill all zones after creating (slower, reflects in editor).

Add a rectangular copper zone (convenience wrapper around add_zone).

Args: x_min_mm, y_min_mm: Top-left corner in mm. x_max_mm, y_max_mm: Bottom-right corner in mm. layers: Layer names, e.g. ['F.Cu']. net_name: Net to connect (e.g. 'GND'). name: Optional zone name. priority: Fill priority. refill: Refill zones after creating.

Refill (recompute) all copper zones on the board. May take a few seconds.

Add a graphic line segment (silkscreen, fab, Edge.Cuts, etc.).

Args: start_x_mm, start_y_mm: Start point in mm. end_x_mm, end_y_mm: End point in mm. layer: Layer name, e.g. 'F.SilkS' or 'Edge.Cuts'. width_mm: Line width in mm.

Add a graphic rectangle.

Args: x_min_mm, y_min_mm: Top-left corner in mm. x_max_mm, y_max_mm: Bottom-right corner in mm. layer: Layer name. width_mm: Outline width in mm. filled: Whether the rectangle is solid-filled.

Add a graphic circle.

Args: center_x_mm, center_y_mm: Centre in mm. radius_mm: Radius in mm. layer: Layer name. width_mm: Outline width in mm. filled: Whether the circle is solid-filled.

Add a graphic arc defined by start, mid, and end points.

Args: start_x_mm, start_y_mm: Arc start in mm. mid_x_mm, mid_y_mm: Point on the arc, in mm. end_x_mm, end_y_mm: Arc end in mm. layer: Layer name. width_mm: Outline width in mm.

Add a graphic polygon.

Args: points: Vertices, each {"x_mm": .., "y_mm": ..} or [x, y]. >= 3 points. layer: Layer name. width_mm: Outline width in mm. filled: Whether the polygon is solid-filled.

Add a rectangular board outline on the Edge.Cuts layer.

Args: x_min_mm, y_min_mm: Top-left corner in mm. x_max_mm, y_max_mm: Bottom-right corner in mm. width_mm: Outline width in mm.

Add free text to the board.

Args: text: The text string. x_mm, y_mm: Anchor position in mm. layer: Layer name, e.g. 'F.SilkS'. size_mm: Glyph height (and width) in mm. thickness_mm: Stroke thickness in mm. angle_deg: Rotation in degrees.

Route a track between two pads by name - no coordinates needed.

Looks up both pads, takes the net from them, uses the netclass track width unless overridden, draws a 45-degree (or orthogonal) path, and then reports clearance conflicts with other nets. A power track wider than a fine-pitch pad is necked down where it leaves the pad (see 'necks' in the result).

Args: from_reference, from_pad: Start pad, e.g. 'U2', '7'. to_reference, to_pad: End pad, e.g. 'J3', '1'. layer: Copper layer. Empty = a layer both pads share (F.Cu preferred). width_mm: Track width; default is the net's netclass width. style: '45' (default), 'manhattan' (90-degree), or 'direct' (straight line). bend: 'straight_first' or 'diagonal_first' - which end gets the bend. via_at: [x_mm, y_mm] to change layer through a via on the way. Required when the pads have no copper layer in common (e.g. one SMD on each side); if omitted in that case the via goes at the midpoint. to_layer: Layer after the via (default: the other outer layer). rollback_on_conflict: Undo the whole route if any clearance problem is found. neck_down: Where the full width would hit the part's other pins, run the stretch next to the pad at the widest width that fits (at most the pad's size) and widen once clear.

Draw a connected multi-segment track through a list of points in one step, then check both ends are connected and nothing is too close.

Args: points: Vertices, each [x, y] or {"x_mm":.., "y_mm":..}; at least 2. net_name: Net to assign (must exist; e.g. 'GND', '/MOTOR_A'). layer: Copper layer name. width_mm: Track width; default is the net's netclass width. rollback_on_conflict: Undo the path if any clearance problem is found.

Quick clearance check of tracks against other nets' copper (tracks, vias, pads), using each net's netclass clearance. Pass track IDs to check just those, or nothing to check every track. Approximate - run_drc is authoritative.

Args: item_ids: Track KIIDs to check; empty = all tracks on the board.

Report whether autorouting can run: Java version, installed Freerouting jars, and KiCad's Python (needed for DSN/SES conversion).

Download the official Freerouting release jar from GitHub into ~/.kicad10_mcp/freerouting. 'auto' picks the newest release the installed Java can run (2.4.1 on Java 25+, 2.1.0 on Java 21-24). Freerouting is GPL-3.0 and runs as a separate program.

Args: version: 'auto' or an explicit release such as '2.1.0'.

Route the remaining connections with Freerouting.

Typical flow: set net classes (configure_netclasses), route or pour the high-current nets yourself, then autoroute the rest with those classes in skip_netclasses. Existing tracks are locked so they are not moved.

With the board open in KiCad it is saved, backed up (.pre-autoroute.kicad_pcb), routed on disk, and reloaded into the editor - that replaces the editor's undo history, so the backup is the way back. Afterwards zones are refilled and DRC runs; always read 'drc_after' (copper text and some keepouts are invisible to Freerouting).

Args: max_passes: Autorouter pass limit (honoured by Freerouting 2.2+). timeout_s: Hard limit for the Freerouting run, in seconds. lock_existing: Keep existing tracks exactly where they are. skip_netclasses: Net classes Freerouting must not route, e.g. ['HighCurrent']. board_file: Route this .kicad_pcb on disk instead of the open board.

List all nets on the board, optionally filtered by net class name.

Args: netclass_filter: Restrict to nets belonging to this net class.

List the project's net classes and their key parameters (mm).

Summarise every board item belonging to a net (counts by type + IDs).

Args: net_name: The net name, e.g. 'GND'.

Find items copper-connected to a given item (by KIID).

Args: item_id_str: KIID string of the source track/via/pad.

Report copper layer count plus enabled, visible, and active layers (names).

Set the active drawing layer in the PCB editor.

Args: layer: Layer name, e.g. 'B.Cu'.

Set exactly which layers are visible in the editor.

Args: layers: Full list of layer names to make visible (others are hidden).

Set the number of copper layers (must be even, >= 2).

WARNING: removing layers deletes any content on them and cannot be undone. Pass confirm=True to proceed.

Args: count: New copper layer count. confirm: Must be True to apply the change.

Return the board stackup: ordered layers with type, thickness, material.

Return the board's minimum design-rule constraints in mm (best effort).

Falls back to an explanatory message if the running KiCad build does not expose design rules over the API.

IPC-2221 minimum track width for a current, plus resistance and voltage drop when a length is given.

Args: current_a: Continuous (or worst-case, e.g. motor stall) current in amps. temp_rise_c: Allowed temperature rise above ambient (10 C is conservative). copper_oz: Copper weight (1 oz = 35 um is the usual default). internal_layer: True for inner layers (they cool worse, need ~2.5x width). length_mm: Optional track length to report resistance, drop, and loss.

Read net classes and net-to-class patterns from the project file (works with KiCad closed). list_netclasses reads the live values from a running KiCad.

Args: project_path: .kicad_pro file or its folder; default = project of the open board.

Create/update net classes and assign nets to them in the .kicad_pro file. Widths can be derived from current (IPC-2221) instead of fixed numbers.

The project must be CLOSED in KiCad (both editors): KiCad keeps project settings in memory and would overwrite this change on its next save. Reopen it afterwards and the nets pick up their classes.

Args: classes: One object per class, e.g. [{"name": "Power", "current_a": 1.5, "nets": ["+5V", "VMOT"]}, {"name": "Motor", "current_a": 2.5, "nets": ["AO1", "AO2"]}, {"name": "Signal", "track_width_mm": 0.25, "nets": ["/*"]}] Keys: name (required); nets (names or KiCad wildcard patterns - plain names also match their '/NAME' root-sheet form); current_a (sizes the track via IPC-2221) or track_width_mm; clearance_mm; via_diameter_mm; via_drill_mm; priority (lower wins when patterns overlap). project_path: .kicad_pro file or its folder; default = project of the open board. temp_rise_c: Temperature rise used for current-based widths. copper_oz: Copper weight used for current-based widths. replace_patterns: Drop all existing net-class patterns first.

Estimate how much current every supply net carries, from the schematic, and suggest track widths / net classes. Works for any kind of board.

Reads the saved schematic via kicad-cli (save it first). Parts are looked up in the current database; regulators, drivers, and series parts (fuse, diode, switch, inductor, 0-ohm) propagate current from loads back to the source.

Returns 'questions' when information is missing - answer them and run again:

• unknown_parts: open the part's 'datasheet' link (taken from the KiCad symbol; about half of vendor sites allow automated download - if it fails, search the web for " datasheet"), read the supply/output current figures, then call set_part_current with the URL as source. 'rating_hint' is only a pointer from the symbol description.

• unknown_connectors: ask the user what is plugged in (and its worst-case current, e.g. motor stall), then pass it in external_loads. Values from the built-in database are flagged in 'unverified_parts' until checked against a datasheet.

Args: schematic_path: .kicad_sch / .kicad_pro / project folder; default = project of the open board. external_loads: What hangs off connectors (or any part), by reference: {"J2": 2.5} or {"J2": {"typ_a": 0.4, "max_a": 2.5, "note": "motor stall"}}. Current is charged to every non-ground net the part touches; restrict with "pins": ["1"] (e.g. only the supply pin of a 3-pin servo header). sources: References of the supply inputs (battery/power connectors). Default: batteries, USB/barrel jacks, and connectors named like BAT/PWR/SUPPLY. net_voltages: Voltages for nets whose name doesn't say it, e.g. {"/VMOT": 7.4}; used for switching regulators and linear-regulator dissipation. temp_rise_c: Temperature rise for the width suggestions. copper_oz: Copper weight for the width suggestions.

Save a part's current data (from its datasheet) to the user part database so analyze_power_budget can use it. Always cite where the numbers came from.

Args: part: Symbol name as in KiCad (e.g. 'TB6612FNG'); also used as the match pattern unless entry has "match": [...] (wildcards allowed). entry: Behaviour description; any of: "supply": [{"pins": ["VCC"], "typ_a": 0.0015, "max_a": 0.0022}] "regulators": [{"in_pins": ["VIN"], "out_pins": ["VOUT"], "type": "linear"|"buck", "vout": 3.3, "efficiency": 0.9, "max_out_a": 1.0}] "drivers": [{"supply_pins": ["VM"], "channels": [["OUT1", "OUT2"]], "max_continuous_a": 1.2, "max_peak_a": 3.2}] Pin names must match the KiCad symbol's pin names. source: Datasheet URL (and page/table) the numbers came from. verified: False if the numbers are estimates rather than datasheet values.

List parts the power budget knows about (built-in and user-added).

Args: filter: Optional case-insensitive substring to filter part names.

Return the open project's name and path.

Return the project's text variables (used in ${VAR} substitutions).

Set (or add) one project text variable, merging with existing variables.

Args: name: Variable name (referenced as ${name}). value: Variable value.

Expand ${...} text variables in a string using the project's values.

Args: text: Text possibly containing ${VAR} references.

Return the board's title block fields (title, date, revision, company, comments).

Update title block string fields on the board.

Args: fields: Map of field name to value, e.g. {"title": "My Board", "revision": "B", "company": "Acme", "date": "2026-05-23"}. Valid field names are returned by get_title_block.

Return counts of symbols, labels, text, lines, and sheets in the open schematic.

List symbol instances in the open schematic (reference, value, position).

Note: requires KiCad's schematic symbol API (KiCad 11+); on KiCad 10 this may return an error — fall back to execute_kipy or read the .kicad_sch file.

List labels (local/global/hierarchical) in the open schematic.

List free text objects in the open schematic.

Return the sheet hierarchy of the open schematic (KiCad 11+ feature).

Add a free text object to the open schematic.

Args: text: Text string. x_mm, y_mm: Position in mm.

Add a local net label to the open schematic.

Args: text: Label text (the net name). x_mm, y_mm: Position in mm.

Save the open schematic to disk.

Run an arbitrary kicad-cli command (escape hatch for any export).

Args: args: Argument list after the binary, e.g. ["pcb", "export", "gerbers", "board.kicad_pcb", "-o", "out/"] or ["version"]. Use the currently open board's path from get_board_summary.

Export Gerber files for the open PCB into a directory.

Args: output_dir: Destination directory (created if needed). layers: Optional comma-separated layer list, e.g. 'F.Cu,B.Cu,Edge.Cuts'. Empty exports all enabled plottable layers. save_first: Save the board before exporting.

Export drill files (Excellon) for the open PCB into a directory.

Args: output_dir: Destination directory (created if needed). save_first: Save the board before exporting.

Export a 3D STEP model of the open PCB.

Args: output_path: Destination .step/.stp file. save_first: Save the board before exporting.

Export a PDF plot of selected PCB layers.

Args: output_path: Destination .pdf file. layers: Comma-separated layers to plot. save_first: Save the board before exporting.

Export an SVG plot of selected PCB layers.

Args: output_path: Destination .svg file. layers: Comma-separated layers to plot. save_first: Save the board before exporting.

Export a component placement (pick-and-place) file.

Args: output_path: Destination file. fmt: 'csv', 'ascii', or 'gerber'. side: 'front', 'back', or 'both'. save_first: Save the board before exporting.

Render a 3D image (PNG) of the open PCB.

Args: output_path: Destination .png file. side: 'top', 'bottom', 'left', 'right', 'front', 'back'. width, height: Image dimensions in pixels. save_first: Save the board before rendering.

Run Design Rule Check on the open PCB and summarise the results.

Args: output_path: Optional .json report path (a temp file is used if empty). save_first: Save the board before checking. refill_zones: Refill zones first (in the editor too when saving) - stale fills after routing show up as false clearance errors.

Export a bill of materials (CSV) from the open schematic.

Args: output_path: Destination .csv file. schematic_path: Explicit .kicad_sch path (defaults to the open project's). save_first: Save the schematic before exporting.

Export a netlist from the open schematic.

Args: output_path: Destination netlist file (e.g. .net). schematic_path: Explicit .kicad_sch path (defaults to the open project's). save_first: Save the schematic before exporting.

Run Electrical Rule Check on the open schematic and summarise the results.

Args: output_path: Optional .json report path (a temp file is used if empty). schematic_path: Explicit .kicad_sch path (defaults to the open project's). save_first: Save the schematic before checking.

Return a PNG picture of the open board (top view) to check placement and routing visually. Front copper is red, back copper blue, zone fills are tinted in their layer's colour, courtyards are grey (front) / purple (back) boxes labelled with references, airwires are yellow.

Args: side: 'both', 'front', or 'back' - which side's parts and copper to draw. show_ratsnest: Draw airwires for connections that copper (tracks, vias, zone fills) does not make yet. ratsnest_exclude_nets: Nets to leave out of the airwires, e.g. ['GND']. highlight_net: Draw this net's pads, tracks, and airwires in green. width_px: Image width in pixels (height follows the board's aspect ratio). show_zones: Draw copper zone fills (refill_zones first if they are stale).

Run arbitrary Python against the live KiCad session (FULL-CONTROL escape hatch).

Use this for anything not covered by a dedicated tool. The code runs in-process with these names pre-bound:

• kicad: connected kipy.KiCad instance

• board: the open Board, or None if no PCB is open

• schematic: the open Schematic, or None

• kipy, board_types, geometry, commit

• Vector2, Angle, BoardLayer, KiCadObjectType

Conventions:

• Internal units are nanometres; build points with Vector2.from_xy_mm(x, y).

• Group board edits in a single undo step: with commit(board, "my change"): board.create_items(item)

• Assign a variable named result to return structured data; anything printed to stdout is also captured.

Args: code: Python source to execute. autosave: If True and a board is open, save it after the code runs.

Example: code = ''' from kipy.board_types import Track from kipy.geometry import Vector2 t = Track() t.start = Vector2.from_xy_mm(10, 10) t.end = Vector2.from_xy_mm(20, 10) t.width = 250000 # 0.25 mm in nm t.layer = BoardLayer.BL_F_Cu with commit(board, "api track"): created = board.create_items(t) result = [c.id.value for c in created] '''