Model Lab

Model Lab

Game gun models drawn in Blender from parameters, rigged and checked against the real gun.

[license: MIT] [Python 3.10+] [PyPI: modellab-mcp] [MCP Registry: modellab-mcp] [Blender: 4.2+] [tools: 10] [presets: 5 AR-15s]

An MCP server that draws game gun models in Blender from a few parameters. Each build has real parts at real proportions, one bone a moving part, its clips, and the facts a game needs. Every build checks itself, and a second check measures its outline against a photo of the real gun.

[An AR-15 with a holographic sight, a magnifier, a light and a vertical grip]

Ask for "an M4A1 with a red dot and a light on the right rail" and Model Lab writes a rigged FBX, an FBX for each attachment, a .blend, a sheet of pictures and a facts.json with every mark in gun space. It tells you which checks failed, if any. It makes game models only: outside shapes and moving parts. It draws no working internals and writes no fabrication data.

What a build gives you

Gun space: centimetres, +X the gun's left, +Y forward, +Z up. The origin is the bolt face at rest on the bore.

[An M4A1 from its right side]

Install

Model Lab needs Python 3.10 or later and Blender 4.2 or later.

uvx modellab-mcp

or

pip install modellab-mcp

Add it to your MCP client (Claude Code, Claude Desktop, or any client that runs stdio servers):

{  "mcpServers": {    "modellab": {      "command": "uvx",      "args": ["modellab-mcp"],      "env": { "MODELLAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 4.2/blender.exe" }    }  }}

The tools

The same calls run from a shell: modellab presets, modellab build M4A1 stock_pos=2 name=MyM4, modellab clips <build>, modellab compare. Run modellab help for the list.

Every build checks itself

A build reports each check with its value. The checks:

• the length against the published figure (the M4A1 at 29.75 and 33 in, the M16A2 at 39.63 in);
• the chamber on the bore;
• the dust cover: closed over the whole port, hinged on its bottom edge, and open against the lower, not through it (the build swings it a degree at a time and stops it where it first touches);
• the magazine clear of its well's walls and seated;
• the bolt's travel past the top round;
• the sight line: the rear aperture and the front post at one height;
• each attachment on a rail it fits, clear of the gun in every state, and its optic on the iron sight line;
• every visible part with its real features (parts_complete). The parts table lists each part a person sees on the real gun and the features that make it read as that part: the charging handle's swept wings, finger hooks, latch and roll pin; the bolt catch's serrations; the castle nut's notches; the front sight base's bayonet lug, swivel and taper pins; and so on. A missing feature fails the build. Marks such as rail numbers are listed as texture, not shape.

[Close views: the charging handle]

The real-gun check

compare_to_reference draws the build's side outline at a reference photo's own scale. It lines the build up on the muzzle and the bore, measures both outlines column by column, and names the parts where they differ. The overlay shows the model in see-through red over the photo: dark photo showing through is real gun the model misses.

[The M4A1's outline over the reference photo]

This check found the faults the self-checks could not: the lower 1.55 cm too far back, the front sight base 2.4 cm back and the wrong shape, the stock's outline, the magazine's curve, and the rail's height. Now no stretch of the gun's outline over 1.75 cm long is more than 1 cm off. Attachments are classes, not the photo's exact models, so the check keeps their outline apart.

The reference ships with the package: a photo of an M4A1 carbine from PEO Soldier, File:M4A1-flattop.jpg on Wikimedia Commons, in the public domain as a work of the US Federal Government. The check reads its scale from the rail's teeth, 0.394 in apart.

Attachments on sockets

Each rail reports its slots at the Picatinny pitch (MIL-STD-1913), slot 0 at the rear. M-LOK handguards report their slots too (32 by 7 mm, 40 mm apart). Pass attachments by name, or as {item, rail, slot, state, options}:

{"preset": "M4A1", "params": {"attachments": [{"item": "flip_rear", "state": "down"}, "red_dot", "weapon_light"]}}

The nine classes: folding rear and front sights, the M4's carry handle, a 30 mm red dot with flip caps, a holographic sight, a 3x magnifier on a flip mount, a 4x32 prism sight, a vertical grip, a weapon light. A build checks that each fits its rail, clears the gun in every state, and clears the others as shown. When one blocks another's move, the build lists it: behind a magnifier, the rear sight goes up only after the magnifier swings aside.

[The sight picture through a red dot, the A2 post in its middle]

Motion and clips

Every .blend holds the cycle as an action. motion=true renders it as GIFs: the charging handle drawn back, the cover springing open, the carrier flying home, the magazine out and in, then the attachments' own moves.

[The cycle on an AR-15 with a magnifier and a holographic sight]

build_gun_clips keys the gun's clips at 60 frames a second from real timings: charge, chamber check, fire (a 75 ms cycle), the last shot (the bolt held on its catch), reload, empty reload, and the stock's positions. Each clip is measured: every part on its own axis, the full stroke, the cover open before the carrier has moved 1 cm, the magazine out of the well and seated, the bolt held until the magazine is in.

[An empty reload: the bolt held open until the new magazine is seated]

Next: soft edges where a hand holds

The owner, 2026-10-21: "the grip is no sharp edge, this will be the next improvement for Model Lab when read on the manual or images, make the corner round a bit, especially the places that human grab and hold, most of the time they will no sharp edge because sharp edges will hurt the hand/human, make them softer so hand can hold it".

• Every part a hand grabs or holds gets rounded edges: the grip, the pistol grip's panels, the handguard, the magazine, the charging handle, the stock's cheek and butt.
• Each radius is read from the manual, drawing or photo when it shows one. Otherwise it comes from a named human-engineering source, recorded with the part.
• The real-gun check compares these edges too.

Why it matters, measured: on a digitized M1911A1 the grip safety was a square extrusion. A hand placed on the grip had the safety's edge 0.42 cm in its palm (the palm gives 0.27 cm). Rounding the grip parts by 0.75 mm, the least MIL-STD-1472G 5.7.7.6 allows, cut that to 0.09 cm past the give. Red: before (sharp). Blue: after (rounded). Below, close-ups of the spot before and after.

[The palm's clip against the grip safety, sharp and rounded]

Limits

• One platform so far: the AR-15 family. Others will follow.
• One reference photo: the M4A1 from its right side.
• The clips are the gun's side only. A hand's clips need an arms rig.
• No selector clip yet: the lever's direction at SAFE is not yet checked against a source.
• Many numbers are estimates sized from photographs. describe_params lists every source and every estimate.

Trademarks

M-LOK is a trademark of Magpul Industries. Model Lab draws M-LOK slots to their published dimensions and is not connected with Magpul. AR-15 is a trademark of Colt's Manufacturing; here it names the rifle family in its common sense. Military designations (M4A1, M16A2, M68) name the guns and parts Model Lab copies. No product is endorsed.

License

MIT. See LICENSE.