localgen-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LOCALGEN_HOST | No | ComfyUI host. Non-loopback hosts are rejected. | 127.0.0.1 |
| LOCALGEN_PORT | No | ComfyUI port. | 8188 |
| LOCALGEN_ROOT | No | Install root for localgen-mcp. | /ai |
| LOCALGEN_FFMPEG | No | ffmpeg executable for speech effects and OGG output. | ffmpeg on PATH |
| LOCALGEN_BLENDER | No | Blender executable for retopology. | blender on PATH |
| LOCALGEN_LOG_DIR | No | Log directory. | under the root |
| LOCALGEN_RUN_DIR | No | Run-state directory. | under the root |
| LOCALGEN_COMFY_DIR | No | ComfyUI directory. | <root>/ComfyUI |
| LOCALGEN_COMFY_ARGS | No | Extra ComfyUI flags, for example --lowvram. | |
| LOCALGEN_OUTPUT_DIR | No | Output directory. | under the root |
| LOCALGEN_TTS_PYTHON | No | Text to speech venv Python executable. | <root>/venvs/localgen-tts/bin/python |
| LOCALGEN_TIMEOUT_TTS | No | Per-job timeout for text to speech jobs, in seconds. | 600 |
| LOCALGEN_TTS_THREADS | No | CPU threads for speech synthesis. | 4 |
| LOCALGEN_IDLE_TIMEOUT | No | Idle timeout in seconds, bounded to 60 to 7200 seconds. | 300 |
| LOCALGEN_MCP_LOG_FILE | No | Server log file. Server logs go to stderr. | |
| LOCALGEN_TIMEOUT_MESH | No | Per-job timeout for mesh jobs, in seconds. | 3600 |
| LOCALGEN_MCP_LOG_LEVEL | No | Server log level. Server logs go to stderr. | INFO |
| LOCALGEN_START_TIMEOUT | No | Wait for ComfyUI to answer, in seconds. | 180 |
| LOCALGEN_TIMEOUT_IMAGE | No | Per-job timeout for image jobs, in seconds. | 900 |
| LOCALGEN_TIMEOUT_VIDEO | No | Per-job timeout for video jobs, in seconds. | 5400 |
| LOCALGEN_TTS_MODEL_DIR | No | Text to speech model directory. | <root>/models/tts/kokoro-82m |
| LOCALGEN_TIMEOUT_RETOPO | No | Per-job timeout for retopology jobs, in seconds. | 1800 |
| LOCALGEN_BLENDER_THREADS | No | CPU threads for Blender's bake. | 8 |
| LOCALGEN_IDLE_TIMEOUT_MAX | No | Maximum idle timeout in seconds. | 7200 |
| LOCALGEN_IDLE_TIMEOUT_MIN | No | Minimum 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
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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 |
| 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 |
| 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 |
| 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
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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).