Gridfinity MCP

A local MCP 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 geometry engine (CadQuery / OpenCascade).

Tools

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

Related MCP server: 3D MCP Server

Install

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.

{
  "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.