# AI PCB Pipeline: Instructions for Your AI Agent

> **How to use this file:** give it to your AI coding agent (Claude Code or a similar agent that can run shell commands and use MCP servers) and say: *"Read this file and help me set up this pipeline step by step. Verify each step before moving on."*
>
> From the video *"What would it take to get Claude to design and order a finished PCB?"*, Steve Spence, KK4HFJ (kk4hfj.com). Tested November 2026 on Windows 11 with KiCad 10.0.8. Tool versions change, so verify everything below against current releases.

---

## 0. Rules for the agent (read first)

1. **Verify every step** with the check command given before moving on. Report the actual output to the user.
2. **Never place or pay for an order.** You can prepare files, upload them and get quotes. The human reviews and pays.
3. **Never install into system-wide or global locations** without saying so first. Prefer user scope and project-local libraries.
4. **Pin versions of third-party packages** (`@x.y.z`, not `@latest`) so updates only happen on purpose.
5. **Keep an engineer's notebook** (section 5). You lose memory between sessions; the notebook is how you pick up where you left off.
6. **Don't trust a clean ERC/DRC as proof the board works.** Electrical-rule checks miss design intent (see the USB-C example in section 6).
7. If a step fails, **diagnose before retrying**. Don't loop on the same failing command.

---

## 1. What gets installed

