---
name: kicad-pcb-design
description: >
  Design, inspect, route, and verify printed circuit boards (PCBs) in KiCad using the KiCAD MCP server and kicad-cli.
scope: global
---

# KiCad PCB Design

Design, inspect, route, and verify printed circuit boards using the KiCAD Model Context Protocol (MCP) server or `kicad-cli`.
Follow the [shared workflow](../../protocols/workflow.md).

## Prerequisites

KiCad and its Python scripting module (`pcbnew`) must be installed on the host:
```bash
sudo pacman -S kicad kicad-library kicad-library-3d
```
The KiCad MCP server is built and located at `~/Projects/work/KiCAD-MCP-Server`.
To start the MCP server manually or via configuration:
- Node runner: `node ~/Projects/work/KiCAD-MCP-Server/dist/index.js`
- Python environment: `~/Projects/work/KiCAD-MCP-Server/.venv/bin/python`

## Workflow

1. **Schematic Capture & Part Selection**
   - Use standard KiCad symbol libraries (`Device`, `Connector`, `Regulator_Linear`, etc.).
   - When using MCP:
     - Search parts: `search_symbols`, `search_jlcpcb_parts`
     - Add components: `add_schematic_component` or `batch_add_components`
     - Connect nets: `add_schematic_wire`, `add_net_label`
     - Run ERC: `run_erc` to catch floating inputs or unpowered pins.
   - When using CLI/files:
     - Work directly with `.kicad_sch` files or compile from netlists.
     - Validate: `kicad-cli sch erc project.kicad_sch`

2. **Board Edge & Physical Stackup**
   - Define board outline on `Edge.Cuts` with mounting holes (e.g. M2.5 or M3 with keepouts).
   - Standard 2-layer or 4-layer stackup:
     - Default thickness: 1.6 mm FR4, 1 oz Cu (35 µm).
     - Signal trace width: `0.25 mm` (10 mil).
     - Power trace width: `0.5 mm` – `1.0 mm` depending on current.
     - Clearance: minimum `0.2 mm` (8 mil) for low-cost fab houses (JLCPCB, PCBWay).

3. **Placement & Routing**
   - **Bypass capacitors:** Place ceramic decoupling caps (0.1 µF) as close as physically possible to IC $V_{CC}$ / GND pins.
   - **Ground plane:** Fill top and bottom (or inner) layers with solid GND copper pours (`zone`). Stitch GND with vias near return current paths.
   - **Routing:**
     - Interactive/MCP routing: invoke routing tools or export DSN for Freerouting (`run_freerouter`).
     - Avoid 90° trace corners; use 45° bends.

4. **Empirical Verification ("The engine measures")**
   - **Design Rule Check (DRC):**
     - MCP: `run_drc`
     - CLI:
       ```bash
       kicad-cli pcb drc --output drc_report.json project.kicad_pcb
       ```
     - Zero unapproved clearance, unrouted net, or courtyard collisions before tapeout.

5. **Fabrication & Export**
   - Generate production manufacturing artifacts:
     ```bash
     # Gerber & Drill files
     kicad-cli pcb export gerbers -o gerbers/ project.kicad_pcb
     kicad-cli pcb export drill -o gerbers/ project.kicad_pcb
     # 2D/3D visual renders for human review
     kicad-cli pcb render -o board_preview.png project.kicad_pcb
     ```
   - Generate BOM and Centroid / Pick-and-place (CPL) for assembly.