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.

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

🎯 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.

Related MCP server: KiCad MCP SEA

⚡ 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"

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 Files (.kicad_sch)"]
        PCB["📐 PCB Layout (.kicad_pcb)"]
    end

    subgraph Pipeline ["🔍 pcb-inspector Verification Engine"]
        direction TB
        L1["1️⃣ Deterministic Ground Truth<br/><code>kicad-cli</code> (ERC & DRC checks)"]
        L2["2️⃣ Programmatic Engineering Heuristics<br/>(Decoupling, loop areas, return paths)"]
        L3["3️⃣ Multimodal Visual Review<br/>(Vision LLM on 2D/3D renders)"]
        
        L1 --> Aggregator
        L2 --> Aggregator
        L3 --> Aggregator
        Aggregator["⚡ Findings Aggregator & Prioritizer"]
    end

    subgraph Output ["📋 Actionable Report"]
        Report["🔴 CRITICAL • 🟠 WARNING • 🟡 SUGGESTION • 🟢 PASS<br/>Coordinates • Net Names • Evidence • Fix Instructions"]
    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

• 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

Computes configurable spatial, geometric, and electrical heuristics directly from schematic and layout topology:

• Decoupling capacitor placement: Proximity and loop inductance relative to IC power pins.

• Power & ground connectivity: Star routing, plane integrity, and copper pour continuity.

• Switching regulators: DC/DC converter high $di/dt$ switching-loop geometry and diode placement.

• High-current path analysis: Trace width, copper weight, and via current capacity.

• Critical net routing: Sensitive analog traces shielded from high-speed digital switching.

• Ground-plane & return paths: Identification of return path interruptions and ground splits.

• Differential pairs: Length tuning, skew matching, and continuous ground reference.

• Thermal relationships: Proximity of heat-sensitive components to power dissipation hot spots.

3. Multimodal Visual Review

Uses Vision-capable models to inspect rendered 2D and 3D PCB views, catching 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:

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):

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: Modifies schematic & PCB files
    Agent->>Inspector: call tool `inspect_project(path)`
    activate Inspector
    Inspector->>Project: Native DRC + Heuristics + Vision Check
    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), reroute track
        Note over Agent,Inspector: Agent automatically iterates until 🟢 PASS
    else All Checks Pass (🟢 PASS)
        Agent->>Fab: Export Gerbers & send to production!
    end

🛠️ Exposed MCP Tools

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

• inspect_project(project_path: str): Runs the complete 3-layer audit (DRC, Heuristics, Vision) and returns prioritized findings.

• 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:

🚀 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)

• Automated 2D SVG board renderer with top/bottom mirrored views & programmatic fallback

• 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)

Future Enhancements (v0.2.0+)

• 3D raytraced photo-realistic board rendering via Blender / KiCad raytracer

• 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: takzen.app@gmail.com