drawing jlcpcb-mapper
type cli tool
target kicad 9 + jlcpcb
rev 0.1
source github ↗

// reads empty-footprint symbols · writes LCSC + KiCad footprint

LLM-assisted part mapping
from KiCad schematics
to JLCPCB's LCSC catalog.

Scores candidates against a local parts catalog, asks Claude Code to break ties on the close calls, then writes the LCSC and KiCad footprint back into the schematic — with a human-readable Markdown report that explains why each part was picked.

→ repository install 한국어 README
§ 01

What this saves you from

Hand-mapping every passive, IC, and connector in a KiCad project to a JLCPCB part is tedious and easy to get wrong — same value, different package; correct package, EOL stock; SMD label, leaded part.

This tool automates the mechanical 80% — resistors, ceramic caps, common diodes and MOSFETs by MPN — and surfaces the close calls as a Markdown review document with LCSC.com links and the alternatives that were considered. Reviewing the report takes a fraction of the time of picking each part by hand.

Out of scope on purpose: power-only symbols, mounting holes, DNP parts, and anything you've explicitly pinned in manual_lcsc.

§ 02

How it picks each part

Symbols are routed by lib_id into a category, grouped by category + spec + package hint, and run through a five-stage pipeline. Each stage either narrows the candidate set or commits to a pick — the LLM is only consulted when deterministic scoring can't decide.

01 · match
Route by lib_id → category (Device:R → resistor, Device:CP_* → polarized_capacitor, anything else with a : → ic).
02 · parse
Extract a structured spec from the Value field. "4.7uH/2A" → inductance + minimum current.
03 · query
Pull candidates from parts.db by category, package, description LIKE on the value, min-stock floor.
04 · decide
single one candidate  ·  score deterministic ranking  ·  llm tiebreak via Claude
05 · resolve
KiCad built-in footprint for common SMD passives; on-the-fly EasyEDA download for everything else.

Manual override bypasses the pipeline entirely: pin a specific LCSC by reference designator or by Value field for subjective parts (USB-C receptacles, pogo pins, tactile switches, barrel jacks).

§ 03

What the report looks like

Every map run writes a Markdown review document next to your project. One section per group, each with the rationale, an LCSC.com link, the chosen part's spec, and the alternatives that came close.

.jlcpcb-mapper/run-2026-04-25T16-07-55.md markdown

resistor 4700Ω 0402 — 20 refs

R20, R21, R22, R23, R24, R50, R52, R56 … +12 more

Selected C25744 — UNI-ROYAL 0402WGF4701TCE

  • Package 0402
  • Tier Basic
  • Stock 4.4M
  • Price $0.0009

Why this part? Score 1.00 vs runner-up 0.40 — Basic-tier (vs Extended), higher stock (4.4M vs 60k).

3 alternatives considered
LCSCMfr PartTierStockScore
C123456YAGEO RC0402FR-074K7L Ext 60k0.40
C25900UNI-ROYAL 0402WGF4701TCE Ext 1.6M0.40
C137970FH 0402WGF4701TCE Ext 980k0.40

The llm path passes Claude's one-sentence reason through verbatim ("Closest SMD form factor matching the existing footprint"); the score path generates the rationale from the score breakdown deltas.

§ 04

Install & run

Three commands to a mapped board. The tool refuses to run on a dirty git tree, so git diff is always your final review step. 

# 1. install
$ pipx install jlcpcb-mapper

# 2. one-time: build the parts catalog (~1 GB → slim 100 MB DB)
$ jlcpcb-mapper fetch-db

# 3. inside your KiCad project
$ jlcpcb-mapper init                          # scaffolds jlcpcb-mapper.yaml
$ jlcpcb-mapper map my-project.kicad_pro      # writes LCSC + footprint
$ open .jlcpcb-mapper/run-<ts>.md             # review the rationale doc
$ git diff                                    # final eyeball

Atomic schematic writes with timestamped backups in .jlcpcb-mapper/backups/<ts>/. Per-group traces (match → parse → query → decide → resolve) recorded under .jlcpcb-mapper/traces/<ts>/groups.jsonl.

§ 05

Status & roadmap

Today (v0.1)

Validated end-to-end against a real KiCad project (≈150 eligible symbols, ~76% exact-match against hand-picked baseline). Supports resistor, ceramic / polarized capacitor, inductor, ferrite bead, LED, crystal, connector, and a catch-all IC category.

Next

Schematic-context-aware part selection. The decision today uses only the symbol's local fields. Net topology, voltage-domain inference, and per-net current estimates would let the LLM tiebreak with full circuit context — "this 4.7 µH inductor sits on the switcher's output, so it needs ≥2× the load rating."