# Gridfinity MCP

A local [MCP](https://modelcontextprotocol.io) server that turns natural-language
requests into printable Gridfinity STL/STEP files. No more dragging sliders on a
website — ask Claude for "a 6×1 tray split into 3, 4 units tall" and get an STL.

It wraps the [cqgridfinity](https://github.com/michaelgale/cq-gridfinity)
geometry engine (CadQuery / OpenCascade).

## Tools

| Tool | What it makes | Key inputs |
|---|---|---|
| `gridfinity_generate_box` | A bin | `length_u`, `width_u`, `height_u`, `length_div`, `width_div`, `holes`, `scoops`, `labels`, `no_lip`, `solid` |
| `gridfinity_generate_baseplate` | A baseplate grid | `length_u`, `width_u`, `corner_screws`, `ext_depth` |
| `gridfinity_generate_drawer_spacer` | Edge fillers to fit baseplates into a real drawer | `drawer_width_mm`, `drawer_depth_mm`, `tolerance` |

Units: 1 grid unit = **42 mm** (X/Y), 1 height unit = **7 mm** (Z). All geometry
is standard 42 mm Gridfinity, so everything is cross-compatible with off-the-shelf
Gridfinity parts. Files are written to `GRIDFINITY_OUTPUT_DIR` (default `~/Gridfinity_STL`).

## Install

```bash
cd gridfinity-mcp
python3 -m venv .venv && source .venv/bin/activate   # recommended
pip install -r requirements.txt
python3 smoke_test.py        # confirms the CAD kernel renders on your machine
```

`cqgridfinity` pulls a matched CadQuery + OpenCascade (`cadquery-ocp`) automatically.
CadQuery also needs `nlopt`, which has prebuilt wheels for normal desktop platforms.

## Add it to Claude

Add to your MCP config (Claude Desktop: `claude_desktop_config.json`; Claude
Code / Cowork: `.mcp.json`). Use absolute paths.

```json
{
  "mcpServers": {
    "gridfinity": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/gridfinity-mcp/gridfinity_mcp.py"],
      "env": { "GRIDFINITY_OUTPUT_DIR": "/ABSOLUTE/PATH/TO/Gridfinity_STL" }
    }
  }
}
```

If you used a venv, point `command` at that venv's python, e.g.
`/ABSOLUTE/PATH/TO/gridfinity-mcp/.venv/bin/python`.

## Fitting a 42 mm grid into a non-grid drawer

Real drawers are rarely a multiple of 42 mm. The standard Gridfinity approach (and
what this server does) is: lay the largest whole-cell baseplate that fits, then fill
the leftover lip with spacers. Call `gridfinity_generate_drawer_spacer` with the
interior drawer size — its summary tells you the baseplate cell count to generate.

### Worked example — the kitchen drawer (335 × 500 mm interior)

This keeps the freestanding utensil organizer and fills the rest:

- **Catch-all area (front-left, ~257.5 × 100 mm):** baseplate `6 × 2` (252 × 84 mm) + a `6 × 2` box, or two `3 × 2` boxes.
- **Back strip (~257.5 × 45 mm):** baseplate `6 × 1` + a `6 × 1` box.
- **Spatula strip (right wall, ~77.5 × 500 mm):** baseplate `1 × 11` (split for the bed) + boxes; the 77.5 mm width leaves a ~35 mm lip — fill it with a drawer spacer.
- **Lip everywhere:** run `gridfinity_generate_drawer_spacer(drawer_width_mm=335, drawer_depth_mm=500)` to take up the slack so nothing slides.

> Note on the trade-off vs. gridfinitygenerator.com: that website can set a *custom
> grid unit* and *custom outer size* to fill odd widths exactly, but those bins no
> longer interchange with standard 42 mm parts. This server keeps the true 42 mm
> standard and absorbs odd drawer dimensions with spacers instead. Pick based on
> whether cross-compatibility matters to you (it does for the toolbox project).

## Notes / limits

- v1 covers box, baseplate, and drawer spacer. `GridfinityRuggedBox` (lidded cases)
  and a custom grid-unit option are easy follow-ups.
- Generation is CPU-bound; large/complex models take a few seconds.

## Troubleshooting

**`AttributeError: 'TopoDS_*' object has no attribute 'HashCode'` when rendering.**
This means CadQuery and its OpenCascade kernel (`cadquery-ocp`) are a mismatched
pair — OpenCascade 7.8+ removed `HashCode`, which older CadQuery still calls. Fix
by letting pip resolve them together (`pip install cqgridfinity`) or by pinning a
matched pair, e.g. `cadquery==2.7.0` with `cadquery-ocp==7.8.1.x`. Don't install a
newer `cadquery-ocp` than your CadQuery version supports.

**`ModuleNotFoundError: No module named 'nlopt'` / nlopt fails to build.**
CadQuery needs `nlopt`, which ships prebuilt wheels for mainstream desktop
platforms. On an unusual arch with no wheel it tries to build from source and
needs `cmake` + a C/C++ toolchain. Use a platform with a prebuilt wheel, or
install the build tools.

## Bundled skill

`skills/gridfinity/` is a Claude skill that captures the custom-pitch
drawer-fitting workflow and bundles `scripts/check_fit.py` (measure exported
STLs, verify bins seat on baseplates, sanity-check drawer fit). Install it via
your client's skill/capabilities settings, or package it with skill-creator.