hwkit MCP server
by cforcomputer
README.md
# 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](https://github.com/aklofas/kicad-happy)'s circuit review. Boards are autorouted with
[KiCadRoutingTools](https://github.com/drandyhaas/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.
[](https://github.com/cforcomputer/build-hardware-with-ai/actions/workflows/tests.yml)
[](LICENSE)
[](https://cforcomputer.github.io/build-hardware-with-ai/)
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.
## Install
**Claude Code** (skills and MCP tools, plus kicad-happy's skills as a dependency). You need
[uv](https://docs.astral.sh/uv/). Add kicad-happy's marketplace first, so its plugin installs along with this one:
```text
/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, ...):
```json
{
"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+):
```bash
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](https://www.kicad.org/) 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
```bash
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`](examples/demo_parts.py) (an open box and a lid 0.1 mm too low) and
the [two-sided test board](tests/fixtures/lvs/).
```text
$ 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](skills/hardware-project/SKILL.md) | idea to verified order: stages, the gates to have, order day, the tools in and alongside the kit |
| [pcb-fab](skills/pcb-fab/SKILL.md) | 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](skills/printed-parts/SKILL.md) | SLA / MJF / SLM / FDM; walls, holes, threads, hollows, gaps; captive nuts; sweeps and tool access; warp; renders |
| [hand-assembly](skills/hand-assembly/SKILL.md) | hand assembly or fab assembly; hot plate, oven, hot air; lead-free paste and profile; part heat limits; first power-up |
| [part-sourcing](skills/part-sourcing/SKILL.md) | live prices with dates, lifecycle, exact parts and substitutes, datasheets, LCSC / Mouser / DigiKey / McMaster / AliExpress |
| [hardware-simulation](skills/hardware-simulation/SKILL.md) | simulate what changes a decision; known answers, convergence, memory-capped job queue, measure afterwards |
| [optical-instruments](skills/optical-instruments/SKILL.md) | 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](https://agentskills.io) 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](https://github.com/aklofas/kicad-happy) | MIT | v3.0.1 | schematic, layout, Gerber, EMC and thermal review; release gate (`hwkit happy`, part of `review`) |
| [KiCadRoutingTools](https://github.com/drandyhaas/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](https://jlc3dp.com/help/article/3D-Printing-Design-Guideline) | [`rules/jlc3dp.py`](src/hwkit/rules/jlc3dp.py) |
| Boards: tracks, spacing, vias, holes, rings, edges, silkscreen, sizes, thicknesses | [JLCPCB capabilities](https://jlcpcb.com/capabilities/pcb-capabilities) | [`rules/jlcpcb.py`](src/hwkit/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`](src/hwkit/stencil.py) |
| Screws, nuts, washers, holes, length tolerance | ISO 262, 4762, 7380-1, 10642, 4032, 4035, 7089, 273, 4759-1; DIN 985 | [`fasteners.py`](src/hwkit/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`](src/hwkit/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](https://github.com/aklofas/kicad-happy) (MIT) | driven by this kit as the circuit reviewer, and a plugin dependency for its skills |
| [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools) (MIT) | driven by this kit as the router |
| KiCad MCP servers ([KiCAD-MCP-Server](https://github.com/mixelpixx/KiCAD-MCP-Server), [Copperpour](https://github.com/Copperpour/Copperpour)) | they let an agent draw boards; this kit checks and orders them. Use together |
| [build123d-mcp](https://pypi.org/project/build123d-mcp/), [cad-skill](https://github.com/flowful-ai/cad-skill) | they draw parts; `print`, `fit`, `sweep` and `access` check them |
| [claude-hardware-in-the-loop](https://github.com/Kemerd/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](https://github.com/Abdelhayali/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
```bash
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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues