pcb-inspector

mcp
Security Audit
Pass
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 10 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Automated 3-layer design review and linter for KiCad (DRC/ERC, spatial heuristics, multimodal vision AI, and native MCP server)

README.md
pcb-inspector icon

pcb-inspector

Automated Multimodal Design Reviewer & Linter for KiCad Projects

Catch placement flaws, decoupling issues, routing problems, and mixed-signal design risks before sending your board to fabrication.

License: MIT Release: v0.1.0 Tests: 422 passed KiCad Support Python MCP Server Multimodal AI PRs Welcome

🎯 What is it? • ⚡ Quickstart • 📖 User Manual • 🧠 Verification Pipeline • 🤖 MCP Server & Agent Loop • 🏗️ Architecture • 🚀 Use Cases • 🛠️ Roadmap • 📄 License


[!NOTE]
pcb-inspector v0.1.0 is now live!
The 3-layer verification engine, built-in MCP server, interactive HTML reporting, and GitHub Action are fully functional. Check out the 📖 User Manual & Configuration Guide (MANUAL.md) for practical examples, rule catalog, and per-project override guides.

🎯 What is it?

pcb-inspector is a multi-layer hardware verification and design-review pipeline for KiCad projects.

Traditional DRC/ERC tools are essential, but they primarily verify explicit electrical and geometric rules. pcb-inspector adds higher-level layout analysis, engineering heuristics, and multimodal visual review to identify potential design issues that may pass standard CAD checks.

It can run standalone as a CLI or GitHub Action on manually designed boards, or integrate with agentic PCB workflows such as Konnect to create a closed-loop design → audit → fix → verify workflow.

[!TIP]
Don't just generate a PCB. Independently inspect it before you manufacture it.
Design. Inspect. Fix. Verify.


⚡ Quickstart & Installation

Installation

# Using uv (recommended)
uv pip install pcb-inspector

# Or install from source
uv pip install "git+https://github.com/takzen/pcb-inspector.git"

# Optional: Claude (Fable / Opus) as the vision model
uv pip install "pcb-inspector[claude]"

[!IMPORTANT]
Layer 1 (DRC/ERC) and hosted vision renders both need KiCad 8+ with kicad-cli on PATH
(or kicad_cli_path in the config). Without it, Layer 1 is reported as not run rather than
silently skipped; pass --require-kicad-cli to make that a failure, as the bundled GitHub
Action does.

Essential CLI Commands

# 1. Full 3-layer audit (DRC + Heuristics + Vision) with interactive HTML report
pcb-inspector check path/to/board.kicad_pcb -o report.html -f html

# 2. Fast deterministic DRC/ERC only (native KiCad)
pcb-inspector drc path/to/board.kicad_pcb

# 3. Spatial & physical engineering heuristics only
pcb-inspector analyze path/to/board.kicad_pcb

# 4. Dedicated Multimodal AI Vision Review (Gemini Flash 3.8, Fable 5, GPT-6 Astra)
pcb-inspector vision path/to/board.kicad_pcb --model gemini-3.8-flash

# 5. Continuous Watch Mode (automatically re-checks on board save)
pcb-inspector check path/to/board.kicad_pcb --watch

# 6. Launch Model Context Protocol (MCP) server for AI agents
pcb-inspector mcp --transport stdio

🧠 Multi-Layer Verification Pipeline

pcb-inspector approaches design verification through three complementary layers of defense:

flowchart TD
    subgraph Input ["📥 Design input"]
        SCH["📄 Schematic<br/>.kicad_sch"]
        PCB["📐 PCB layout<br/>.kicad_pcb"]
    end

    subgraph Pipeline ["🔍 Verification engine"]
        direction TB
        L1["1️⃣ Ground truth<br/>kicad-cli<br/>ERC and DRC"]
        L2["2️⃣ Heuristics<br/>decoupling,<br/>loop areas,<br/>return paths"]
        L3["3️⃣ Vision review<br/>LLM on<br/>board renders"]
        Aggregator["⚡ Aggregate<br/>and prioritise"]

        L1 --> Aggregator
        L2 --> Aggregator
        L3 --> Aggregator
    end

    subgraph Output ["📋 Report"]
        Report["🔴 CRITICAL<br/>🟠 WARNING<br/>🟡 SUGGESTION<br/>🟢 PASS<br/>coordinates, nets,<br/>evidence, fixes"]
    end

    Input --> Pipeline
    Aggregator --> Output

