productofamerica/mcp-server-kicad/pcb-layout

<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>

KiCad PCB Layout

Place footprints and route traces to produce a manufacturable board. This skill assumes you have a completed schematic with a netlist.

Response Format

When this skill activates, print exactly:

Using pcb-layout to place footprints and route traces.

Then proceed directly to the Pre-flight Checks. This is a mechanical execution phase — do not ask the user what to do unless board size or layer count is ambiguous and not specified in specs/bom.md.

Report progress at natural milestones: after footprint placement, after critical trace routing, after autoroute, after post-route refinement. Keep status updates to one line each.

MCP Tools for This Skill

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

Reading / inspection:

• 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
• get_board_info — get board outline, layer count, design rules
• get_footprint_pads — get pad positions and net assignments
• get_footprint_bounds — get board-coordinate bounding box of a placed footprint
• check_placement — check if placing a footprint at (x, y) violates keepout or board edge

Netlist import:

• update_pcb_from_schematic — pull the schematic's netlist onto the board:

loads the assigned footprints, binds every pad to its net, creates the .kicad_pcb if missing (requires kicad-cli for the netlist). Re-run after schematic edits; delete_stale=True removes parts dropped from the schematic.

Placing and moving footprints:

• place_footprint — place a footprint on the board
• move_footprint — reposition a placed footprint (warns on keepout/edge violations)
• remove_footprint — delete a placed footprint

Routing:

• add_trace — add a trace segment with layer, width, coordinates
• add_via — add a via at a coordinate
• autoroute_pcb: run Freerouting autorouter (requires Java 25+, auto-downloads JAR)

Post-routing refinement:

• add_copper_zone — create a copper zone (ground plane, power fill) with polygon outline
• add_keepout_zone — create a keep-out zone restricting tracks, vias, pads, copper pour, or footprints
• fill_zones — compute copper fills for all zones (requires pcbnew)
• set_trace_width — change width of existing traces by net, layer, or region
• add_thermal_vias — add a via array under a footprint pad (QFN thermal pads)
• remove_traces — delete traces by net, layer, or region
• set_net_class — create/update net classes with design rules (edits the .kicad_pro)
• remove_dangling_tracks — clean up unconnected trace stubs

Drawing and annotation:

• add_pcb_text — add silkscreen text or other layer text
• add_pcb_line — draw lines (board outline on Edge.Cuts, etc.)

Verification and export:

• run_drc — run design rules check
• export_pcb — export PCB as PDF/SVG
• export_gerbers — export Gerber manufacturing files
• export_3d — export 3D model (STEP/VRML)
• export_positions — export pick-and-place file
• export_ipc2581 — export IPC-2581 data
• export_hierarchical_netlist — use instead of standard netlist export

for hierarchical designs with sub-sheets

Footprint libraries:

• list_lib_footprints — browse .pretty library directories
• get_footprint_info — check pad dimensions and pin mapping

Pre-flight Checks

Before starting PCB layout, verify these prerequisites:

1. ERC gate cleared: Run run_erc and confirm violation_count = 0.

If ERC has not been run or has violations, STOP and invoke the verification skill first.

1. Annotation check: Run validate_hierarchy on the root schematic.

Netlist import fails if references contain ? or have duplicates across sheets. Fix with annotate_schematic (pass project_path for hierarchical designs) before proceeding.

1. Footprint verification: For each schematic component, call

list_lib_footprints to verify the assigned footprint exists.

1. BOM cross-reference: If specs/bom.md exists, cross-reference

footprints against the BOM's footprint column.

1. Board size constraints: Check board size from BOM artifact (if

present) and configure board outline accordingly.

1. IPC design class: If BOM specifies IPC design class, configure

design rules (trace width, spacing, annular ring) to match class requirements:

• Class 1 (consumer): relaxed tolerances
• Class 2 (industrial): standard tolerances (default)
• Class 3 (high-rel): tightest tolerances

Layout Process

1. Import netlist — update_pcb_from_schematic creates the board file

if missing; footprints appear in a cluster with all nets bound. Net names match the schematic's netlist (local labels sheet-prefixed, e.g. "/SIG") — read them with list_pcb_nets.

1. Board setup — define board outline, layer count, design rules.
2. Place footprints — group by function, then optimize.
3. Route critical traces — power, high-speed, sensitive analog.
4. Route remaining traces — signal interconnects (or use autoroute_pcb).
5. Post-route refinement — review and improve routing quality:

a. Set net classes for power nets: set_net_class (e.g., "Power" class with 0.5mm+ width) b. Widen power traces: set_trace_width on power nets (VIN, VOUT, SW, GND paths) c. Add thermal vias: add_thermal_vias under QFN/exposed pads d. Clean up: remove_dangling_tracks to remove autorouter stubs e. Remove and re-route if needed: remove_traces + add_trace for problem areas