| Piece | Role |
|---|---|
| KiCad 10 | Schematic and PCB editor. Includes its own Python with the `pcbnew` board API, and `kicad-cli` |
| Node.js LTS | Runs the KiCad MCP server and npx-based MCP servers |
| KiCad MCP server ([mixelpixx/KiCAD-MCP-Server](https://github.com/mixelpixx/KiCAD-MCP-Server)) | Lets the agent create projects, place parts, wire, route, and run ERC/DRC |
| Java (Temurin JRE) | Required by Freerouting |
| Freerouting | Autorouter for boards with more than a handful of nets |
| pcbparts MCP ([pcbparts.dev](https://pcbparts.dev/)) | Live JLCPCB/LCSC part search, stock and pricing, plus Mouser/DigiKey lookups. No login |
| jlc MCP (`@jlcpcb/mcp`, community package, not made by JLCPCB) | Installs the exact LCSC part's symbol, footprint and 3D model into the project |
| Git | Needed to clone the MCP server |
| Claude in Chrome (browser extension) | Lets the agent use the fab websites: upload Gerbers, BOM and placement files, and read back part matching, placement previews and quotes |

---

## 2. Installation (Windows, PowerShell)

### 2.1 Check what's already there
```powershell
foreach ($c in 'git','node','npm','npx','python','java','claude') {
  $p = (Get-Command $c -ErrorAction SilentlyContinue).Source
  "{0,-7} {1}" -f $c, ($(if ($p) { $p } else { 'NOT FOUND' }))
}
```

### 2.2 KiCad 10
- Install from kicad.org with **all components**, including the 3D models (needed for clearance checks).
- **Gotcha:** the installer may install **per-user** to `%LOCALAPPDATA%\Programs\KiCad\10.0` instead of `C:\Program Files\KiCad\10.0`. Find the real location:
```powershell
Get-ChildItem 'C:\Program Files\KiCad', "$env:LOCALAPPDATA\Programs\KiCad" -Recurse -Filter kicad-cli.exe -Depth 3 -ErrorAction SilentlyContinue | Select-Object FullName
```
- Set `$K` to that `...\KiCad\10.0` folder for the rest of these steps, then **verify** (both should print the KiCad version):
```powershell
& "$K\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"
& "$K\bin\kicad-cli.exe" version
```

### 2.3 Node.js LTS
```powershell
winget install OpenJS.NodeJS.LTS
```
- **Gotcha:** don't use a version manager like fnm for this. It only puts `node` on PATH inside configured shells, and agents launch MCP servers outside those shells.
- **Gotcha:** if `npm --version` fails with "running scripts is disabled on this system":
```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```
- Open a **new** PowerShell window, then verify: `node --version; npm --version; npx --version`

### 2.4 KiCad MCP server
Install this **after** KiCad.
```powershell
cd $HOME\Documents
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install                # also builds; ignore audit warnings, do NOT run "npm audit fix --force"
.\setup-windows.ps1        # finds KiCad, installs Python deps, builds, test-starts the server
```
- The script prints a config block for Claude Desktop. For **Claude Code**, register it like this instead, using the paths the script detected:
```powershell
claude mcp add kicad -s user `
  -e PYTHONPATH="$K\bin\Lib\site-packages" `
  -e KICAD_PYTHON="$K\bin\python.exe" `
  -e NODE_ENV=production -e LOG_LEVEL=info `
  -- node "$HOME\Documents\KiCAD-MCP-Server\dist\index.js"
```
- **Verify:** `claude mcp list` shows `kicad ... Connected`.
- **If you get `ModuleNotFoundError` later:** the Python deps went into the system Python instead of KiCad's. Fix:
  `& "$K\bin\python.exe" -m pip install -r "$HOME\Documents\KiCAD-MCP-Server\requirements.txt"`

### 2.5 Java + Freerouting
- **Gotcha:** Freerouting **2.2.0 and later need Java 25**. Freerouting 2.1.0 is the last release that runs on Java 21. Keep only one Java installed so the wrong one can't be picked up.
```powershell
winget install EclipseAdoptium.Temurin.25.JRE
New-Item -ItemType Directory -Force "$HOME\.kicad-mcp" | Out-Null
# Check github.com/freerouting/freerouting/releases for the current version:
Invoke-WebRequest "https://github.com/freerouting/freerouting/releases/download/v2.5.0/freerouting-2.5.0.jar" -OutFile "$HOME\.kicad-mcp\freerouting.jar"
```
- **Verify:** in a new window, `java -version` shows 25, and `(Get-Item "$HOME\.kicad-mcp\freerouting.jar").Length / 1MB` is tens of MB. A tiny file means you saved an error page.
- Then have the agent run the MCP's Freerouting check tool.

### 2.6 Parts MCP servers
```powershell
claude mcp add --transport http pcbparts -s user https://pcbparts.dev/mcp
claude mcp add jlc -s user -- npx -y @jlcpcb/mcp@0.5.0
```
- **Gotcha:** the npm package is `@jlcpcb/mcp`. Its README mentions a command called `jlc-mcp`, but `npx jlc-mcp` is a 404.
- **Gotcha (version 0.5.0):** it only knows KiCad 8 and 9. **Always pass `project_path`** to its tools so parts go into `<project>\libraries\`, registered via `${KIPRJMOD}`. Without it, parts land in a KiCad 9 folder that KiCad 10 ignores.

### 2.7 Claude in Chrome (browser access for the fab websites)
- Install the **Claude** extension in Chrome and sign in with the **same Claude account and organization** as Claude Code.
- Start Claude Code with browser tools enabled: `claude --chrome` (or run `/chrome` and enable it by default). `/chrome` shows the status.
- **What the agent does with it:** creates the quote, uploads the Gerber zip, BOM and placement (CPL/centroid) files, then **reads back** the part matching, the placement preview and the price so the human can review them.
- **Gotcha (PCBWay):** files are uploaded *after* Save to Cart, and the upload form sits inside an iframe. Open the iframe's URL in its own tab to reach the file inputs.
- **Hard stop:** the agent **does not** accept terms of service, export/IP notices or payment. The human clicks those.

---

## 3. Project rules file (put in your projects folder as CLAUDE.md or AGENTS.md)

```markdown
# KiCad projects
- One project per folder. Read SETUP.md before tooling work; add every solved tool problem to it.
- Every project keeps NOTEBOOK.md. Read it first when resuming; update it as work happens.

## Parts
- Prefer in-stock JLC Basic/Preferred parts (no extended-part fee). Add an LCSC field to every symbol.
- jlc MCP: ALWAYS pass project_path.
- Check converted (EasyEDA) footprints before use: pad names must match the symbol's pin numbers,
  and "custom" pads on a tiny anchor pad break zone fills and connectivity; redraw them as plain pads.

## Before ordering
- After installing any converted part, verify its 3D model offset: the legs/pins must sit on the
  footprint's slots/pads. A wrong offset silently invalidates every 3D check.
- Run a 3D-body clearance check (not just courtyard DRC) for connectors and tall parts:
  numeric (STEP body extents vs. other parts and the Edge.Cuts outline) plus rendered views from
  at least two angles. Record the result in the notebook.
- Refill zones and save before every export (DRC refills only for the check).
- Never place or pay for an order. Prepare files, upload, quote; the human approves and pays.
```

---

## 4. Workflow

1. **Spec:** agree on the requirements, block diagram, parts with LCSC numbers, board outline and connector positions before drawing anything.
2. **Schematic:** create the project and run ERC. Then **review the design intent** as well as the ERC result (section 6).
3. **Placement:** set the board outline, place connectors at the edges, keep decoupling capacitors next to their pins.
4. **Routing:** hand-route critical nets (power, USB data, RF feeds) and lock them. Autoroute the rest with Freerouting on a **copy** first, then import the `.ses` file.
5. **Checks:** DRC with 0 errors, schematic/board parity, the 3D model offset check, the clearance check, and LED and diode polarity.
6. **Export:**
   - **JLCPCB:** Gerbers (Protel extensions) plus Excellon drill (mm). BOM columns `Comment, Designator, Footprint, LCSC Part #`. CPL columns `Designator, Mid X, Mid Y, Layer, Rotation`.
   - **PCBWay:** the same Gerbers plus drill map. BOM by manufacturer part number (`Item #, Designator, Qty, Manufacturer, Mfg Part #, Description, Package, Type`). Centroid in mm from the board's lower-left corner.
7. **Upload and fab preview (Claude in Chrome):** upload the files and get the quote. In the fab's placement preview, check every polarized part and every connector's orientation; LEDs are the most common thing to come out rotated 180°. Report the matched parts, any shortfalls and the price to the human.
8. **Human approval:** the human reviews the quote and pays.

---

## 5. Engineer's notebook template (NOTEBOOK.md in each project)

```markdown
# <project> engineer's notebook
## Current state
- Design: ERC/DRC counts, accepted warnings
- Order: fab, quantity, order numbers, status
## Circuit
| Ref | Value | LCSC | MPN | Notes |
## Layout
- Board size/layers, key placements, routing method
## Files
| Path | What |
## Log
### YYYY-MM-DD
- What was done, why, and the result (with numbers). Problems and their fixes. Anything the user approved.
## Open items
```

---

## 6. Lessons from the first board

- **ERC passing doesn't mean the board works.** On a USB-C power input, a USB-C source only switches on 5 V when it sees **5.1 kΩ pull-downs on CC1 and CC2**. Without them, the board stays dead on a C-to-C cable, even though ERC passes.
- **Distrust 3D views until you've checked the model offsets.** A converted USB-C model sat 0.8 mm out of place and 1 mm above the board, which made a clearance problem appear that wasn't real. The copper was fine.
- **Freerouting completes routes; it doesn't optimize them.** On tiny boards a hand route is often cleaner. Freerouting earns its keep at dozens of nets.
- **Fab accounts can be restricted for trade-compliance reasons** (for example, sign-ins from VPN or data-center IP addresses). Keep exports for two fabs ready, and **don't try to get around a restriction**. Contact the fab's support instead.
- **Use the strongest (most expensive) model only where it pays off:** dense, RF or mixed-signal layouts on products you intend to sell. Setup, part lookups, exports and simple boards run fine on a standard model.

---

*No warranty. You are responsible for reviewing every design before ordering. Third-party tools and packages are independent projects; check their licenses and current versions.*