IlluGen

IlluGen MCP

Let your AI agent build, edit and render JangaFX IlluGen node graphs.

Describe a texture, a VFX flipbook or a procedural mask in plain words: your agent creates the .illugen project, wires the nodes, checks it and renders it with your own IlluGen. No clicks, no window.

Quick start · What it can do · Tools · How it works · FAQ

Real tool calls and timings, real IlluGen renders. Reproduce them with examples/demo_scenes.py.

Quick start

1. Requirements

• Windows with IlluGen 1.2.x installed and activated (a valid JangaFX license: this project does not include or replace IlluGen).
• Python 3.10+. uv is recommended (no manual install needed).

2. Add it to your agent

Claude Desktop: one click

Download illugen-mcp-<version>.mcpb from the latest release and open it (or drag it into Claude Desktop › Settings › Extensions). Needs uv on your PATH. If IlluGen is installed elsewhere, set its path in the extension settings.

Claude Code

claude mcp add illugen -s user -- uvx --from git+https://github.com/dokaNc/illugen-mcp illugen-mcp

Claude Desktop, Cursor, Windsurf, VS Code, Gemini CLI… (any MCP client): add this to the client's MCP configuration (claude_desktop_config.json, .cursor/mcp.json, …):

{
  "mcpServers": {
    "illugen": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dokaNc/illugen-mcp", "illugen-mcp"]
    }
  }
}

Without uv (plain pip)

pip install git+https://github.com/dokaNc/illugen-mcp
claude mcp add illugen -s user -- illugen-mcp

or "command": "illugen-mcp" in the JSON configuration.

IlluGen installed somewhere else?

Set ILLUGEN_EXE to the full path of IlluGen.exe:

claude mcp add illugen -s user -e ILLUGEN_EXE="D:\Apps\IlluGen\IlluGen.exe" -- uvx --from git+https://github.com/dokaNc/illugen-mcp illugen-mcp

"env": { "ILLUGEN_EXE": "D:\\Apps\\IlluGen\\IlluGen.exe" }

3. Ask

Restart your agent, then try:

Check that IlluGen is reachable with illugen_status, then build me a tileable stone mask
and render it to C:\Users\me\Desktop\stone.

What it can do

• Build graphs from scratch: all 157 node types of IlluGen 1.2.1 (Grayscale, Color, UV, Geometry, Islands, Utils, signals, import/export…), with their real defaults, every legal enum value, ranges, units and descriptions.
• Wire them safely: pin types (Grayscale, Color, UV, Normal, Islands, GeometryBuffer…) are checked before IlluGen sees the file, and the error suggests a converter node when types don't match.
• Go beyond plain parameters: curves, color gradients, spline / lattice control points, subgraphs with exposed parameters, signal modulation (Oscillator → Scale…), framed groups and notes.
• Start from the shipped examples: copy any of IlluGen's 120+ example presets and modify it.
• Validate for real: project_validate(engine=true) loads the project in IlluGen, runs a trial export and reports dropped nodes or links, log errors and a screenshot of any warning dialog.
• Render: project_render runs File › Export on every export node (PNG, JPG, TGA, EXR, HDR, RAW, R16, R8, OBJ, FBX, flipbook sequences…), returns the produced files and an inline preview.
• Stay out of your way: rendering uses a private, invisible IlluGen instance. An IlluGen you have open keeps running untouched, and nothing steals your mouse or keyboard focus.

Tools

Typical flow: project_new → node_add … → link_add … → project_validate(engine=true) → project_render.

Showcase

Lava (Voronoi noise → levels → color ramp → glow), caustics (polygon fractal → caustics → ramp) and an energy web (Voronoi edges → ramp → glow): 4 to 5 nodes each, built and rendered by the agent in about 15 seconds. The exact graphs are in examples/demo_scenes.py.

Example prompts

Open the "brick_wall" preset, make it 2048x2048, make the bricks darker and render it.

Create a 64-frame looping smoke flipbook (8x8 atlas), export as TGA to D:\fx\smoke.

Build a subgraph "edge wear" (noise + levels + blur) with its seed exposed, use it twice with
different seeds and blend the results.

Explain what every node in C:\projects\lava.illugen does and suggest how to make it less noisy.

How it works

• Editing happens directly on the file. .illugen projects are read and written losslessly (a file saved without changes is byte-identical), so offline edits are instant and safe. Node definitions come from bundled tables matching IlluGen 1.2.1.
• Rendering uses IlluGen itself. The server starts a private copy of IlluGen in its own folder, hidden from the screen and the taskbar, loads the project and triggers IlluGen's own export shortcut. It follows progress through IlluGen's log and closes it when done. Your settings and open IlluGen windows are not touched.
• Errors come back to the agent. Failed exports and loading warnings are detected and returned with a screenshot, so the agent can fix the graph by itself.

Files written by the server: projects and renders where you ask, plus a scratch folder in %LOCALAPPDATA%\illugen-mcp (override with ILLUGEN_MCP_HOME).

Updating IlluGen

The bundled node tables target IlluGen 1.2.1. After an IlluGen update, rebuild the catalog from your installation (takes a few minutes, IlluGen runs invisibly):

uvx --from git+https://github.com/dokaNc/illugen-mcp python -m illugen_mcp.build_catalog

The new catalog is stored in %LOCALAPPDATA%\illugen-mcp\data and takes precedence over the bundled one.

FAQ

Does it work on macOS or Linux? Not yet: rendering drives the Windows build of IlluGen. Offline editing (project_*, node_*, link_*) is pure Python and should work elsewhere, but only Windows is tested.

Will it mess with the IlluGen I have open? No. Each render runs in its own private instance with its own configuration and recovery file.

IlluGen did not finish starting Start IlluGen once by hand (activate the license, close the welcome screen), check the path with illugen_status, and look at the latest log in %LOCALAPPDATA%\JangaFX\illugen\logs. If it persists, open an issue with that log.

A render says "Nodes failed to export". Usually a graph problem (pin type mismatch, disconnected input). The screenshot returned with the error shows the node in warning; describe_node_type lists the expected pin types.

I changed IlluGen's keyboard shortcuts. Supported: the server reads them from IlluGen's config.ini.

Development

git clone https://github.com/dokaNc/illugen-mcp
cd illugen-mcp
pip install -e ".[dev]"
pytest                      # tests needing IlluGen are skipped automatically if it isn't installed
ruff check .

Contributions are welcome: see CONTRIBUTING.md.

Disclaimer

IlluGen MCP is an independent community project. It is not affiliated with, endorsed by or supported by JangaFX. IlluGen and JangaFX are trademarks of their respective owner. You need your own licensed copy of IlluGen; this project neither includes nor modifies it.

License

MIT