flamingo-pcb

Prompt-first PCB CAD for Claude Code. No schematic step: describe the board
in plain language and Claude Code drives a custom TypeScript engine over MCP —
picking real LCSC parts, placing footprints, wiring
connectivity, autorouting with Freerouting,
running DRC, and exporting a
JLCPCB-ready fab package (gerbers.zip + bom.csv +
cpl.csv). A live browser view shows the board update as it's built.

Features

• Prompt-first workflow over MCP — 34 tools cover the whole flow: parts →
  placement → nets → routing → DRC → fab export. No schematic step.
• Real parts — LCSC keyword search plus EasyEDA footprint fetch/parse with
  real pad numbers and geometry, cached locally under ~/.flamingo/parts/.
• Live browser editor — WebSocket-synced canvas view with selection and
  drag editing, a via tool (hover copper to inherit its net), silk text/line
  editing, board search, zone & label layer toggles, copper island tints, a
  nets panel showing each net's track width, a one-click Lock & Route
  button, and Run DRC with red canvas markers.
• 3D view + STEP export — interactive 3D board with real vendor component
  models, 3D silkscreen, and STEP export in two flavours: light courtyard
  blocks or full detail (copper, silk, drilled barrels).
• Autorouting — Freerouting integration with per-net routing, automatic
  thin-escape retry for fat nets that can't exit fine-pitch pads, a widen pass
  that necks down only at obstructions, and automatic GND stitching vias for
  orphaned pour islands.
• Copper features — zone pours with filled-copper connectivity, keepouts,
  mounting holes/slots, and per-net-class track width / clearance / via rules.
• DRC against JLCPCB capabilities — rulesets picked by layer count:
  clearance, track width, drill/annular/via minimums, copper-to-edge,
  keepouts, hole-to-hole, courtyard overlap, silk-over-pad, unconnected nets,
  and outline checks.
• Live stock check in DRC — every placed part is checked against JLCPCB's
  assembly parts library; out-of-stock parts gate export (waivable), low or
  unknown stock is reported as a non-gating advisory.
• Board-aware silkscreen — refdes labels are auto-placed on-board,
  pad-safe, and non-overlapping by a whole-board solver.
• Fab-ready export — Gerber X2 + Excellon drills, JLCPCB BOM/CPL, a
  reference render SVG, and a browser download zip shaped for direct upload
  to JLCPCB's order page.
• Op-log editing — every change is an operation with full undo/redo;
  boards are plain JSON files that diff cleanly in git.
• Agent-friendly feedback — PNG screenshots (with ratsnest and DRC
  overlays), text board summaries, and connection listings on demand.

Quick start

npm install
npm run build

# Serve a board (creates board.flamingo if it doesn't exist):
node packages/server/dist/cli.js serve board.flamingo
#   … or, once the server package is linked, `npx flamingo serve board.flamingo`

# Open the live view:
open http://localhost:4242

Point Claude Code at the running server by dropping this .mcp.json in your
project (it's already at the repo root):

{
  "mcpServers": {
    "flamingo": { "type": "http", "url": "http://localhost:4242/mcp" }
  }
}

Now ask Claude Code to build a board — e.g. "make me a 2-layer ESP32-S3
breakout with USB-C power and a 3.3V LDO" — and watch the browser view fill in.

Requirements

• Node.js 22+
• A Java runtime (for the Freerouting autorouter). On macOS: brew install openjdk (keg-only — either add /opt/homebrew/opt/openjdk/bin to PATH or
  set JAVA_HOME). freerouting.jar is downloaded to ~/.flamingo/ on first
  autoroute.
• Network on first use, to fetch part footprints from the EasyEDA/LCSC API
  (cached under ~/.flamingo/parts/ afterward).

The workflow

prompt → parts → place → connect → route → drc → export

1. parts — parts_search (keyword) then parts_get (pad list) to choose
   real LCSC parts and learn their pin numbers.
2. place — new_board, set_board_outline, then place_component /
   move_component to lay out footprints (mm, y-up).
3. connect — connect_pins builds nets from REFDES.PAD pin refs;
   create_net_class / assign_net_class set track/via/clearance rules.
4. features — add_zone (copper pours), add_mounting_hole, add_silk_text,
   add_keepout.
5. route — autoroute runs Freerouting for bulk routing; add_track /
   add_via place surgical fixes by hand; get_ratsnest / unroute help
   iterate.
6. drc — run_drc reports violations against the JLCPCB ruleset for the
   board's layer count, and checks live JLCPCB assembly stock for every placed
   part: a part with less stock than one board needs is a gating stock-out
   violation; low stock (fewer than 100 boards buildable) and parts missing
   from the JLC library are non-gating advisories. Set
   FLAMINGO_STOCK_CHECK=off to skip the stock half (e.g. offline).
7. export — export_fab runs DRC (fills zones first, including the stock
   check) and writes the JLCPCB fileset — refusing on any violation unless
   waiveDrc is set.

screenshot renders the board to a PNG at any point so Claude can see what it's
doing.

MCP tools

34 tools are served at http://localhost:4242/mcp:

Architecture

npm workspaces monorepo — all packages are ESM, strict TypeScript, tested with
Vitest (packages/*/test/*.test.ts):

packages/
  engine/   pure library: data model, geometry, netlist/ratsnest, zone fill, DRC, ops
  parts/    LCSC search + EasyEDA footprint fetch/parse/cache
  fab/      Gerber X2 + Excellon writers, BOM/CPL writers, DSN export / SES import
  server/   Node: document host, op-log + undo/redo, HTTP + WebSocket, MCP endpoint, CLI, autoroute runner
  ui/       browser PCB view (Canvas 2D) with mouse editing tools

The server is the hub: it owns the live Doc (board + undo/redo), serves the
ui at /, streams changes over /ws, and exposes every editing operation as
an MCP tool at /mcp. Claude Code and the browser both act on the same board.

Development

npm run build   # tsc -p . in every package (+ vite build for the ui)
npm test        # vitest run in every package

The full prompt→fab pipeline is exercised for real (live LCSC parts, real
Freerouting) by:

npx tsx packages/server/scripts/e2e-esp32.ts

which builds the reference board above, asserts a DRC-clean export, and
tracespace-validates every Gerber.

License

MIT — see LICENSE.