1. Deterministic Ground Truth

Runs KiCad's native verification tools through kicad-cli:

  • ERC — Electrical Rules Check
  • DRC — Design Rules Check
  • Connectivity & netlist verification, including schematic parity: footprints missing from
    or extra on the board and pads on the wrong net, grouped by kind
  • Clearance and short-circuit detection
  • Unconnected pins and nets
  • Manufacturing and fabrication constraint violations

These results form the deterministic baseline for the entire audit.


2. Programmatic Design Analysis

Five rules computed directly from the layout, reading the design intent KiCad records: net classes
from the .kicad_pro, the copper stack order, and each pad's schematic pin name.

  • Decoupling capacitor placement (HEUR-DEC-001) — distance from every IC supply pin to its
    nearest bypass capacitor, adding the board thickness for capacitors on the opposite side. Supply
    pins are recognised by their schematic pin name (VDD, VCC, 3.3V, +VS…) as well as the
    net name; a bias or reference net such as BIAS_1.65V is not mistaken for a rail.
  • Power rail trace width (HEUR-PWR-001) — one finding per net and layer. A trace narrower
    than its own net class is a warning; one that matches its net class but sits below the
    configured power-rail guideline is a suggestion, since KiCad treats net class widths as defaults.
  • Differential pair skew (HEUR-DIFF-001) — length mismatch across _P/_N, +/-,
    _DP/_DM and H/L pairs, counting curved (arc) routing and via transitions. Only pairs named
    as a fast interface (USB, HDMI, PCIe, LVDS, Ethernet, clocks…) can be critical; a CAN bus or an
    analog sensor pair is a suggestion, since millimetres of skew are picoseconds.
  • Switching regulator loop area (HEUR-DCDC-001) — switching nodes confirmed by a declared
    SW/LX pin or by inductor-to-converter topology, never by net name alone.
  • Ground reference (HEUR-GND-001) — the share of each signal segment lying over a ground
    plane on an adjacent copper layer, read from the board's physical stack order.

[!NOTE]
Thresholds are configurable globally and per rule via custom_rules in YAML; any rule can be
disabled there. See MANUAL.md for every key.

Not yet implemented, and listed in the Roadmap: thermal proximity of
heat-sensitive parts to hot spots, analog/digital separation, copper-weight and via current
capacity, and star-routing checks.


3. Multimodal Visual Review

Each side of the board is raytraced to PNG with kicad-cli pcb render and reviewed in its own
request by Gemini, OpenAI or Claude (Fable/Opus). The API key is read from the chosen provider's
own variable — GOOGLE_API_KEY or GEMINI_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY —
exported or kept in a .env file in the directory you run from; use --vision-model mock to
run offline. A spent daily quota is reported at once rather than retried. Hosted models need the kicad-cli render; the tool refuses to send them anything
else rather than fail at the provider. Vision models catch layout anti-patterns that resist
formulation into rigid CAD rules:

  • Component placement: Clustering balance, awkward orientations, and assembly congestion.
  • Routing aesthetics & quality: Unnecessary detours, awkward acute angles, and excessive vias.
  • Silkscreen & DFM: Overlapping silkscreens, unreadable reference designators, and obstructed testpoints.
  • Polarity & Pin 1: Missing or ambiguous diode/electrolytic polarity and IC Pin 1 indicators.
  • Mechanical fit: Edge clearance, mounting hole keepouts, and connector access clearances.
  • Schematic intent vs. PCB: Visual cross-check ensuring physical layout reflects functional schematic grouping.

Vision review acts as an automated "peer engineer over your shoulder" — probabilistic guidance backed by deterministic verification.


4. Structured, Actionable Feedback

Produces a clean, prioritized report tailored for both human review and automated agent consumption:

Severity Meaning Example
🔴 CRITICAL Functional failure or manufacturing blocker DRC short, bypass capacitor on wrong side of via
🟠 WARNING Signal integrity, thermal, or EMI hazard High-speed trace crossing ground slot, undersized power trace
🟡 SUGGESTION DFM, readability, or best-practice refinement Obscured silkscreen, sub-optimal component rotation
🟢 PASS Clean verification All power rails decoupled within target metrics

