Skip to main content
Glama
hwkit MCP server

hwkit MCP server

by cforcomputer

build-hardware-with-ai: AI hardware design checks for Claude Code and MCP

An open-source toolkit that lets an AI agent research, design, verify and order real hardware: PCBs, 3D-printed and metal parts, optical setups and the parts list. It works with Claude Code, Codex, Cursor or any MCP client, and runs on your machine. It covers:

  • 3D printing (DFM): measured wall thickness, trapped resin or powder, build volume, supports, mass.

  • Fit and motion: overlaps and gaps between parts, moving parts over their whole travel, screw lengths, tool access.

  • KiCad PCBs: JLCPCB's design rules through KiCad's DRC. The Gerber files are rebuilt and compared with the schematic (shorts, opens), along with BOM and placement files, solder-paste stencils, and kicad-happy's circuit review. Boards are autorouted with KiCadRoutingTools.

  • Parts: live prices from LCSC, Mouser and DigiKey, datasheets and papers, with the source and date on every number.

  • Optics: Gaussian beams through lens trains, objectives and back-aperture fill, focal spots, drag near a wall, Mie scattering, and stiffness calibration from a thermal-motion position record.

  • Heavy jobs: simulations and routing run in a queue with a memory cap.

tests License: MIT Website

It is four things in one repo:

  1. hwkit, a command-line tool. Every check prints PASS / WARN / FAIL with the numbers behind it and exits with code 1 on a FAIL, so it can block an order.

  2. An MCP server (hwkit mcp, 40 tools) that gives any AI agent the same checks. It runs locally, so your files, KiCad install and API keys stay on your machine.

  3. Seven skills (guides an agent reads before acting): the method from idea to order, boards, printed parts, hand assembly, sourcing, simulation, and optical instruments. MCP clients read them with the guide tool.

  4. A project template (hwkit init). Its AGENTS.md holds the working rules for any agent, including a table of the mistakes a real project already made once.

Why

AI agents can write a schematic or a CAD script. Most mistakes happen later, between the file and the parcel:

  • a wall too thin for the process;

  • a lid that clips the case;

  • a carrier that hits its frame at the end of its travel;

  • a screw no driver can reach;

  • a Gerber export that no longer matches the schematic;

  • a stencil that won't release paste;

  • a price quoted from memory, or a chip at end of life.

Each check here exists because a real device project, built with an agent from simulation to ordered boards and printed metal parts, hit that problem.

Related MCP server: pcb-inspector

Install

Claude Code (skills and MCP tools, plus kicad-happy's skills as a dependency). You need uv. Add kicad-happy's marketplace first, so its plugin installs along with this one:

/plugin marketplace add aklofas/kicad-happy
/plugin marketplace add cforcomputer/build-hardware-with-ai
/plugin install build-hardware-with-ai@build-hardware-with-ai

If you skip the first line, the plugin installs but won't load. Claude Code's error tells you to add that marketplace.

Any other MCP client (Claude Desktop, Cursor, Codex, ...):

{
  "mcpServers": {
    "build-hardware-with-ai": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/cforcomputer/build-hardware-with-ai", "hwkit", "mcp"]
    }
  }
}

Command line only (Python 3.11+):

uv tool install git+https://github.com/cforcomputer/build-hardware-with-ai
uv tool install "build-hardware-with-ai[step,fast,optics] @ git+https://github.com/cforcomputer/build-hardware-with-ai"   # all extras

Optional extras:

  • KiCad 8 or newer, for the rule checks and exports.

  • Free Mouser and DigiKey API keys in .env, for prices beyond LCSC.

  • hwkit doctor lists what is installed.

Quick start

hwkit init my-gadget && cd my-gadget     # folders, AGENTS.md, CLAUDE.md, gates.toml, docs/order.md, .env.example
hwkit doctor                             # installed tools and keys
hwkit guide hardware-project             # the method (or ask your agent to read it)
hwkit gates                              # run every gate; results in checks/last_run.md

What the checks say (real output)

The examples below use examples/demo_parts.py (an open box and a lid 0.1 mm too low) and the two-sided test board.

$ hwkit fit case.stl lid.stl --process mjf
  FAIL  case.stl / lid.stl  overlap 38.40 mm3, 60.00 x 40.00 x 0.10 mm around (0.0, 0.0, 19.9)

$ hwkit review tests/fixtures/lvs/lvs.kicad_pcb --order-dir tests/fixtures/lvs
== Order readiness: lvs
  PASS  1. board vs fab limits      passed
  PASS  2. fab files vs board nets  passed
  PASS  3. BOM and placement        passed
  PASS  4. stencil, top             passed
  PASS  4. stencil, bottom          passed

$ hwkit gerbers tests/fixtures/lvs/gerbers tests/fixtures/lvs/lvs.kicad_pcb --selftest
  PASS  planted bridge  R1.1 [N1] to R1.2 [N2], 2.20 mm: reported as a short
  PASS  removed holes   2 of 2 removed plated holes reported as opens

$ hwkit screw M3 --grip 5 --nut hex --room 3
  PASS  length       shortest stock length that works: 10 mm
  PASS  engagement   2.31 to 2.89 mm past the nut face (needs 0.50 mm)

$ hwkit optics calibrate record.npy --fs 50000 --radius-um 0.5    # a simulated sphere held at 0.020 pN/nm
  "stiffness_pn_per_nm": 0.01988, "corner_hz": 377.1

Add --json to any check for the full findings as data.

Commands

Area

Commands

Project

init, doctor, gates, guide [topic]

Printed and machined parts

print FILE --process sla|mjf|sls|slm|bj|fdm, fit A B ..., sweep MOVING FIXED... --slide x,y,z --travel a,b (or --pivot --axis --angles), access PARTS... --start --direction, screw M3 --grip ..., holes M3 --process mjf, render FILES -o x.png, compare --before ... --after ... -o sheet.png

Boards

review BOARD [--order-dir] (everything), pcb, gerbers GERBERS BOARD [--schematic] [--selftest], bom BOARD BOM CPL, stencil, happy PROJECT, route BOARD --tries 3, jlc-rules, limits print|pcb

Parts and research

part NUMBER, prices BOM.csv, lcsc-cart BOM.csv, datasheet PART --find text, papers "query"

Optics

optics beam|expander|objective|spot|drag|calibrate|simulate

Heavy work

jobs submit --mb N -- cmd, jobs list|show|cancel|wait, run --mb N -- cmd, tools [install]

Server

mcp

MCP tools (40)

Area

Tools

Method and project

guide, project_init, doctor, gates_run, decision_log

Printed and machined parts

print_check, fit_check, sweep_check, tool_access, screw_stack, screw_holes, render_views, render_compare

Boards

board_review, pcb_check, gerber_check, gerber_selftest, bom_check, stencil_check, kicad_happy_review, route_board, jlcpcb_rules, fab_limits

Parts and research

part_lookup, bom_prices, lcsc_cart, datasheet_fetch, paper_search

Optics

beam_path, beam_expander, objective_aperture, focal_spot, sphere_drag, brownian_calibrate, brownian_simulate, mie_sphere

Jobs and tools

job_submit, job_status, job_cancel, tools_status

The skills are also served as resources (hwkit://guide/<name>).

Skills

Skill

Covers

hardware-project

idea to verified order: stages, the gates to have, order day, the tools in and alongside the kit

pcb-fab

JLCPCB rules in KiCad, routing in the loop, hwkit review, exact kicad-cli exports, every order-form field, stencils, assembly by the fab

printed-parts

SLA / MJF / SLM / FDM; walls, holes, threads, hollows, gaps; captive nuts; sweeps and tool access; warp; renders

hand-assembly

hand assembly or fab assembly; hot plate, oven, hot air; lead-free paste and profile; part heat limits; first power-up

part-sourcing

live prices with dates, lifecycle, exact parts and substitutes, datasheets, LCSC / Mouser / DigiKey / McMaster / AliExpress

hardware-simulation

simulate what changes a decision; known answers, convergence, memory-capped job queue, measure afterwards

optical-instruments

microscopes and laser instruments: laser safety, objectives and filling, conjugate planes, back-focal-plane detection, thermal-motion calibration, heating, drift, parts

Skills follow the Agent Skills format; copy a folder into your agent's skills directory to use one alone.

Tools it drives (fetched on first use, pinned, checksummed)

Tool

License

Pinned

Used for

kicad-happy

MIT

v3.0.1

schematic, layout, Gerber, EMC and thermal review; release gate (hwkit happy, part of review)

KiCadRoutingTools

MIT

v0.24.0

autorouting (hwkit route); its installer fetches its prebuilt router for your OS

Both download into ~/.cache/hwkit (or HWKIT_HOME) and are checked against a SHA-256. To use your own copy instead, set KICAD_HAPPY_DIR or KRT_DIR. kicad-happy's findings are advisory here. Its keepout check reads a zone's outer outline only, so those findings are re-measured exactly (cut-outs included) and dropped when the exact check clears them.

The project template

hwkit init writes:

  • AGENTS.md: the working rules, and the table of mistakes already made once. CLAUDE.md imports it.

  • gates.toml: one named shell command per claim.

  • docs/order.md: the one order document.

  • docs/decisions.md: the decision log.

  • .env.example for shop keys.

  • Folders: pcb/, mech/out/, sim/, firmware/, order/, checks/, archive/.

Where the numbers come from

Limits

Source (read 2026-11-19)

Code

3D printing: walls by part size, clearances, holes, escape holes, text, tolerances, build boxes

JLC3DP design guideline

rules/jlc3dp.py

Boards: tracks, spacing, vias, holes, rings, edges, silkscreen, sizes, thicknesses

JLCPCB capabilities

rules/jlcpcb.py

Stencils: area ratio 0.66, aspect ratio 1.5; electropolishing at 0.5 mm pitch

IPC-7525; JLCPCB's stencil form

stencil.py

Screws, nuts, washers, holes, length tolerance

ISO 262, 4762, 7380-1, 10642, 4032, 4035, 7089, 273, 4759-1; DIN 985

fasteners.py

Gaussian beams, drag, Faxén, power-spectrum calibration

Siegman (1986); Neuman & Block, RSI 75, 2787 (2004); Berg-Sørensen & Flyvbjerg, RSI 75, 594 (2004)

optics.py

Services change their limits. Before an order, re-read the page. The numbers here are a dated copy of it.

How it fits with other tools

Surveyed 2026-11-19 from each project's README.

Project

Relation

kicad-happy (MIT)

driven by this kit as the circuit reviewer, and a plugin dependency for its skills

KiCadRoutingTools (MIT)

driven by this kit as the router

KiCad MCP servers (KiCAD-MCP-Server, Copperpour)

they let an agent draw boards; this kit checks and orders them. Use together

build123d-mcp, cad-skill

they draw parts; print, fit, sweep and access check them

claude-hardware-in-the-loop (source-available)

a larger framework on the same idea of gates. Its README doesn't mention print checks, screw stacks or prices

CircuitPilot (PolyForm Strict)

an all-in-one app, licensed for use only. This kit is MIT and made to compose

FAQ

Can Claude Code design a PCB that can be ordered? It can draw one with KiCad MCP servers. This kit makes sure the order is right:

  • hwkit route routes it.

  • hwkit review checks KiCad's DRC with JLCPCB's limits, rebuilds the Gerber files and compares them with the schematic, checks the BOM and placement files and the stencils, and runs kicad-happy's review.

How do I check whether a 3D print will work before ordering it? hwkit print part.stl --process mjf measures the walls everywhere and groups the thin areas by size and place. It also finds hollows that trap resin or powder, and checks the build volume, supports and mass.

How do I calibrate stiffness from Brownian motion (power spectrum)? Record the particle's position at a known sample rate, then run hwkit optics calibrate positions.csv --fs 50000 --radius-um 0.5. It fits the aliased Lorentzian spectrum (Berg-Sørensen & Flyvbjerg 2004) and returns the corner frequency and stiffness, plus the detector's metres per volt with --volts. Add --height-um for Faxén's correction.

What beam size fills my objective? hwkit optics objective 60 1.2 --immersion 1.33 --beam-w 4 gives the back aperture (8.0 mm), the fill ratio and the power passed. hwkit optics expander 1.0 4.0 lists telescopes from stock focal lengths.

What are JLCPCB's design rules for KiCad? For 2 layers and 1 oz copper:

  • tracks and spacing 0.10 mm;

  • vias from a 0.15 mm hole with 0.25 mm diameter (a hole under 0.3 mm with a diameter of 0.4 mm or less costs extra);

  • copper at least 0.2 mm from the edge;

  • silkscreen text at least 1.0 mm tall.

hwkit jlc-rules -o board.kicad_dru writes them as KiCad rules.

Does it work without Claude? Yes. hwkit is a plain command-line tool, the MCP server works with any MCP client, and the guides are Markdown.

Limits of this tool

  • Fab rules: JLCPCB and JLC3DP only, for now. Elsewhere, use --min-wall, --build-box and --gap.

  • Wall thickness: measured by rays cast inward from points spread over the surface. A strip beside a hole or slot is a wall too, and the check reports it. Raise --samples for fine parts.

  • Fit, sweep and access are exact on closed meshes. Open meshes fall back to sampling.

  • Warp has no published threshold, so it is reported as information.

  • Optics are paraxial or textbook estimates. Forces of light at a high-NA focus need T-matrix codes.

  • Laser safety is a procedure in the guide, not a calculation. Eyewear and exposure limits come from the standard and a qualified person.

  • Sourcing: LCSC lookups need C-numbers. Mouser and DigiKey need free keys. Thorlabs and McMaster have no open price API.

  • Memory caps (hwkit run and the job queue) sample memory every 0.25–0.5 s.

  • Not affiliated with JLCPCB, LCSC, Mouser, DigiKey, McMaster-Carr, Thorlabs, Anthropic, or the authors of the tools it drives.

Development

git clone https://github.com/cforcomputer/build-hardware-with-ai && cd build-hardware-with-ai
uv venv && uv pip install -e ".[dev,optics]"
.venv/bin/python -m pytest              # HWKIT_LIVE=1 also queries LCSC
claude plugin validate .

Tests use known answers. Each line below is something the tests check:

  • A 0.3 mm gap measures 0.300 mm.

  • A planted copper bridge is reported as a short.

  • A removed via is reported as an open.

  • A 1 mm beam through f = 100 mm focuses to λf/πw.

  • A simulated particle's stiffness comes back within 6%.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables language models to perform hardware engineering tasks including CAD part design and heat transfer simulations. Provides tool calls for building mechanical components and running thermal analysis through natural language interactions.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to audit KiCad PCB designs through deterministic DRC/ERC checks, spatial heuristics, and multimodal vision review, returning structured, prioritized findings with coordinates and fix guidance.
      9
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to turn natural-language hardware prompts into deterministic schematics and netlists, query live LCSC parts data, validate designs, calculate trace impedance, and estimate PCBA BOM costs through stdio MCP tools and resources.
      84
      158 PyPI
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to author, read, critique, and validate production CAD drawings through 247 typed tools spanning mechanical parts, architectural plans, P&IDs, takeoffs, and ISO GD&T / dimension-tolerance checks. It drives live AutoCAD over COM on Windows or runs headlessly anywhere via ezdxf, with pack and discovery modes to keep the advertised tool surface cheap.
      -