productofamerica/mcp-server-kicad/verification

<CRITICAL-RULE> NEVER use the Read, Write, or Edit tools on KiCad files (.kicad_sch, .kicad_pcb, .kicad_sym, .kicad_mod, .kicad_pro, .kicad_prl). ALL KiCad file manipulation MUST go through the kicad MCP tools. NEVER run kicad-cli commands via Bash. If an MCP tool returns an error, try different parameters — do NOT fall back to manual file editing.

EVERY KiCad operation has a corresponding MCP tool. Do NOT claim a tool does not exist without first listing all available tools. Key tools that MUST be used instead of file writes:

• add_symbol — create custom symbol definitions in .kicad_sym files
• create_symbol_library — create new .kicad_sym library files
• create_schematic — create new .kicad_sch files
• create_project — create new .kicad_pro project files

If you find yourself thinking "there's no MCP tool for this," you are wrong. Check the tool list again. </CRITICAL-RULE>

<HARD-GATE> No phase proceeds past verification without zero violations. "Probably clean" is not evidence. Run the check, show the output, confirm violation_count = 0. </HARD-GATE>

KiCad Design Verification

Systematic workflows for fixing ERC and DRC violations. Run these checks after completing schematic capture or PCB layout — never skip them.

Response Format

When this skill activates, announce which check is being run:

• ERC gate: Print exactly: "Running ERC verification on the

schematic."

• DRC gate: Print exactly: "Running DRC verification on the

PCB."

Then proceed directly to running the check. Do not ask the user what to do. Report violations found, then fix them systematically per the workflow below.

MCP Tools for This Skill

These are the kicad MCP tools you should be using during verification:

Schematic checks:

• run_erc — run electrical rules check, returns all violations.

Checks a sub-sheet from its project's root for full hierarchy context and returns that sheet's own violations.

• list_unconnected_pins — find unconnected pins by component.

Checks a sub-sheet from its project's root to avoid false positives and returns that sheet's own pins.

• get_net_connections — trace a net to debug connectivity issues
• validate_hierarchy — check for unannotated refs, duplicate refs,

orphaned labels/pins, direction mismatches, junctions and bus entry ends left inside wires, and no-connect flags and wire ends left off the pins of mirrored, rotated parts (run from root schematic)

• trace_hierarchical_net — trace a net across sheet boundaries to

debug cross-sheet connectivity issues

Schematic fixes:

• add_power_symbol — place PWR_FLAG to fix "power pin not driven"
• connect_pins — wire two pins together
• wire_pins_to_net — connect pins to a named net
• no_connect_pin — mark intentionally unused pins
• remove_label — remove misplaced labels
• set_page_size — resize sheet when components exceed page boundary
• annotate_schematic — auto-assign reference designators to unannotated

components (pass project_path for hierarchical designs)

• set_component_property — reset duplicate references to X? before

re-annotation

• remove_text — remove leftover text annotations from debug/workaround

operations

PCB checks:

• run_drc — run design rules check, returns all violations
• get_board_info — verify board setup and design rules
• list_pcb_footprints — list footprints on the board
• list_pcb_traces — list traces on the board
• list_pcb_nets — list nets on the board
• list_pcb_zones — list zones on the board
• list_pcb_layers — list layers on the board
• list_pcb_graphic_items — list graphic items on the board
• validate_board — check all footprints against keep-out zones and board edge

PCB fixes:

• add_trace — route missing connections
• add_via — add vias for layer transitions
• move_footprint — fix clearance violations by repositioning
• set_trace_width — fix trace width violations
• remove_traces — remove problematic traces for re-routing
• add_copper_zone — add missing ground planes / copper fills
• fill_zones — recompute zone fills after changes
• remove_dangling_tracks — clean up unconnected trace stubs

Export (post-verification):

• export_gerbers — Gerber manufacturing files
• export_positions — pick-and-place file
• export_bom — bill of materials
• export_3d — 3D model for mechanical review
• export_schematic — schematic PDF/SVG
• export_pcb — PCB PDF/SVG
• export_ipc2581 — IPC-2581 manufacturing data (alternative to Gerbers

for some fabs)

• export_hierarchical_netlist — netlist with hierarchy info for

hierarchical designs (use instead of export_netlist when design has sub-sheets)

ERC Workflow (Schematic)

Step 0: Pre-ERC Hierarchy Validation

Run validate_hierarchy on the root schematic before ERC. This catches issues that kicad-cli ERC does not report: unannotated components, duplicate reference designators across sheets, orphaned hierarchical labels/pins, and direction mismatches.

If `unannotated_ref` issues:

1. Run annotate_schematic(schematic_path, project_path="path/to/project.kicad_pro")

— the project_path param scans the hierarchy to avoid cross-sheet conflicts

