Kicad Pcb

KiCAD PCB Layout Workflow

This skill guides Claude to perform PCB layout using Konnect MCP tools. ALL modifications go through MCP tools — never edit .kicad_pcb files directly.

Prerequisites

Most PCB layout operations require KiCAD to be running with the board file open. The IPC connection communicates with the running KiCAD instance in real-time.

Some board-construction and component tools have guarded closed-board paths. IPC-first tools fall back to the file only when the transport is unreachable and the target board has not been observed live during this server session. These paths use revision-aware atomic writes: placement preserves pads, graphics, attributes, and models; moves preserve the existing angle; rotations update the footprint and its child angles; the closed-board flip fallback mirrors supported geometry and swaps front/back layers, refusing any 3D model whose offset/rotation it cannot transform. On KiCad 10.0.6+, flip_component prefers KiCad's own native FlipItems IPC command instead, which handles that 3D-model transform correctly — the file fallback only applies when no live KiCad holds the board. A reachable KiCad that predates 10.0.6 returns the structured error unsupported_capability; every reachable rejection stays closed instead of racing the editor with a file edit.

unsafe_file_fallback is a stop condition. It means Konnect reached this board live earlier in the current server session but IPC is now unreachable, so the saved file may be older than lost editor state. Pause mutation work, tell the user that Konnect left the file unchanged, and ask them to reopen/recover, reconcile, and save the board in KiCad. A read-only tool taking board_source can return the same kind, where nothing was going to be written: reporting the saved file as current would be the unsafe act. There, board_source: "saved" inspects that snapshot deliberately and says what it excludes — offer it instead of retrying the default. Continue through live IPC afterward. Preserve the guard: do not retry-loop, restart Konnect automatically, or edit .kicad_pcb directly. If the user confirms a clean close and an authoritative saved file, they may restart Konnect to deliberately begin a new closed-board session.

If connection fails:

• Tell the user to open KiCAD and load the project
• The board (.kicad_pcb) must be open in the PCB editor
• KiCAD's IPC API must be enabled (default in KiCAD 8+)

Toolset Loading

Before any PCB work, load the required toolsets:

load_toolset('pcb_board')        # board outline, layers, setup, stackup
load_toolset('pcb_components')   # place, refresh, move, rotate, align footprints
load_toolset('pcb_routing')      # traces, vias, differential pairs
load_toolset('sch_export')       # update PCB from the saved schematic hierarchy

Zones (pcb_board: add_zone; pcb_routing: add_copper_pour), component/net queries (pcb_components: find_component, get_component_list; pcb_board: get_board_info), and bulk placement (pcb_components: place_component_array, align_components, duplicate_component) are already covered by the toolsets loaded above.

Load additional toolsets as needed:

load_toolset('config')           # design rule storage: add_design_rule, list_design_rules
load_toolset('verification')     # run_drc, rules/sizes, check_clearance (explicit anchor/courtyard mode)

Always call get_active_toolsets() first to see what is already loaded.

References by decision

• Read references/layer-reference.md when selecting a copper, fabrication, user, or mechanical layer or deciding which side owns an item.
• Read references/trace-width-table.md when sizing a current-carrying trace, via, or controlled-impedance route. It defines the required calculation inputs and acceptance record; it is not a lookup table.
• Read references/design-rules.md when creating netclasses, configuring project constraints, or adjudicating DRC results.

Layout Order

Follow this sequence for a clean PCB workflow:

1. Board outline — set_board_size or draw Edge.Cuts geometry. Both outline tools append, so resize with delete_graphics(layer='Edge.Cuts') first — a second call without it leaves two overlapping outlines and a DRC failure.
2. Update from schematic — call update_pcb_from_schematic first with dry_run: true. Review status, coverage, diagnostics, and staged positions. Apply only with dry_run: false and the exact returned expected_plan_revision value. The saved schematic hierarchy must be closed in the schematic editor, and the target board must be open in KiCad. A conflict is non-mutating; resolve it and rerun the dry run. A diagnostic about a library footprint names that footprint and every part that needs it: when the footprint cannot be placed (custom-shape pads are not supported), assign those parts a footprint without them; when the schematic connects a pad the footprint does not have, fix the symbol or the footprint choice. A successful apply is one KiCad undo entry, so Ctrl-Z reverses the whole update.
3. Refresh changed libraries — when a linked footprint library changed, use update_footprints_from_library, the MCP equivalent of KiCad Tools → Update Footprints from Library. This is distinct from update_pcb_from_schematic: it refreshes supported library-owned pads, graphics, attributes, metadata, and 3D models without changing references, placement, side, rotation, KIID, symbol metadata, instance overrides, or pad nets. Always call it first with dry_run: true; apply only with dry_run: false and the exact returned expected_plan_revision. The requested board must be open in live KiCad, one apply is one undo entry, and unsupported or stale content returns a non-mutating conflict instead of silently dropping it.
4. Place components — position all footprints
5. Route traces — connect all nets
6. Copper pour — add ground/power zones last
7. DRC — run design rule check
8. Save — save_project