Each finding includes:

  • Component designators (e.g., U1, C14, L2)
  • Affected nets & physical PCB coordinates $(X, Y)$
  • Measured values vs. expected thresholds
  • Visual snapshots / highlighted bounding boxes
  • Concrete, actionable remediation instructions

🤖 MCP Server & Agentic Integration

pcb-inspector provides a native Model Context Protocol (MCP) server, making it a drop-in verification tool for AI coding and design agents (Claude Desktop, Cursor, Antigravity).

🤝 The Dual-MCP Synergy: Konnect + pcb-inspector

In modern autonomous hardware workflows, agents need both actuators (to edit KiCad designs) and sensors/auditors (to verify physical correctness):

Role MCP Server Function
The Hands (Actuator) Konnect (by mixelpixx) Adds components, connects pins, routes traces, modifies footprints in KiCad.
The Brain & Eyes (Auditor) pcb-inspector (this project) Validates DRC/ERC, decoupling proximity, switching loops, ground cuts, and silkscreen DFM.

Together, they enable a closed-loop autonomous self-correction loop:

sequenceDiagram
    autonumber
    participant Agent as 🤖 Autonomous Agent (Claude / Cursor)
    participant Konnect as 🖐️ Konnect MCP (KiCad Actuator)
    participant Project as 📁 KiCad Project (.kicad_pcb)
    participant Inspector as 👁️ pcb-inspector MCP (Auditor)
    participant Fab as 🏭 Fabrication (JLCPCB / PCBWay)

    Agent->>Konnect: place_component / route_track
    Konnect->>Project: Edits the board live in KiCad (IPC API, undoable)
    Agent->>Inspector: call tool `inspect_project(live=true)`
    activate Inspector
    Inspector->>Project: Snapshot of the open board, then DRC + Heuristics + Vision
    Inspector-->>Agent: Returns structured JSON findings + coordinates
    deactivate Inspector

    alt Violations Found (e.g. Decoupling too far, DRC clearance)
        Agent->>Konnect: Move C3 closer (< 3.5mm), dry run first, reroute track
        Note over Agent,Inspector: Agent automatically iterates until 🟢 PASS
    else All Checks Pass (🟢 PASS)
        Agent->>Fab: Export Gerbers & send to production!
    end

Konnect edits the board in the running KiCad; the file on disk changes only when someone
saves. The audit step therefore reads the open board with live=true (or --live on the
CLI), unsaved edits included, through KiCad's API. It needs pip install 'pcb-inspector[live]'
and Preferences → Plugins → Enable KiCad API in KiCad 10. Konnect's own plans are worth
auditing before they are applied: on a real board its place_decoupling_caps dry run for one
op-amp gathered every capacitor sharing ground, scoring itself 70 → 10.

🛠️ Exposed MCP Tools

When launched with pcb-inspector mcp, the server provides:

  • inspect_project(project_path: str = "", live: bool = False): Runs the complete 3-layer audit (DRC, Heuristics, Vision) and returns prioritized findings. Every tool takes live=true in place of a path.
  • check_decoupling(pcb_path: str, max_distance_mm: float = 3.5): Rapid spatial analysis of IC power pins and decoupling bypass capacitors.
  • run_drc(pcb_path: str): Fast deterministic DRC check returning structured clearance and connectivity violations.
  • get_actionable_fixes(project_path: str): Machine-readable $(X, Y)$ coordinate patches and step-by-step remediation commands for agents.

🏗️ Design Philosophy

pcb-inspector enforces a strict separation of concerns across its verification tiers:

Layer Purpose Authority Predictability
KiCad DRC/ERC Explicit electrical & geometric constraints Deterministic Exact
Programmatic Analysis Measurable engineering heuristics & physics Deterministic / Configurable High
Vision Review Spatial sanity, aesthetics & assembly review Probabilistic Heuristic

[!IMPORTANT]
No single layer catches everything. By stacking deterministic CAD checks with spatial analytics and visual AI, pcb-inspector achieves coverage that standard DRC cannot match.