1. Re-run validate_hierarchy to confirm

If `duplicate_ref` issues: annotate_schematic only assigns numbers to ? refs — it does NOT fix duplicates. To fix:

1. Reset the conflicting ref to X? with set_component_property:

set_component_property(reference="R1", key="Reference", value="R?", schematic_path="sheet_with_duplicate.kicad_sch")

1. Run annotate_schematic with project_path to assign a unique number
2. Re-run validate_hierarchy to confirm

If `orphaned_label`, `orphaned_pin`, or `direction_mismatch`: Fix with add_sheet_pin/remove_sheet_pin or modify_hierarchical_label.

If `junction_inside_wire` or `bus_entry_inside_wire`: an earlier version of this package left a junction or a bus entry end inside a wire, and kicad-cli 9 (ERC, netlist, PCB update) cuts the wire there. Make the call each issue names in repair, exactly as given, then re-run validate_hierarchy to confirm.

If `no_connect_off_pin` or `wire_end_off_pin`: versions 0.5.8 to 0.20.1 of this package computed the pin of a part rotated 90 or 270 degrees and mirrored at a point where KiCad draws no pin, so a flag or a wire end placed there misses it: KiCad draws the pin at pin_x, pin_y. For a wire end with a repair, make that call exactly as given: it joins the pin to what the wire reaches, and leaves the old wire where it is. A flag always carries a note (below), since no tool removes a flag by its position. An issue that lists pins in place of reference, pin, pin_x and pin_y is a point where those versions put several pins: which one the flag or wire was written for is not known, so it carries a note and no repair.

If an issue carries a `note` and no `repair`: no tool call fixes it, and the note says why. Do not work around it with other tools (removing, redrawing or moving wires, junctions or bus entries). Report the note to the user and wait, as in stuck escalation below:

• unreadable_file: the named sheet file cannot be parsed, so none of

its checks ran. The user must restore or repair that file.

• A sheet KiCad cannot load (a symbol or pin at an angle KiCad does not

store): the user applies the remedy the note names in KiCad.

• A bus entry end where KiCad allows no junction: the user opens the

schematic in KiCad 9's editor, which splits the line on load, makes any edit and undoes it, then saves. Saving with nothing edited writes nothing to a schematic already in KiCad 9's format.

• references_unchecked: the hierarchy has too many sheet instances

for the reference check; tell the user it was not completed.

• no_connect_off_pin: the user deletes the flag at x, y in

KiCad's editor. After that, make the no_connect_pin call the note names, if it names one; for an issue that lists pins, the user says which of them to flag.

• wire_end_off_pin with a note: the call that would join the pin

refuses, or the wire's net has no single local label name that wire_pins_to_net accepts (the note then names the pin the wire reaches, if any), or the issue lists pins; the note says which. The user decides how the pin is wired. After the user acts, re-run validate_hierarchy.

Debug cross-sheet nets: Use trace_hierarchical_net to follow a net across sheet boundaries when investigating connectivity violations that span multiple sheets.

Proceed to Step 1 only when validate_hierarchy returns status: "ok".

Step 1: Run ERC

Use run_erc to get the full violation list. Read every violation before fixing anything — some errors share a root cause.

Sub-sheet note: run_erc and list_unconnected_pins automatically check a sub-sheet from its project's root schematic, wherever the sheet file sits in the project, for full hierarchy context. This eliminates false positives from missing parent connections (hierarchical label errors, dangling wire errors). The result holds only that sheet's own violations, and a "note" field says when the check ran from the root. A sheet below a top-level sheet other than the root is refused when that kicad-cli did not check it from the root; run run_erc on that top-level sheet instead. A run that makes no report raises, and output_dir keeps what it held. A file that no sheet of its project uses is checked on its own. Item positions are millimetres in sheet coordinates, the numbers get_pin_positions prints.

Step 2: Fix by Category

Work through violations in this order. Fixing earlier categories often eliminates later ones.

Category 1: Power pin not driven

The most common ERC error. A power input pin has no driving source.

Use add_power_symbol to place PWR_FLAG. Connect it to the net with wire_pins_to_net or connect_pins.

No automatic PWR_FLAG: neither wire_pins_to_net nor add_power_symbol inserts one, because whether a net needs a flag depends on its real source, which only the design knows. Place each flag yourself, one per net that needs it.

Where to place PWR_FLAG manually: On every net that is driven by something KiCad does not recognize as a power source — regulator outputs, battery terminals, connector pins providing external power.

Category 2: Unconnected pins

Use list_unconnected_pins to get a precise list of which pins are unconnected and on which components.

Category 3: Different net names on same wire

A wire connects two differently-named nets, creating a conflict.

Category 4: Pin type conflicts

KiCad warns when incompatible pin types connect (e.g., two outputs driving the same net).