Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
LOCALGEN_HOSTNoComfyUI host. Non-loopback hosts are rejected.127.0.0.1
LOCALGEN_PORTNoComfyUI port.8188
LOCALGEN_ROOTNoInstall root for localgen-mcp./ai
LOCALGEN_FFMPEGNoffmpeg executable for speech effects and OGG output.ffmpeg on PATH
LOCALGEN_BLENDERNoBlender executable for retopology.blender on PATH
LOCALGEN_LOG_DIRNoLog directory.under the root
LOCALGEN_RUN_DIRNoRun-state directory.under the root
LOCALGEN_COMFY_DIRNoComfyUI directory.<root>/ComfyUI
LOCALGEN_COMFY_ARGSNoExtra ComfyUI flags, for example --lowvram.
LOCALGEN_OUTPUT_DIRNoOutput directory.under the root
LOCALGEN_TTS_PYTHONNoText to speech venv Python executable.<root>/venvs/localgen-tts/bin/python
LOCALGEN_TIMEOUT_TTSNoPer-job timeout for text to speech jobs, in seconds.600
LOCALGEN_TTS_THREADSNoCPU threads for speech synthesis.4
LOCALGEN_IDLE_TIMEOUTNoIdle timeout in seconds, bounded to 60 to 7200 seconds.300
LOCALGEN_MCP_LOG_FILENoServer log file. Server logs go to stderr.
LOCALGEN_TIMEOUT_MESHNoPer-job timeout for mesh jobs, in seconds.3600
LOCALGEN_MCP_LOG_LEVELNoServer log level. Server logs go to stderr.INFO
LOCALGEN_START_TIMEOUTNoWait for ComfyUI to answer, in seconds.180
LOCALGEN_TIMEOUT_IMAGENoPer-job timeout for image jobs, in seconds.900
LOCALGEN_TIMEOUT_VIDEONoPer-job timeout for video jobs, in seconds.5400
LOCALGEN_TTS_MODEL_DIRNoText to speech model directory.<root>/models/tts/kokoro-82m
LOCALGEN_TIMEOUT_RETOPONoPer-job timeout for retopology jobs, in seconds.1800
LOCALGEN_BLENDER_THREADSNoCPU threads for Blender's bake.8
LOCALGEN_IDLE_TIMEOUT_MAXNoMaximum idle timeout in seconds.7200
LOCALGEN_IDLE_TIMEOUT_MINNoMinimum idle timeout in seconds.60

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Local, offline image, video and 3D mesh generation on this machine's GPU. Tools return file paths (open them to view). The shared backend starts on the first call (about 10 s, plus model load) and stops itself after an idle timeout (default 300 s). Pass idle_timeout_seconds, or call start_backend first, when planning a long batch; call stop_backend when done to free GPU memory. Only one large model fits in VRAM at a time; switching modality reloads models. speak (text to speech) runs on the CPU without the backend; list_voices shows its voices.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

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

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4/5.0

Scored across 16 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo recent community issues