Do NOT add copper pours before routing is complete — they interfere with interactive routing.

Placement

Strategy

• Group components by functional block (power, digital, analog, connectors)
• Place ICs first, then their associated passives
• Decoupling caps: within 2mm of their IC power pins, on same layer
• Cable/EMI filter caps: on the connector's own pins, and judged against that connector rather than the nearest IC
• Connectors: at board edges, accessible for cables
• High-frequency components: minimize trace lengths between them
• Thermal considerations: power components away from sensitive analog

Placement Tools

Bounded AI-directed placement loop

Load load_toolset('sch_analysis'), load_toolset('placement'), and load_toolset('verification'). Complete placement through this ordered loop; a proposed coordinate or a successful tool call is not evidence that the requested board now has the intended placement:

1. Recover intent and name the scope. Read the schematic, connectivity, and current board. Identify the functional reason for each move and list the exact footprint references that may move. Do not infer a capacitor-to-IC relationship from GND alone; use score_placement.decoupling_associations as supporting evidence and treat unproven_decoupling_caps as unresolved intent.
2. Build the held set. Include every caller-identified intentional placement. A diagnostic auto_place_from_schematic dry-run reports saved-board lock records in its held list; accept those only when that saved file is known current. get_component_list does not expose lock state, so if neither current saved evidence nor the caller establishes the KiCad-locked references, report BLOCKED and ask the caller to confirm them. Never send a held reference to move_component or rotate_component.
3. Plan a small explicit batch. Prefer one functional group and the fewest references needed to test the improvement. auto_place_from_schematic is a deprecated diagnostic planner only: its plan is always blocked from apply. refine_placement_force_directed is also deprecated; do not weaken its gates or apply a score tie. Make a justified score-neutral change with explicit moves instead.
4. Apply only the named moves. Use move_component and rotate_component; do not turn a diagnostic whole-board plan into an autonomous bulk mutation.
5. Read back the exact requested live board. After every batch, call get_component_list for that board and verify each requested reference's observed position, rotation, and layer. Call get_board_info and require source: "ipc" before treating this as live-board proof (score_placement names the same live authority source: "live_ipc"). A saved-file or CLI observation may support a separate check, but report it as saved/CLI evidence and do not present it as live IPC readback.
6. Validate the observed result. Re-run score_placement and KiCad DRC. Check the score's hard failures, outline status, deductions, associations, and evidence source—not only its numeric score. Continue with another small batch only when the observed result justifies it.
7. Finish with evidence or BLOCKED. Report the exact moved and held references, observed live positions, source for each check, score/DRC result, and remaining findings. Report BLOCKED when live source authority, functional intent, containment, or another required fact cannot be proved; never fill an evidence gap with a guessed coordinate or a request value.

Completion requires live readback of every applied move plus placement and DRC results from the resulting board. A diagnostic plan, a saved-file snapshot, or an unproved outline is not completion evidence.

Placement diagnostics and planners

• score_placement reports a 0-100 score with named deductions. Hard failures (courtyard overlaps, parts outside a proven outline) decide the verdict regardless of the number, and a board with no outline can never pass. decoupling_associations names the non-ground, bounded-fanout evidence used for cap-to-IC distance checks; unproven_decoupling_caps identifies caps the scorer deliberately did not guess about. interface_filter_caps lists caps within their family limit of a connector carrying every one of their nets; do not drag those cable-filtering parts toward an IC.
• Outside-outline and connector-edge evidence applies only to a provably axis-aligned rectangular outline (outline_shape: "rectangular"). Treat outline_unproven like outline_missing, not like pass; validate a non-rectangular board's real fit with KiCad DRC and report BLOCKED for the unavailable containment proof.
• auto_place_from_schematic returns a deterministic net-clustered starting plan for diagnosis. It never writes: dry_run: false returns structured plan_blocked.
• refine_placement_force_directed is deprecated. Its global-net spring model can pull a part toward every footprint sharing a board-wide rail. Dry-run may explain its plan, but blocked, non-improving, and score-tied plans do not apply; use bounded explicit moves instead.
• place_decoupling_caps plans a row beside an IC from exact caller-given capacitor_references (never net-inferred). It refuses an out-of-bounds, non-improving, or containment-unproven plan.
• plan_bga_fanout detects pitch from the pad grid; apply executes as one KiCad undo commit over live IPC.

Placement Tips

• Use mm coordinates (KiCAD default for PCB)
• Standard grid: 0.5mm for placement, 0.25mm for fine adjustment
• Check component courtyard overlaps after placement
• Reference designator text: F.SilkS layer, 1mm height default

Routing

Before choosing trace approach points, call get_component_pads for the participating footprints. Use its returned board-space position, effective rotation, shape, size, drill, and per-copper-layer geometry; do not estimate copper extent from package family or a different pad in the footprint. A null geometry field is unavailable evidence, not a zero-size pad.