🚀 Use Cases

  • 🤖 AI-Generated PCB Designs: Autonomous validation for LLM/agent-designed boards.
  • ⚡ Mixed-Signal & Audio: Protecting analog front-ends from noisy digital microcontrollers.
  • 🔋 Power Electronics: Verifying DC/DC buck/boost switching loops and thermal copper pours.
  • 📡 RF & High-Speed Digital: Return paths, differential pair continuity, and keepout verification.
  • ⏱️ Pre-Fabrication Sanity Check: Catching Silkscreen, footprint, and assembly bugs before purchasing silicon.
  • 🔄 CI/CD for Hardware: Automated regression testing on every Git pull request.

🛠️ Roadmap & Progress

v0.1.0 (Released)

  • Three-tier verification architecture design & domain data models
  • KiCad 8 / 9 / 10 CLI automation wrappers (kicad-cli) & DRC/ERC JSON parsers
  • Programmatic spatial & physical heuristics (decoupling, DC/DC loops, return paths, diff pairs, power traces)
  • Multimodal vision inspection engine (Gemini Flash 3.8, Fable 5, GPT-6 Astra)
  • Board renderer for vision review (superseded — see Unreleased)
  • Built-in Model Context Protocol (MCP) Server (pcb-inspector mcp) for autonomous agent loops
  • Konnect agentic closed-loop integration & ActionableFix auto-repair coordinates
  • Continuous watch mode (--watch) for real-time iterative layout reviews
  • Multi-format reporting: Interactive HTML5 (zero CDN), Markdown, JSON, and Terminal Rich
  • Reusable GitHub Action (.github/actions/pcb-inspector) for CI/CD pipelines
  • Golden Sample reference benchmark boards (clean_board & flawed_board)

Unreleased — reliability and accuracy

  • Live audits of the board open in KiCad 10 (--live, MCP live=true), so a repair loop
    driven through Konnect sees its own unsaved edits
  • Vision reads its API key from .env too, accepts GOOGLE_API_KEY as Google's own tools
    do, and stops retrying once a daily quota is spent (verified against the live Gemini API)
  • Checked against a real KiCad 10 analog board: the CLI no longer crashes on ERC titles
    such as ERC [/]:, supply rails are recognised the same way by every rule (+3.3V was
    missed, BIAS_1.65V was taken for one), and DRC checks schematic parity
  • A target holding no board or schematic is a usage error (exit 2), no longer a PASSED
    audit with a 100/100 health score; the MCP tools return an error for it too
  • Never report a clean board for work not done: failed or missing kicad-cli is a finding,
    every run records which layers executed, and the GitHub Action installs KiCad
  • Parser reads the KiCad 10 file format (nets named inline), curved (arc) tracks,
    multi-layer zones, net classes, the layer stack and pad
    pin names; pad positions match pcbnew exactly
  • Heuristics fixed for false positives on connectors, SWD/PHY nets and matched pairs, with
    repair actions keyed to the rule that produced them
  • Vision review works with hosted models: raytraced PNG per side via kicad-cli pcb render,
    Claude through the Anthropic SDK with refusal fallbacks, Gemini requests reach the configured
    model instead of being rewritten to gemini-2.0-flash
  • Findings correlation, ground-reference check and watch mode made fast enough for
    26,000-track boards
  • HTML report search and category filtering; smoke tests over KiCad's own demo boards

Future Enhancements (v0.2.0+)

  • Thermal rule: heat-sensitive parts near power dissipation hot spots
  • Analog/digital separation: analog traces crossing digital buses or plane splits
  • Via current capacity and copper-weight-aware trace width
  • Star-routing and ground-split checks
  • Direct Gerber (RS-274X) & Excellon drill file fabrication inspection
  • Automated IPC-2221 conductor spacing & current-carrying capacity calculator
  • Differential TDR waveform simulation for transmission lines

⚠️ Engineering Disclaimer

pcb-inspector is an automated design-review tool, not a substitute for professional engineering certification. Vision models and heuristic checks may yield false positives or overlook specific corner-case failure modes. Final sign-off and safety-critical decisions remain the sole responsibility of the engineer.


📄 License & Author

This project is licensed under the MIT License — see the LICENSE file for complete details.

Author & Maintainer:
👤 Krzysztof Pika (@takzen)
📫 Contact: [email protected]

Reviews (0)

No results found