1. Add copper zones — add_copper_zone for ground planes on both layers, then fill_zones.
2. Run DRC — fix violations, re-run until clean.
3. Export — Gerbers, drill files, pick-and-place, BOM.

Footprint Placement Strategy

Group by functional stage — keep components from each schematic stage physically together. The schematic's block diagram maps directly to PCB placement regions.

Placement priority order:

1. Connectors — fixed by mechanical constraints (edge of board)
2. ICs / active components — central to their stage
3. Decoupling caps — as close as possible to IC power pins (< 3mm)
4. Input/output passives — near their IC, following signal flow
5. Bulk caps and inductors — near but not blocking routing channels
6. Test points, mounting holes — last, fill remaining space

Orientation conventions:

• Align ICs with pin 1 in a consistent corner (top-left preferred)
• Polarized caps: positive toward the supply side
• Diodes: cathode band facing consistent direction per stage
• Connectors: mating face toward board edge

Spacing minimums:

• IC to decoupling cap: < 3mm center-to-center
• Between 0805 passives: 1.0mm edge-to-edge minimum (1.5mm comfort)
• Between ICs: 3–5mm edge-to-edge for routing channels
• Components to board edge: 1.0mm minimum (2.0mm for wave solder)

Use place_footprint with coordinates in mm. Use move_footprint to adjust after initial placement. Use get_footprint_pads to check pad locations before routing.

Trace Routing

Trace Width by Current

These assume 1oz (35um) copper, 10C rise, outer layer. Inner layers need ~2x width for the same current.

Routing Rules

Power traces first:

• Route VIN, VOUT, and GND connections before signal traces.
• Use the widest trace the space allows, not the minimum.
• Keep power loops tight — short, wide traces from regulator input

cap through the IC to the output cap.

Signal traces:

• Default 0.25mm width for logic signals.
• Keep parallel runs short to minimize crosstalk.
• Route differential pairs together with matched length.
• Avoid 90-degree corners — use 45-degree bends or arcs.

Return paths:

• Every signal needs a return path. On a 2-layer board, route GND

traces alongside signal traces.

• On 4+ layer boards, use a continuous ground plane — do not split it

under signal traces.

Sensitive traces:

• Analog inputs: guard ring or ground trace on both sides.
• High-impedance nodes: minimize trace length, keep away from

switching signals.

• Clock/PWM lines: route away from analog sections.

Use add_trace with layer, width, and coordinate list. Use add_via to transition between layers.

Via Usage

• Signal vias: 0.3mm drill / 0.6mm annular ring (default)
• Power vias: 0.4mm drill / 0.8mm annular ring, use multiple

vias in parallel for high current (one via ≈ 1A for 1oz copper)

• Thermal vias: under thermal pads, 0.3mm drill, array of 4–9

vias connecting to ground plane

• Place vias close to pads, not in the middle of trace runs

Post-Autoroute Refinement

After using autoroute_pcb, the board has connectivity but needs refinement before it's manufacturing-ready. The autorouter uses minimum-width traces for everything and has no concept of power integrity or thermal design.

Step 1: Define net classes

Use set_net_class to establish design rules for power nets:

• Create a "Power" class with track_width=0.5 (or wider per current table)

for VIN, VOUT, and other power rails.

• Create a "HighCurrent" class with track_width=1.0 for switch nodes (SW)

and high-current ground paths.

Step 2: Widen power traces

Use set_trace_width to bring power traces up to their net class width:

• set_trace_width(width=0.5, net_name="VIN")
• set_trace_width(width=1.0, net_name="SW")
• For ground nets routed as traces (before zone fill): widen to 0.5mm+

Step 3: Add thermal vias

Use add_thermal_vias for any QFN or exposed-pad IC:

• add_thermal_vias(reference="U1", rows=3, cols=3, spacing=1.0, via_drill=0.3)
• Thermal vias connect the exposed pad to the ground plane on the opposite

layer for heat dissipation.

Step 4: Clean up

Use remove_dangling_tracks to remove autorouter stubs — trace ends that connect to nothing. These are cosmetic but will show as DRC warnings.

If any trace routing is unsatisfactory, use remove_traces to delete traces on a specific net, then re-route manually with add_trace.

Step 5: Add copper zones

Use add_copper_zone on both layers:

• Ground fill on F.Cu and B.Cu (2-layer) or dedicated ground plane on In1.Cu (4-layer)
• Set clearance to match design rules (typically 0.3–0.5mm)
• Then call fill_zones to compute the actual copper fill

Step 6: Final DRC

Run run_drc and fix any remaining violations. Common post-refinement issues:

• Clearance violations from widened traces — may need to re-route nearby signals
• Zone fill islands — delete or connect them

Checklist