localgen-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@localgen-mcp generate an image of a cozy cabin in a snowy forest"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
localgen-mcp
A local MCP server that lets agents generate images, video and 3D meshes on this machine's GPU, fully offline, through one shared ComfyUI backend that starts on demand and shuts itself down when idle.
Localhost and offline only. The managed ComfyUI binds
127.0.0.1and always runs with--offline(no partner or API nodes, a restrictive CSP for its frontend). Hub lookups are disabled withHF_HUB_OFFLINE=1. The network is used only by the setup scripts, to fetch software and weights.Nothing resident when idle. The MCP server imports no ML libraries. ComfyUI runs only while there is work, and its process is killed after the idle timeout (default 300 s), which releases all VRAM and RAM.
One backend for every agent. Each agent session runs its own MCP server process; they all share a single ComfyUI instance, coordinated with file locks.
Returns file paths, plus the seed and settings used, so results can be reproduced.
Tools
Tool | What it does |
| Text to image (Z-Image Turbo). With |
| Text to video, or image to video with |
| Textured GLB from |
| Game weight copy of any textured GLB: quad remesh (Instant Meshes) or decimation to |
| Texture an existing mesh (GLB, glTF, OBJ or STL) from a prompt and optional |
| Build a model as separate part meshes from a front view concept and a box for each part, assembled in place and rigidly rigged (one bone per part, pivoting at the joints). Writes a GLB and an FBX. About 1 to 2 minutes per part. |
| Tileable PBR surface material from a prompt (optional |
| Consistent front, left, back and right views (optionally three-quarter views too) of one object from a concept image or a prompt: flat lit, plain background, framed at one scale for Pixal3D's rig, plus a sheet. By default each view is painted over a render of a TRELLIS.2 guide mesh from the rig's cameras, so flat objects turn properly. |
| Cut the subject out of 1 to 64 images in one batch (BiRefNet): RGBA PNGs with a transparent background. Optional |
| Text to speech for game dialogue (Kokoro-82M, English, on the CPU): 24 kHz WAV plus OGG, in one of 28 voices or a blend, with an optional |
| The installed voices (accent, gender, quality grade), the effects, and whether ffmpeg was found. |
| Soft rig for an organic creature: bone chains ( |
| Upscale a PNG or JPEG 2x or 4x with a super resolution model: Real-ESRGAN x4plus for concept art and general images, or 4x-PBRify V4 ( |
| Whether the backend is running and managed, the effective idle timeout, queue length, GPU memory, and which models are installed. |
| Warm the backend ahead of a batch, optionally with a longer |
| Stop it now to free memory. Refuses while jobs are queued unless |
Every generation tool takes optional output_dir, seed, model and idle_timeout_seconds. Outputs default to /ai/output/localgen/<modality>/<date>/. Long jobs send MCP progress notifications.
Image to image and masked editing
generate_image(input_image=..., denoise=..., mask_image=...) starts from an image instead of noise.
Image to image: the input is VAE encoded and sampled with partial
denoise(0.05 to 1.0, default 0.6 for Z-Image Turbo). Z-Image holds on to the input strongly: at 0.3 and 0.6 only fine detail changes, at 0.9 the layout stays and colours and materials change, and 1.0 ignores the input. The prompt describes the whole result.Denoise with few steps: KSampler runs
stepssteps of anint(steps / denoise)step schedule, so at Z-Image's 8 steps any denoise from 0.89 up would be a full schedule from pure noise (measured: 0.9 gave an unrelated image). The graph picks 8 to 16 steps so the applied value is within 0.01 of the request up to 0.9; above that it is at most 0.94 (16 of 17 steps), so below 1 the input always counts. Klein's custom sampler gets the same treatment.Size: any input size works. It is worked on at about 1 megapixel with both sides a multiple of 16 and resized back, so the output has the input's size;
widthandheightare refused withinput_image.Mask: a black and white image, white = change, black = keep, read from its red channel and stretched to the input if its size differs. Sampling is limited to the mask (
SetLatentNoiseMask), then the result is pasted over the original (ImageCompositeMasked) with the mask grown and feathered by 8 pixels. Every pixel more than about 18 px outside the white area is the original's, byte for byte (measured below). To replace what is in the region usedenoise1.0; to recolour an object, Klein follows the prompt better than Z-Image, which at 0.9 keeps some of the old colour.With
reference_images(ormodel="flux2-klein-4b"): FLUX.2 Klein editsinput_imageas image 1, with the references as images 2 to 4 (so at most 3). It starts from the input's latent too, withdenoisedefault 1.0, which is Klein's usual reference guided edit;mask_imagelimits it the same way.Refused combinations:
mask_imageordenoisewithoutinput_image, andwidthorheightwith it.Measured through the MCP server on a 1024x1024 image (Z-Image at 0.9, and Klein) and a 1001x757 one with a 433x311 mask (Z-Image at 1.0): no pixel more than 18 px outside the mask changed; from 16 to 18 px at most by one level; from 8 to 16 px by at most 8 (34 for Klein). Without the composite step, 99% of the pixels outside the mask changed by up to 22 levels (the VAE round trip).
The input's alpha channel is dropped (the output is RGB). Like every input image, the mask is uploaded only after a content check.
Multi-view framing
Pixal3D assumes a fixed camera rig: views 90 degrees apart, the object centred and at the same scale in every view.
framing="crop"(default, as in ComfyUI's template) crops each view to its own outline. This keeps the scale when the object's widest extent is the same in every view, as for a standing figure or a character turnaround sheet. For an object much wider from the front than the side it stretches the side views, and the mesh comes out too deep.framing="as_framed"uses square views exactly as given. Use it for 3D renders or turnarounds already framed like the rig (object about 1/1.1 of the frame at its widest, 20 degree horizontal FOV);scripts/render_glb_views.pyrenders that framing.remove_background=falsetakes the mask from the images' own alpha channel instead of BiRefNet.
Retopology
Generated meshes are about 300k faces with textures baked for that mesh. For a game asset:
generate_mesh(face_count=...)(5000 or more) decimates inside the generation and bakes the textures straight from the model's voxels: the best texture quality, but triangles.retopologize_mesh(orgenerate_mesh(retopo_faces=...)) rebuilds the topology of any GLB.method="quad"(default) gives an even all-quad mesh, suited to rigging and deformation.method="decimate"gives triangles that keep the silhouette closest.It then unwraps new UVs and bakes base color, roughness, metallic and a tangent space normal map from the original with Cycles on the CPU. Colour values are copied byte for byte (a test checks this).
Where the detail goes (
method="decimate"only):detail="auto"(default) keeps more faces where the surface bends sharply, such as fingers, joints and face features, and fewer on flat panels.detail="paint"reads the mesh's vertex colours as a map you paint in Blender: white for the most detail, black for the least. Export as GLB, which keeps vertex colours.detail="none"is uniform.detail_strength(0 to 1) scales the effect; 1 is the most that keeps the shape intact.The report gives the share of faces that landed in the detailed areas; on the test robot, the 16% of the surface marked detailed got 27% of the faces.
The quad remeshers have no per-area density, so quad output is uniform.
Thin parts far from the new surface can bake with dark specks; a higher
target_facesreduces them.glTF stores only triangles, so the GLB holds each quad as two triangles; the FBX written beside it keeps the quads and embeds the textures.
LOD chains:
lods=[10000, 3000, 800](orgenerate_mesh(retopo_lods=...)) writes LOD0, LOD1, LOD2 that share one UV layout and one texture set, so the engine loads one material.lods[0]replacestarget_faces: LOD0 is the retopology above, with its baked textures.Each further LOD is a collapse decimation of LOD0 itself (not of the LOD before it), to that many triangles. Blender's collapse interpolates the UVs on each side of a UV seam separately, so LOD0's layout and textures still fit.
One GLB and one FBX hold objects
<name>_LOD0,<name>_LOD1, ...; Unity's FBX importer builds a LOD Group from that suffix. The FBX keeps LOD0's quads; the lower LODs are triangles.The report lists each LOD's face and triangle counts and a
texture_fit, measured at each triangle's centre against the nearest point of LOD0:uv_drift_texels_median(a few texels when the layout is shared; a fresh unwrap measures about 100) andcolour_mismatch_share(triangles whose base colour differs from LOD0's there, which grows as small parts collapse). The p90 drift can be large on a correct LOD, because a centre near a seam can find its nearest LOD0 point on the other island.Detail weighting: with
method="decimate", the same detail map (detail,detail_strength) also steers the LOD decimations, carried from the original to LOD0's vertices. Without it, LODs made from a weighted LOD0 drift back toward uniform density (on the painted test mesh, 0.78 and 0.63 of the faces in the detailed half instead of 0.91 and 0.81). Withmethod="quad"the LODs are uniform, like LOD0.Limits: the lower LODs reuse LOD0's tangent space normal map, which fits less well as the shape simplifies. Strong reductions show it: on a test robot, a quad LOD0 of 18.8k triangles held up well down to 800 triangles, while a decimated LOD0 of 8k triangles taken to 600 grew spikes on thin parts (a direct 600 face decimation of the original has them too, though fewer). Quad LOD0s (the default) chain better.
Quad remeshing uses Instant Meshes (BSD) through pynanoinstantmeshes in the MCP venv. Blender's own Quadriflow is the fallback but rejects many generated meshes, so expect decimate results if that package is missing. Blender (4.2 or later, any build) must be installed; LOCALGEN_BLENDER points at a specific one.
Texturing
texture_mesh gives any mesh a PBR material, using native ComfyUI nodes and FLUX.2 Klein:
UVs:
UnwrapMeshmakes a fresh UV layout;keep_uvs=Truekeeps the mesh's own.Clay renders:
RenderMeshdraws grey clay views fromviewscameras around the mesh, framed to its bounding sphere and tilted 20 degrees.Painting: Klein paints each view image to image. It starts from the clay render's own latent with partial
denoise, which holds the painting to the geometry; from an empty latent it drifts back to a front view, and the back of the mesh gets a face.style_imageguides the front view.Projection:
BakeTextureFromViewsprojects the painted views into the UVs, each limited to its silhouette, and fills texels no view sees.BakeAmbientOcclusionadds AO.Blender (CPU): adds a tangent space normal map baked from a bump of the painted detail, a roughness map (rougher where the paint is darker) and metallic, then writes the GLB and an FBX.
Inputs are GLB, glTF, OBJ, STL, PLY or FBX. Each is re-exported through Blender, and only that fresh GLB is uploaded: like images, which must be real image files, a caller's file is never copied into ComfyUI's input folder as is. Uploads are deleted when the job finishes.
Limits: every view is painted separately, so the views can disagree on details. Parts seen only edge-on, or only from above, get filled or blended colour. It works best on clean meshes of a few thousand to 50k faces, such as retopologize_mesh output.
Separate parts and a rigid rig
generate_parts is for models that animate as hinged parts (robots, machines, armoured creatures).
Input: a front view concept image and, for each part, a name and a rough box (fractions of the image or pixels). The calling agent can read the boxes off the image. An optional parent and a few words of description can be given.
Isolation: each box is cropped, and FLUX.2 Klein redraws just that part as a complete standalone piece, with hidden areas filled in. Asking Klein to isolate or recolour a part of the whole image was unreliable (it moved, merged or missed parts), so the crop matters.
Meshing: TRELLIS.2 meshes each part (
face_count, default 20k).Placement: each part is placed by its box: scaled to fit it, with depth taken from a whole-object mesh made from the same concept, which is also given back as
full_mesh.Rig: one bone per part. The hierarchy follows the given parents, else which parts touch (a minimum spanning tree rooted at the largest part). Each bone pivots where its part meets its parent, and each part mesh is parented rigidly to its bone. The output is a GLB and an FBX with every part as its own object.
Resume: a failed run (for example the GPU running out of memory while another application holds VRAM) resumes when called again with the same
output_dir, reusing finished parts.
Tileable materials
generate_material makes surface materials for environment art (rock, hull plating, floors, organic growth).
Base color: Z-Image Turbo from the prompt, with "seamless top-down texture" wording added; FLUX.2 Klein when
reference_imageis given; or the caller'stile_image.Making it tile: image models do not tile. The graph (
workflows/seamless_material.py, native nodes only) offsets the image by half its size with wrap around, so the old edges meet in a cross through the middle and the new edges are continuous. It then repaints over that cross in two passes with Z-Image image to image, each with its mask as the latent noise mask (SetLatentNoiseMask), compositing only the masked part back:A cross shaped band (
seam_width, default 1/4 of the size across), fully repainted over the old edges and fading out towards its own edge, which noise makes ragged: a band with straight edges showed up as a grid once tiled. Its arms stop short of the image edges, because repainting up to an edge paints the two sides of that edge independently and breaks the wrap.What is left of the seam (short pieces where the arms stopped, two spots on the torus) is moved inside the image by a further quarter offset, repainted with a patch each, and moved back. No pass paints up to the edge of the frame it paints in, so the result wraps whatever the model draws (a test runs the graph with a stand-in that draws an image that does not tile).
seam_denoise(default 0.7) sets how freely the bands are repainted; higher hides a stubborn seam but drifts further from the surrounding texture.
Seam check: each wrap edge is compared with the opposite edge, and the repainted centre lines with their neighbours. A seam passes when its mean difference is no larger than the largest difference between neighbouring rows or columns inside the image (the result also gives its ratio to the mean and its percentile rank). If the centre still shows a line, the band is repainted again on the result (
seam_passes, default 2 in all), and the new pass is kept only if its centre line is weaker. The result reports every metric, for the untiled image too.Maps (Blender's numpy on the CPU, every filter wraps around, so the maps tile as well):
height (16 bit PNG): luminance, high pass (a blur of 1/8 the size removed), light blur. Brighter reads as higher;
invert_height=truefor the reverse.normal: tangent space from the height with wrap-around central differences,
normal_strength. OpenGL convention by default (green is +Y, as Unity and Blender expect):_normal_gl.png.directx_normal=truewrites DirectX -Y (Unreal):_normal_dx.png.roughness:
roughnessas the base, rougher in cavities and darker spots and smoother on raised, bright areas by up toroughness_variation.ambient occlusion: from the cavities of the height at three scales,
ao_strengthdeep at most.
Previews:
_tile3x3.png(the base color 3x3) and_preview.png, a Cycles render of a sphere (orpreview="plane") with every map under a low, raking light.Files go to
<output_dir>/<name>_<seed>/(default/ai/output/localgen/material/<date>/).
Limits: the maps are derived from the colour, so relief follows brightness, not real geometry: painted dark stains read as dents. The roughness is a heuristic, and there is no metallic map. The repaint can soften or change detail inside the band, which can show as a faint softer strip through the middle when tiled; look at the 3x3 preview. The seam metric is conservative for grids: on panel plating the wrap edge falls on a panel line, which can be the strongest transition in the image and then reads as not ok although it is not a seam.
Turnarounds
generate_turnaround makes the views a multi-view mesh needs from one concept image (or from a prompt, generating the concept first).
Clean front: FLUX.2 Klein first redraws the concept as a clean front view. Every prompt asks for flat even lighting, no cast shadows and a plain background, and names which way the object faces: the left view shows the object's own left side, facing image-left, as in Pixal3D's rig.
subjectnames the object and its parts; parts named there turn up in more views.guide="mesh", for flat, winged or wide objects: the other views are painted over renders of a guide mesh, so their pose comes from 3D, not from the image model's idea of the object.TRELLIS.2 meshes the clean front (50k faces, 1024 px textures;
generate_mesh's path). If that fails (a furry front can make TRELLIS.2 extract tens of millions of faces, whose remesh then runs out of GPU memory), it retries from the concept and says so inwarnings;guide_source="concept"starts from the concept. The concept must then show the object from the front.Blender renders the guide mesh from the rig's own cameras (
src/localgen_mcp/blender/render_rig_views.py, rig in_rig.py, shared withscripts/render_glb_views.py): colour onbackground, a uniform white world for flat light. One mesh and the rig's cameras mean one scale and the rig's framing in every view. TRELLIS.2 does not always turn a mesh's front to the rig's front (a test robot came out facing sideways, so the "front" render showed its side), so the mesh is first rendered small from the four axis aligned yaws, each compared with the image it was made from (silhouette aspect, overlap and colour, after cropping both to the silhouette), and the cameras turn by the best yaw (guide_yawin the result). Front and back cannot be told apart when TRELLIS.2 made the back a copy of the front, which then does not matter.Klein paints each view image to image from its own render (
guide_denoise, default 0.6), references [render, clean front, concept], with a prompt to keep the exact shape, silhouette and pose and only improve the surface to match the concept. The front is painted from its render too, so it is framed like the others; the clean front stays a reference. The painted views are used as rendered, with a BiRefNet mask as alpha.
Why: drawn from an empty latent, Klein redraws flat or winged objects facing the camera in every view. A Shade Moth (a spiky spore body, two wide fluffy wings, tendrils) came back with the wings spread flat in the side views, and Pixal3D built a four winged cross from them.
texture_meshhad the same drift and the same cure.guide_denoise: on the moth, 0.5 changed little beyond the render, 0.6 kept every silhouette and added surface detail, 0.75 began growing a wing patch back into the side view.The result adds
guide_mesh(a usable single view TRELLIS.2 mesh on its own),guide_renders,guide_source,clean_frontandstage_seconds.
guide="none"(default), for standing objects: Klein draws left, back and right (and withthree_quarter=Truethe four diagonals) from references [clean front, concept] from an empty latent, and the views are framed as below. It is faster (no TRELLIS.2 run or renders) and better on standing objects (below), but flat objects come out facing the camera.Framing (
guide="none"only): each view gets a BiRefNet mask and is scaled so its silhouette has the same height as in every other view, then all views are cropped by one square box around the union of their silhouettes. So every view has one scale, the object is centred, and the widest view spans 1/1.1 of the frame, as the rig wants. This assumes the object's height is the same from every side, which holds for a standing object seen level. The views are RGBA PNGs (alpha is the mask), plus a sheet of them side by side.Meshing:
mesh=Truefeeds the four main views togenerate_meshwithframing="as_framed"and the views' own alpha. Withguide="mesh"the result also carries the guide mesh.Limits: the views are drawn separately, so small asymmetric parts can drift between them. On the test robot, with a generic
subject, its one antenna came out doubled in the back view, or on the wrong side, depending on the seed; large parts (head, cargo cage, arms, treads) stayed consistent. Naming the part and its side insubject("exactly one antenna, behind the right side of its head (its own right)") gave one antenna, on the right side, in every view. Starting the back view from the mirrored front did not help (at denoise 0.7 the back kept the face).symmetric=Truemirrors the left-hand views into the right-hand ones, which keeps left and right consistent for symmetric objects only. Look at the views before meshing.Limits of
guide="mesh": the views can only be as right as the guide mesh, and TRELLIS.2 guesses the hidden back from one front view (the moth's back came out as a copy of its front). Klein at 0.6 keeps the shape but matches the concept's surface only loosely: on the 2026-10-11 Shade Moth the wings lost most of the violet and green speckle, and on the 2026-10-30 one the glowing wing edges came out faint. It takes 3 to 6 minutes instead of about 1.5, with two model swaps (Klein, TRELLIS.2, Klein).Tested (Shade Moth, 2026-11-15): with
guide="none"every view came back facing the camera with the wings spread, and Pixal3D built a four winged cross. Withguide="mesh"the side views show the wings edge-on and the body in profile, andmesh=Truegave a moth with two wings, thin from the side: bounding box 0.988 x 0.389 x 0.844 (TRELLIS.2 from the concept alone: 0.996 x 0.315 x 0.805). The later design (two wing pairs, two tail tendrils) gave 0.774 x 0.246 x 1.0.Tested (robot, 2026-11-15), why
nonestays the default: on a salvage robot with a camera head,guide="mesh"got the front and the side poses right (after the facing match), but its back view showed the camera face, because TRELLIS.2 had copied the front onto the guide mesh's back; its head was shallower in profile than the concept's, and the surface was softer.guide="none"on the same concept gave a real back (no face), a deeper head closer to the concept, and sharper detail. So the guide helps where the image model cannot turn the object (flat, winged, much wider than deep) and costs accuracy where it can.
Background removal
remove_background takes a list of images and returns one PNG per image, the subject opaque and the background transparent.
No options: each cut-out is the size of its input and lines up with it, ready for compositing.
trim=True: crops to the subject's bounding box, pluspaddingon every side as a fraction of the subject's longer side (default 0.05; 0 for a tight crop). The result reports the box found, in input pixels.square=True: centres the result on a square transparent canvas.size: scales the longer side to that many pixels (withsquare, size x size).background="#rrggbb": flattens onto a solid colour instead (RGB PNG).Typical calls: a UI icon is
trim=True, square=True, size=256; an item sprite istrim=True, padding=0.How: one ComfyUI prompt holds a chain per image, so BiRefNet loads once for the batch:
RemoveBackgroundgives the foreground mask, andJoinImageWithAlphagetsInvertMaskof it, because it inverts its alpha input (it expects LoadImage's 1 - alpha convention). With any option set, a second prompt without a model crops, pads, scales and flattens each cut-out using native nodes (ImageCrop,ImageCompositeMasked,ImageScalewith Lanczos). No native node returns a bounding box as numbers, so pass 1 also saves a 512 px copy of the mask and the server reads the box from it with the standard library, rounding outwards.Limits: the edge colour is the original pixel colour, so semi-transparent edges (hair, fur) keep a trace of the old background; a plain background that contrasts with the subject gives the cleanest result. Mask values under about 5% count as background when finding the box. Only the first frame of an animated GIF or WebP is used. BiRefNet's mask tops out just under 1, so the subject's alpha is 253 or 254 rather than 255. With layout options the job is two prompts, and on a busy shared backend each waits its turn in the queue.
Speech
speak turns one line of English into a WAV file for game dialogue. It does not use ComfyUI or the GPU, so it runs beside image and video jobs.
Model: Kokoro-82M v1.0 (Apache 2.0) on the CPU, in its own venv (
<root>/venvs/localgen-tts). The MCP server runssrc/localgen_mcp/tts/runner.pywith that venv's Python and reads its finalTTS_RESULT {json}line, the same pattern as the Blender scripts. The runner getsHF_HUB_OFFLINE=1and a CPU only PyTorch build.Time: about 5 s per line on 4 threads, most of it loading the model; each call starts a fresh process, so nothing stays in memory.
Voices: 20 American and 8 British English voices;
list_voicesgives Kokoro's quality grade for each (af_heartA,af_bellaA-,bf_emmaandaf_nicoleB-, the male voices C+ at best). A comma separated list of up to 4 voices with one accent is averaged into a new voice.Effects (ffmpeg filter graphs in
tts/effects.py;intensity0 to 1 scales each):radio: band limited to about 300 to 3200 Hz, compressed, light crushing and hiss.robotic: a constant phase spectrum (a flat, buzzing monotone) with a short metallic echo.glitch: for the low power lines. Stutters repeat the onset of some words (placed with the model's word timings), with dropouts, bursts of heavy bit crushing and light crushing throughout.seedreproduces a take.The effected take is brought back to the dry take's peak level, and the dry take is kept as
<name>_dry.wav.Without ffmpeg, the runner renders approximations with numpy and writes WAV only.
Output: 24 kHz mono 16 bit WAV and an OGG Vorbis copy, named by
name(for examplepathfinder_hull_40_lowpower). The result gives the duration, sample rate, RMS and peak level, and word timings (usable for subtitles).Limits: English only. Very short lines (a word or two) are weaker; Kokoro's model card suggests bundling them. No voice cloning; see docs/model-choices.md for why Chatterbox was not chosen. Levels and durations are checked automatically; only a listener can judge the voice itself.
Soft rigs for creatures
rig_creature rigs organic meshes for deformation driven in the engine (shaders, Verlet chains, springs); it makes no animation clips. Run it on a retopologize_mesh result: raw generated meshes are heavy and full of stray shells.
Presets.
chain:bones(default 8) along the main axis or a givenaxis, rooted atroot_end(default: the lower end of a vertical chain, else the thicker end). Joints are slice centroids, so the chain follows a gently curved mesh.spine: the same along a body.wings: the thin axis is the surface normal, and the left-right axis is the one the mesh is mirror symmetric across. A spine runs down the middle, andwing_chainschains ofwing_bonesbones fan out on each side to the wing edge.auto: picks from the proportions and reports why.
Names.
tentacle_01(or<name>_01),spine_01,wing_L1_01and the mirroredwing_R1_01, numbered from the root and, for wing chains, from the head. Every bone's local Y runs along it; rotating about local X bends it (for wings, towards the surface normal: a flap).Weights. Blender's heat weights first. They often fail on generated meshes: on the test manta, a spine rig left 100% of the vertices unweighted ("failed to find solution"). When more than 1% of the vertices are unweighted, or weighted mainly to a bone more than twice as far as their nearest, all weights are replaced by a smooth inverse distance falloff from the bone segments; a smaller share is patched. Vertices at the same position (split at UV seams) get the same weights, then each vertex keeps its 4 largest, normalised. The report gives the method, the heat failure shares, coverage and influences per vertex.
Output. A GLB and an FBX in the rest pose, and a report of every bone (head, tail, parent).
scripts/render_glb_views.py ... --pose 'wing_.*=12'renders a rig posed, framed like the rest pose, for before and after stills.Limits.
Joints come from straight slices, so a tentacle curled through more than about 90 degrees gets a chain that cuts the curve. Give it a straighter mesh or split it.
Distance weights are Euclidean, so parts that touch without being connected (a tentacle curled against the body) pull on each other.
On
wings, the body is a fixed strip (12% of the half span each side of the middle). Anything outside it, such as a manta's head lobes, moves with the nearest wing chain.
Upscaling
upscale_image runs a 4x super resolution model with ComfyUI's native UpscaleModelLoader and ImageUpscaleWithModel nodes.
Models:
realesrgan-x4plus(default) is a general upscaler that also cleans up mild noise and JPEG artefacts; it suits concept art, renders and photos.pbrify-v4is trained on game textures and keeps more fine surface detail, at about 3 times the run time. Both allow commercial use (BSD-3-Clause and CC0); see docs/model-choices.md.Scale: 4 is the models' native scale. 2 downscales the 4x result by half with Lanczos, so one model serves both scales.
Alpha: a PNG with transparency keeps it (
keep_alpha=falsedrops it). The model upscales the colour, and the alpha channel is resized bilinearly. Colour hidden under fully transparent pixels is upscaled too, so edges look as clean as the source's.Large images: the upscale node works in 512 px tiles (halved if the GPU runs out of memory), so VRAM is not the limit. The result is limited to 8192 px per side: 2048 px inputs at 4x, 4096 px at 2x. Output is an 8-bit PNG named
<input>_x<scale>.png.
Idle timeout
Default 300 s, bounded to 60 to 7200 s (
LOCALGEN_IDLE_TIMEOUT,LOCALGEN_IDLE_TIMEOUT_MIN,LOCALGEN_IDLE_TIMEOUT_MAX).The call that starts the backend sets the timeout. While it runs, a longer request extends it and a shorter one is ignored: the effective value is the maximum requested since it started, so one agent cannot cut short another's batch.
The effective value is in every tool result and in
status.Idle means an empty ComfyUI queue and no client activity for that long.
Related MCP server: ComfyUI MCP Server
Models
Chosen for a 12 GB card (an RTX 3080 Ti, with about 7.8 GB actually free beside a desktop session). Reasons, rejected candidates and sources are in docs/model-choices.md.
Use | Model | License | Download |
Text to image | Z-Image Turbo 6B bf16 | Apache 2.0 | 18.28 GB (with its text encoder and VAE) |
Image editing, reference images; painting views for | FLUX.2 Klein 4B fp8 | Apache 2.0 | 12.45 GB (includes the full Qwen3 4B text encoder) |
Video | Wan 2.2 TI2V 5B fp16 | Apache 2.0 | 18.15 GB |
Mesh from one image | TRELLIS.2 4B int8 | MIT | 8.96 GB |
Mesh from several views | Pixal3D multi-view int8 | MIT | 5.58 GB (shares the TRELLIS.2 files) |
Speech (optional, CPU) | Kokoro-82M v1.0, 28 English voices | Apache 2.0 | 0.34 GB, plus a 1.3 GB venv |
Upscaling, general | Real-ESRGAN x4plus | BSD-3-Clause | 67 MB |
Upscaling, game textures | 4x-PBRify UpscalerV4 (DAT2) | CC0-1.0 | 140 MB |
All of them use native ComfyUI nodes; no custom nodes are installed.
Measured on an RTX 3080 Ti (2026-11-15)
Measured through the MCP server over stdio, with all models in one backend session. Peak VRAM is the whole card: about 3.6 GB of it is the desktop and other applications. ComfyUI streams weights to fit, and no run hit an out of memory error.
Job | Settings | Time (execution, total) | Peak VRAM |
Image, cold start (process start + model load) | Z-Image Turbo 1024x1024, 8 steps | 66 s, 73 s | 11.5 GB |
Image burst, | same | 8.4, 7.6, 7.7, 7.6 s per image; 33 s total | 11.8 GB |
Image edit, one reference, first load | Klein 4B, 4 steps, 1024x1024 | 42 s | 11.7 GB |
Image edit, warm | same | 6 s | 11.5 GB |
Video, text to video | Wan 2.2 5B, 832x480, 49 frames (2.0 s at 24 fps), 20 steps | 85 s | 11.8 GB |
Video, defaults, cold start | Wan 2.2 5B, 1280x704, 49 frames, 20 steps | 168 s, 174 s | 11.8 GB |
Video, image to video, warm | same, 33 frames | 30 s | 11.8 GB |
Mesh, one image | TRELLIS.2, resolution 1024, 2048 px textures, 300k faces | 76 s (GLB 16.9 MB, 162k vertices) | 11.5 GB |
Mesh, four views | Pixal3D multi-view, same settings | 63 to 83 s (GLB about 17 MB) | 11.1 GB |
Mesh, three views from a turnaround sheet | Pixal3D multi-view, | 74 to 96 s | |
Turnaround, from a concept image | Klein 4B, 4 views at 1024 px, framing and sheet | 81 s execution (129 s with the model swap) | 11.7 GB |
Turnaround with three-quarter views, | 8 views, 5 of them sampled | 101 s execution | |
Turnaround, | clean front, TRELLIS.2 guide (50k faces), 3 or 4 Blender renders at 1024 px (4 threads), views painted | front 8 to 56 s, guide 38 to 166 s, renders 19 to 41 s, paint 89 to 114 s: 3 to 6 min (moths 3 min, robot 6 min) | |
Retopology | 300k faces to 10k quads, 2048 px textures | 10 to 13 s (CPU) | none |
Soft rig ( | 8k quad manta, | 2 s (CPU) | none |
Texture a mesh, warm | 4 views at 1024 px, 2048 px textures, 10k quad mesh | 34 s, plus 4 s in Blender | |
Speech, one 4 to 6 s line (measured with the load average near 10) | Kokoro-82M, 4 CPU threads, any effect | about 5 s in the runner (mostly model load); 6 to 10 s per call over MCP | none (CPU) |
Upscale 4x, | 1024x1024 to 4096x4096; 1536x1024 to 6144x4096 | 8.7 s; 12.1 s | |
Upscale, | 1024x1024, scale 2 (4x run, then Lanczos) | 25.0 s | |
Idle shutdown | default 300 s | ComfyUI gone at 301 s idle; VRAM back to 3.6 GB, RAM freed (about 18 GB) |
Times include the model swap when the previous job used a different model.
Mesh quality was checked by rendering each GLB from the four rig views in Blender (scripts/render_glb_views.py). The test was Pixal3D fed four renders of a TRELLIS.2 teapot. With framing="as_framed" it reproduced the original's proportions: a bounding box of 0.993 x 0.609 x 0.654 against 1.0 x 0.614 x 0.654, with one handle and one spout. With crop the same views produced a body as wide from the side as from the front.
Install or rebuild
Requirements: Linux, an NVIDIA GPU and driver, git and uv. uv provides Python 3.12. Blender is optional: only retopology needs it, and install.sh reports whether it was found. ffmpeg is optional too: speak uses it for effects and OGG output.
setup/install.sh --root /ai # ComfyUI, both venvs, directories, all model weights
setup/install.sh --root /ai --dry-run # show what would be done, change nothing
setup/install.sh --skip-models # software only
setup/download-models.sh --only video # weights for one group (image, video, mesh, upscale); --verify rechecks SHA256
setup/install.sh --root /ai --with-tts # also the text to speech venv (CPU) and the Kokoro weightsWhat gets pinned:
ComfyUI at commit
e08cc003(0.45.0).Both venvs from frozen lock files (
setup/comfyui-requirements.lock,setup/mcp-requirements.lock).Every weight file by Hugging Face revision and SHA256 (
setup/models.manifest). The upscale models exist only as GitHub release assets, so those entries name the release tag and are pinned by SHA256.With
--with-tts: the text to speech venv fromsetup/tts-requirements.lock(every package hashed, CPU only PyTorch) and the Kokoro files insetup/tts.manifest, into<root>/models/tts.
Everything large lives under the install root: weights, venvs, uv's cache and managed Pythons, logs, outputs and temp files. Nothing goes in /tmp or the home directory. The scripts are idempotent; rerun them after an interruption.
MCP client config
setup/register-mcp.sh prints the block below and keeps a copy in claude-mcp-config.json. It does not install it anywhere; add it to your MCP client's config yourself.
{
"mcpServers": {
"localgen": {
"command": "/ai/venvs/localgen-mcp/bin/python",
"args": ["-m", "localgen_mcp.server"],
"env": {
"LOCALGEN_ROOT": "/ai",
"LOCALGEN_IDLE_TIMEOUT": "300"
}
}
}
}How it works
agent A ── MCP server ─┐ ┌─ ComfyUI 127.0.0.1:8188 --offline
agent B ── MCP server ─┼─ flock start.lock ─ supervisor ───┤ (child process, killed when idle)
agent C ── MCP server ─┘ touch last_activity └─ reads idle_timeout every pollbackend.ensure_backend()takes an exclusive lock on<root>/run/localgen/start.lock. If ComfyUI answers, it is used. Otherwise a detached supervisor is started (its own session, logs in<root>/logs), and the caller waits for/system_stats. Concurrent cold calls therefore start exactly one backend.The supervisor holds
supervisor.lockfor its lifetime and runs ComfyUI as its child, which gets SIGTERM if the supervisor dies. It polls/queueand the mtime oflast_activity, which clients touch before and during every job.To shut down, the supervisor takes
start.lock(so no client can submit into a dying server) and rechecks for activity. It then terminates ComfyUI (SIGTERM, then SIGKILL after a grace period) and clears its run state.If a ComfyUI that localgen did not start is already on the port (for example one started by hand), it is used as is and never stopped.
Run state, all under <root>/run/localgen: start.lock, supervisor.lock, supervisor.pid, last_activity, idle_timeout.
Configuration
Variable | Default | |
|
| Install root |
|
| |
|
| Non-loopback hosts are rejected |
| 300 (60, 7200) s | |
| 180 s | Wait for ComfyUI to answer |
| 900, 5400, 3600 s | Per job |
| Extra ComfyUI flags, for example | |
| under the root | |
|
| Server logs go to stderr |
|
| For retopology |
| 8 | CPU threads for Blender's bake |
| 1800 s | |
|
| Text to speech venv |
|
| |
| 4 | CPU threads for synthesis |
| 600 s | |
|
| Effects and OGG output |
Adding a model
Add its files to
setup/models.manifest: group, target path, Hugging Face repo, pinned revision, path in the repo, size and SHA256 (all fromhttps://huggingface.co/api/models/<repo>/revision/<rev>?blobs=true).Add a module under
src/localgen_mcp/workflows/definingWORKFLOW = Workflow(...): modality, model files, defaults, limits, namedimage_slots, and abuild(params)function returning an API format graph. List it in_MODULES.ComfyUI's bundled templates are UI format;
python -m localgen_mcp.ui_to_apiconverts them headless, andscripts/make_trellis2_workflow.pyis a worked example.
Tools choose a workflow by modality and by which image slots the caller filled, so a new model is reachable through
model=without touching the server. A new modality also needs a tool inserver.py.
Development
uv venv --python 3.12 /ai/venvs/localgen-mcp
uv pip install --python /ai/venvs/localgen-mcp/bin/python -r setup/mcp-requirements.lock -e .
/ai/venvs/localgen-mcp/bin/python -m pytest # no GPU needed: the backend tests run against a fake ComfyUI
scripts/mcp_call.py --list # talk to the server over stdio like an MCP client would
PYTHONPATH=$PWD/src scripts/mcp_call.py --list # the server gets this environment, so this runs a checkout's code
scripts/mcp_call.py generate_image '{"prompt": "a red apple"}'
blender -b -P scripts/render_glb_views.py -- mesh.glb out/mesh 512 # front, left, back, right stills of a GLB
blender -b -P scripts/render_glb_views.py -- lods.glb out/lod2 512 0 1 robot_LOD2 # one object only, wireframe onThe backend tests launch the real supervisor against tests/fake_comfy/main.py, a stand-in that answers the same endpoints and records its command line. They cover:
the cold start, which must bind to localhost and run with
--offline;reuse of a running backend;
timeout extension and clamping;
idle shutdown on a custom timeout;
an extension from a second process being honoured;
a busy queue keeping the backend up;
four concurrent cold callers starting exactly one backend;
stop_backendguarding a busy queue;an unmanaged ComfyUI being left alone.
Credits
The server skeleton (FastMCP, stderr logging, signal handling) follows the layout of the author's other MCP servers. The ComfyUI client and the Z-Image Turbo graph are ported from a standalone Z-Image CLI written for the same install. Workflow graphs follow ComfyUI's own templates.
License
MIT, see LICENSE. Model weights are under their own licenses, listed above.
Available Tools
16 toolsgenerate_imageA
Generate images from a text prompt, optionally guided by reference images.
Without reference_images the default model is Z-Image Turbo (1024x1024, 8 steps). reference_images: up to 4 local image paths to edit or combine; the prompt says what to do with them (for example "change the jacket to red", "the person from image 1 in the setting of image 2"). This uses FLUX.2 Klein 4B; output size follows the first reference unless width and height are given. input_image: a local image to start from (image to image) instead of noise. The output keeps its size (width and height are not allowed); it is worked on at about 1 megapixel. The prompt describes the whole desired result, not only the change. denoise (0.05 to 1.0, needs input_image): how much may change. Z-Image Turbo default 0.6. Z-Image holds on to the input strongly: 0.3 and 0.6 change only fine detail, 0.9 keeps the layout but changes colours and materials, 1.0 ignores the input (except outside a mask). mask_image (needs input_image): a black and white image, white = change, black = keep; any size (it is stretched to input_image). Only the white area is regenerated, and the result is pasted back over input_image with an 8 pixel feathered edge, so every pixel more than about 18 px outside the white area is exactly the original. To replace what is in the region use denoise 1.0; to recolour an object, Klein (model="flux2-klein-4b") follows the prompt better than Z-Image at 0.9, which keeps some of the old colour. input_image with reference_images (or model="flux2-klein-4b"): FLUX.2 Klein edits input_image as image 1 and the references are images 2 to 4 (at most 3), for example "give the person in image 1 the hat from image 2"; Klein's denoise default is 1.0 (a full edit guided by image 1), and mask_image limits it to a region the same way. count > 1 queues all images at once (one model load); seeds are seed, seed+1, ... Returns absolute PNG paths, the seeds and settings used, timings and the effective backend idle timeout. Default output folder: /ai/output/localgen/image//. idle_timeout_seconds: keep the backend up this long after the last call (bounded, default 300).
Inputs: prompt (required), seed, count, model, +9 more.
generate_materialA
Make a tileable (seamless) PBR surface material for environment art: rock, rusted metal, floors.
prompt describes the surface only ("rough grey basalt rock with cracks"); "seamless top-down texture" wording is added. size 1024 (default) or 2048 (512 to 2048, a multiple of 64). reference_image: a picture whose colours and material to follow (FLUX.2 Klein). tile_image: make this existing image tileable instead of generating one (the prompt still guides the seam repaint). How it tiles: the image is offset by half its size with wrap around, then the cross where the old edges meet is repainted image to image under a soft, ragged mask (Z-Image Turbo) and only the masked part composited back; the arms stop short of the edges and the leftover spots are repainted after a further quarter offset, so no repaint ever crosses an edge and the result wraps exactly. seam_width (0.05 to 0.3 of the size, default 0.25) is how wide the band is; seam_denoise (0.3 to 1.0, default 0.7) how freely it is repainted: higher hides a stubborn seam but drifts from the surrounding texture. The wrap and the repainted centre are then measured; while the centre still shows a line, the repaint runs again (seam_passes in all, default 2; a rerun is kept only if it helps). Maps, derived from the base color in Blender on the CPU, all tiling: height (16 bit; luminance, high pass, light blur; brighter is higher, invert_height=True for the reverse), normal (tangent space, OpenGL +Y green up as Unity and Blender expect; directx_normal=True writes DirectX -Y for Unreal; normal_strength 0 to 10), roughness (roughness 0 to 1 is the base, 0.2 glossy, 0.8 matte; rougher in cavities and dark spots by up to roughness_variation), ambient occlusion from the height's cavities (ao_strength 0 to 1). Previews: a 3x3 tiling of the base color, and a lit Cycles render (preview "sphere", "plane" or "none") using every map. Look at both to judge seams and relief. Output: <output_dir or /ai/output/localgen/material/>/_/ with _basecolor.png, _height.png, _normal_gl.png (or _normal_dx.png), _roughness.png, _ao.png, _tile3x3.png, _preview.png. Returns the paths, seed, the normal convention, and seam metrics per map ("tiles" is true when every wrap edge is within the image's own neighbouring pixel differences). About 25 s on the GPU at 1024 when warm (longer at 2048, and again for each extra seam pass), plus 5 to 15 s in Blender on the CPU.
Inputs: prompt (required), name, seed, size, +14 more.
generate_meshA
Generate a textured 3D mesh (GLB with PBR materials) from an image of one object.
Give input_image (a local path), or give only prompt to first generate a reference image with the image model (a plain background suffix is added) and then mesh it. Default model: TRELLIS.2 with shape resolution 1024, 2048 px textures, 300k faces. Multi-view: also give left_image, back_image and/or right_image (views 90 degrees apart at the same scale, input_image being the front) to use Pixal3D multi-view instead. framing (multi-view only): "crop" (default) crops each view to its own outline, which suits figures; it stretches the side views of objects wider from the front than the side. "as_framed" uses square views exactly as given (object centred, about 1/1.1 of the frame at its widest, one scale for all views, as from a 3D render rig at 20 degrees horizontal FOV). remove_background=False uses the image's own alpha channel instead of BiRefNet. retopo_faces (for example 10000): also make a game weight copy with retopologize_mesh (retopo_method "quad" or "decimate"); the result's "retopo" entry has its path. retopo_lods (for example [10000, 3000, 800]) makes a LOD chain instead, as retopologize_mesh's lods. For a plain triangle mesh at a given size, face_count alone does it inside the generation. Returns the GLB path, the reference image path when one was generated, seed, settings and timings.
Inputs: seed, model, prompt, framing, +13 more.
generate_partsA
Build a model as separate part meshes from a front view concept, assembled and rigidly rigged.
parts: one entry per part, {"name": "left_arm", "box": [x0, y0, x1, y1], "parent": optional part name, "description": optional words to tell it apart}. The box is where that part is in concept_image, as fractions of the image (0 to 1) or pixels; look at the image and give a rough box around each part (overlaps are fine). subject names the object ("robot", "stingray"). Each part is cropped, cleaned into a standalone part by FLUX.2 Klein (hidden areas completed) and meshed by TRELLIS.2 with face_count faces. The parts are placed by their boxes, with depth from a whole-object mesh (generated from the concept unless full_mesh, a GLB of it, is given). rig=True adds an armature with one bone per part: the hierarchy follows the parents given, else which parts touch (rooted at the largest part), and each bone pivots where its part meets its parent. Parts are parented rigidly to their bones, the natural rig for robots and other hard surface models. If a run fails part way, call again with the same output_dir: finished parts are reused. Output: an assembled GLB and FBX (each part a separate object), plus every part's image and mesh. About 1 to 2 minutes per part on the GPU.
Inputs: parts (required), concept_image (required), rig, seed, +5 more.
generate_turnaroundA
Make consistent turnaround views of one object (front, left, back and right) from a concept image.
Give concept_image (a local PNG or JPEG of the object, any angle), or only prompt to generate the
concept first with the image model. subject: a few words naming the object and its key parts
("a salvage robot with a cargo cage on its back and tread feet"); it goes into every view's prompt
and defaults to prompt. Naming the parts helps them appear in every view.
FLUX.2 Klein first redraws the concept as a clean front view (flat even lighting, no cast shadows,
plain background). Views follow Pixal3D's rig: the left view shows the object's own left side,
facing image-left.
guide="none" (default, better for standing objects): each other view is drawn from the clean
front and the concept from an empty latent, then scaled by silhouette height (which assumes a
standing object seen level). Flat, winged or wide objects tend to come out facing the camera in
every view (a moth with its wings spread flat in the side views).
guide="mesh" (for flat, winged or wide objects): TRELLIS.2 meshes the clean front view (a guide
mesh; guide_source="concept" meshes the concept instead, and a failure from the front retries
from the concept), Blender renders it from the rig's cameras (turned by guide_yaw, found by
matching the mesh to that image, since TRELLIS.2 does not always face a mesh's front to the
rig's front), and Klein repaints each render image to image (guide_denoise, default 0.6, 0.3 to
0.95: lower keeps more of the render) with the clean front and the concept as references. The
renders fix each view's pose and silhouette, so a moth's wings are edge-on from the side, and
the views come out already framed for the rig. The views are only as right as TRELLIS.2's guess
at the hidden sides: on a robot it copied the face onto the back, which guide="none" got right.
three_quarter=True adds front_left, back_left, back_right and front_right views (for reference;
meshing uses the four main views). symmetric=True draws only the left-hand views and mirrors them
into the right-hand ones, which keeps a left-right symmetric object consistent (do not use it for
asymmetric objects).
Every view is square, the object centred at one scale, the widest view at 1/1.1 of the frame.
Views are RGBA PNGs (alpha is a BiRefNet foreground mask) on background; a sheet puts them
side by side.
mesh=True also meshes the four views with generate_mesh's multi-view path (framing "as_framed").
Views are generated, so they can still disagree on details: look at them before relying on them.
Returns the view paths by name, the sheet, the concept, the clean front, and with guide="mesh"
the guide mesh ("guide_mesh", a usable single view TRELLIS.2 mesh on its own) and its renders
("guide_renders"); with guide="none" the raw (unframed) views; the mesh result when asked.
About 6 s per view warm plus model loads; guide="mesh" adds a TRELLIS.2 run (about 1 to 2
minutes) and the Blender renders (about 10 s per view on the CPU).
Inputs: mesh, seed, guide, steps, +11 more.
generate_videoA
Generate a video from a text prompt, or animate input_image (a local image path) guided by the prompt.
Default model: Wan 2.2 TI2V 5B at 1280x704, 49 frames (about 2 s) at 24 fps, 20 steps, MP4 (H.264). frames must be 4n+1 (rounded down otherwise), up to 121 (5 s). Expect several minutes per clip on this GPU; longer clips and higher resolutions take proportionally longer. Returns the MP4 path, seed, settings, timings and the effective backend idle timeout.
Inputs: prompt (required), fps, seed, model, +8 more.
list_voicesA
Text to speech voices installed for speak(): name, accent, gender and Kokoro's quality grade (A best, F worst; higher grades had more and cleaner training audio), the effects available, and whether ffmpeg (for effects and OGG output) was found.
Inputs: no named parameters.
remove_backgroundA
Cut the subject out of one or more images: PNG cut-outs with a transparent background (BiRefNet).
images: 1 to 64 local image paths (PNG, JPEG, WebP, GIF, BMP or TIFF; the first frame of an animation). All are processed in one batch, so the model loads once; pass them together. With no other option each output is the same size as its input, the subject opaque and the background transparent, so it lines up with the original for compositing. trim=True crops to the subject's bounding box, plus padding on every side (a fraction of the subject's longer side, default 0.05; 0 is a tight crop). padding applies only with trim. square=True centres the result on a square transparent canvas (for icons and sprites). size: scale so the longer side is this many pixels (16 to 4096); with square, size x size. background: a colour like "#ffffff" to flatten onto instead of transparency (RGB PNG). Typical calls: UI icon trim=True, square=True, size=256; item sprite trim=True, padding=0; cut-out for compositing: no options. Returns per image the input, the output path, its size and the subject box found (x0, y0, x1, y1 in input pixels, with trim). A second, model free pass does the layout when any option is set. Default output folder: /ai/output/localgen/cutout//.
Inputs: images (required), size, trim, square, +4 more.
retopologize_meshA
Make a game weight copy of a textured GLB: new topology, new UVs, and baked PBR textures.
method "quad" (default): an all quad mesh with even edge flow (Instant Meshes), suited to rigging, deformation and further modelling. "decimate": triangles, closest silhouette. The new mesh gets a fresh UV layout, and base color, roughness, metallic and a tangent space normal map baked from the original (target_faces 200 to 500000, texture_size 256 to 8192). Where the faces go (method "decimate" only): detail "auto" (default) keeps more faces where the surface bends sharply (fingers, joints, face features) and fewer on flat panels; "paint" reads the mesh's vertex colours as a detail map you painted in Blender (white = most detail, black = least; export as GLB); "none" is uniform. detail_strength 0 to 1 sets how strongly (default 1, the most that keeps the shape intact). The quad method always uses one density everywhere. Runs in headless Blender on the CPU, about 10 to 30 s at 10k faces; the GPU is not used. Output: <output_dir or the input's folder>/retopo_.glb, plus an .fbx with embedded textures that keeps real quads (glTF stores only triangles). Returns the path, face and vertex counts before and after, the method that ran and timings. lods (for example [10000, 3000, 800]): a LOD chain for a game engine instead of one mesh. lods[0] replaces target_faces and is LOD0, the retopology above with its baked textures; each further entry is a triangle budget for a decimation of LOD0 that keeps LOD0's UVs, so every LOD uses the same textures and one material. Entries must be strictly decreasing (1 to 8 of them). Output: retopolods.glb and .fbx holding objects _LOD0, _LOD1, ... (Unity's FBX importer builds a LOD Group from that suffix). The report's "lods" lists each LOD's face and triangle counts and texture_fit: uv_drift_texels_median (how far its UVs sit from LOD0's at the same place; a few texels is right, hundreds means broken mapping) and colour_mismatch_share (share of its triangles whose base colour differs from LOD0's there; it grows as small features collapse). With method "decimate", the detail map also steers the LOD decimations.
Inputs: input_mesh (required), lods, detail, method, +4 more.
rig_creatureA
Soft rig for an organic creature (tentacles, tails, vines, rays, fish): bone chains with smooth skin weights, so engine scripts or physics (Verlet, springs) can bend it. No animation clips are made.
Call it on a clean mesh: run retopologize_mesh first (generated meshes are about 300k faces with
stray shells; a quad retopology of 5k to 20k faces skins and deforms far better). input_mesh: a GLB.
preset:
"chain": one chain of bones (default 8) along the mesh's main axis, or axis; for tentacles,
tails, vines. Bones are named _01.. from the root (name default "tentacle").
"spine": the same along the body, named spine_01.. (default 6 bones).
"wings": stingray, manta, bat or bird: a spine along the body length (bones, default 6) and,
on each side, wing_chains (default 3) chains of wing_bones (default 4) fanning from the body
to the wing edge. Named spine_01.., wing_L1_01.. and the mirrored wing_R1_01.. (L is the
positive side of the left-right axis: +X when that is X, the creature's left when it faces -Y as
generated meshes do; chain 1 is nearest the head).
"auto" (default): chain if long and thin, wings if flat and broad, else spine; the report says
which and why.
axis: "x", "y", "z" or [x, y, z]: the chain direction, or the body length for "wings"
(default: from the mesh's principal axes; for wings, the left-right axis is the one the mesh is
mirror symmetric across).
root_end: which end the chain (or the spine, at the head) starts from: "min" or "max" along the
axis, or a point [x, y, z] (the end nearest it). Default: a vertical chain starts at its lower end,
otherwise at the thicker end (a tentacle's base); wings start at the wider end (a tail is narrow).
weights: "auto" tries Blender's heat weights and falls back to a smooth distance falloff from the
bones when they fail (more than 1% of the vertices unweighted or on a far bone, common on generated
meshes); "distance" always uses the falloff. Every vertex gets at most 4 influences, normalised.
Bone axes: local Y runs along each bone; rotate about local X to bend (for wings, local Z is the
surface normal, so local X rotation flaps up and down).
Output: <output_dir or the input's folder>/rig.glb and .fbx (armature and skinned
mesh, rest pose). Returns the bones (head, tail, parent), the preset used, weight coverage and
method, and warnings. Headless Blender on the CPU, a few seconds.
Inputs: input_mesh (required), axis, name, bones, +6 more.
speakA
Speak a line of text (English) to a WAV file, with an optional game voice effect. Runs on the CPU.
Model: Kokoro-82M (Apache 2.0) in its own venv, offline; ComfyUI and the GPU are not used, so it never waits on image or video jobs. About 10 s to load plus about 1 s per sentence. voice: an installed voice name (see list_voices; default "af_heart"), or a comma separated blend of up to 4 voices with the same accent, averaged ("am_michael,bm_george" is invalid: two accents; "am_michael,am_fenrir" is fine). Prefix a = American, b = British; f = female, m = male. speed: 0.5 to 2.0 (1.0 normal). effect: "none"; "radio" (band limited, compressed, light hiss, like a comms channel); "robotic" (flat buzzing monotone with a metallic echo); "glitch" (a voice struggling on low power: stutters on word onsets, dropouts, bursts of bit crushing). intensity 0 to 1 (default 0.5) scales the effect. seed makes the glitch pattern and noise reproducible (returned in the result either way). name: file name stem for the line (for example "pathfinder_hull_40_lowpower"); an existing file with that name is overwritten. Default: . keep_dry: with an effect, also keep the unprocessed take as _dry.wav. Output: 24 kHz mono 16 bit WAV, plus an OGG Vorbis copy when ffmpeg is installed, in output_dir (default /ai/output/localgen/audio//). Returns the paths, duration, sample rate, RMS and peak level, word timings and the seed. Text up to 2000 characters; one call per line of dialogue.
Inputs: text (required), name, seed, speed, +5 more.
start_backendA
Start (or keep) the shared backend ahead of a batch.
idle_timeout_seconds: how long the backend stays up after the last activity. If this call starts the backend the value is used as is; if it is already running, a longer value extends it and a shorter one is ignored (the effective value is the maximum requested since it started). Bounded to the configured min and max (default 60 to 7200 s). Returns the effective value.
Inputs: idle_timeout_seconds.
statusA
Backend state: running or not, managed by localgen or not, effective idle timeout and bounds, queue length, GPU memory, and which workflows have their model files installed.
Inputs: no named parameters.
stop_backendA
Stop the shared backend now and free all GPU and system memory it holds.
Refuses while jobs are queued or running (possibly another agent's) unless force=True. An unmanaged ComfyUI (started by hand) is never stopped.
Inputs: force.
texture_meshA
Texture an existing mesh (GLB, glTF, OBJ, STL, PLY or FBX; untextured is fine) from a text prompt.
Builds everything a PBR material needs: a fresh UV layout (keep_uvs=True keeps the mesh's own),
a base color painted by FLUX.2 Klein on views clay renders around the mesh and projected into
the UVs (style_image: an optional picture whose colours and style the front view follows),
ambient occlusion, a normal map from a bump derived from the painted detail (bump 0 to 1, 0 for
none), and roughness (base value, rougher where the paint is darker) and metallic values.
denoise (0.6 to 1.0) is how freely views are painted: lower keeps more of the clay shading.
Best on clean meshes of a few thousand to 50k faces, for example from retopologize_mesh.
Outputs a GLB and an FBX with embedded textures, plus the painted views as PNGs. About 1 to 2
minutes on the GPU, then a few seconds in Blender on the CPU.
Inputs: prompt (required), input_mesh (required), bump, seed, +9 more.
upscale_imageA
Upscale an image (PNG or JPEG) 2x or 4x with a super resolution model, adding plausible detail.
model: "realesrgan-x4plus" (default; general purpose, suits concept art, renders and photos, and cleans up mild noise and JPEG artefacts) or "pbrify-v4" (made for game textures such as albedo, roughness or normal maps; keeps fine surface detail; about 3 times slower). scale: 4 (the models' native scale) or 2 (the 4x result downscaled by half with Lanczos). keep_alpha: a PNG with transparency keeps it; the alpha channel is upscaled smoothly, the colour by the model. keep_alpha=False writes an opaque RGB PNG. Large images are processed in tiles inside the backend, so any size fits in VRAM; the result is limited to 8192 px per side (for example 2048 px at 4x, 4096 px at 2x) and is an 8-bit PNG. Measured on this GPU: about 0.5 s per megapixel of 4x output with the default model and 1.5 s with pbrify-v4 (a 1024 px image takes about 9 s and 25 s), plus any wait for the shared queue. Output: <output_dir or /ai/output/localgen/upscale/>/_x.png. Returns the path, input and output sizes, whether alpha was kept, and timings.
Inputs: input_image (required), model, scale, keep_alpha, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have clearly distinct purposes (image, video, mesh, material, rig, retopo, TTS, upscale, background cut-out), and the long descriptions spell out when to use each. The main soft spots are in the 3D family: generate_mesh vs generate_parts vs generate_turnaround (with mesh=True) all end in a GLB, and generate_material vs texture_mesh both produce PBR textures, though the input types (prompt vs existing mesh) differentiate them.
Nearly all names follow a verb_noun pattern (generate_image, generate_video, remove_background, upscale_image, start_backend, stop_backend, list_voices). The outliers are the bare verb 'speak' and the noun 'status', which are readable but deviate from the pattern.
16 tools is on the higher side but justified by the breadth of the domain: image, video, 3D generation, 3D post-processing (retopo/rig/texture), audio, upscaling and backend lifecycle. Each tool maps to a distinct pipeline step, though the 3D group is dense enough that a slightly leaner surface (e.g. folding retopo into rig) might be easier to navigate.
Coverage is broad: generation for every modality, post-processing steps in a coherent chain (generate -> retopologize -> texture -> rig), plus backend start/stop/status and voice listing for TTS. Minor gaps remain: no job-list/cancel tool, no way to enumerate or clean up generated outputs, and no animation/clip tool for rigged meshes (explicitly out of scope, but a lifecycle dead end for some workflows).
Maintenance
Related MCP Connectors
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Generate 3D models, worlds, PBR materials, and coordinated asset packs from AI agents.
On-brand creative studio for AI agents: images, video, audio, and 3D.
Turn any LLM multimodal; generate images, voices, videos, 3D models, music, and more.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to generate and iteratively refine images, audio, and video by interacting with a local ComfyUI instance through natural conversation. It provides comprehensive tools for workflow management, node introspection, and publishing generated assets.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to generate and iteratively refine images, audio, and video through natural conversation using a local ComfyUI instance.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to generate and iteratively refine images, audio, and video through natural conversation using a local ComfyUI instance.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables local, provider-independent image generation and editing through named connections, multiple image protocols, and configured ComfyUI workflows, with saved outputs, job tracking, and explicit tool operations.4GPL 3.0