Skip to main content
Glama
Lightning Emperor MCP Server

Lightning Emperor MCP Server

by LucidMach

Lightning Emperor

Composite CG behind live-action actors, from your terminal, from Blender, or by asking an AI agent.

plate, matte, composite Left to right: a rendered green-screen plate (with real green bounce light), the automatic matte, and the composite over a CG room with a cast shadow and matched grain. Reproduce it with python examples/make_demo.py. No footage needed.

ci license python

Replacing a green or blue screen well is mostly measuring and matching, not clicking: the camera's lens and distance, where the light really comes from, how noisy the plate is, how far the actor is from the wall. Lightning Emperor turns those steps into tools, and ships the know-how as a skill so an AI agent can run the whole workflow and not just one step.

For

Python library + CLI

numpy only, ffmpeg for video I/O

scripts and pipelines

MCP server

13 tools, headless Blender jobs

Claude and any MCP client

Blender add-on

sidebar panel for camera, lights, practicals, renders, matte/grain/tracking

artists

Agent skill

the workflow and the lessons, as markdown

any LLM agent

What you get

  • Camera: distance from a known size in the plate, cross-checked against the lens focus distance, with a warning when they disagree. (A wrong distance makes the CG the wrong size in every frame; this is the mistake the tool exists to prevent.) Lens, exposure and white balance read straight from Blackmagic RAW files.

  • Keying: a difference key that calibrates itself to the screen, with brightness gating for dark clothing, hole filling that leaves hair gaps open, despill confined near the screen edge, edge decontamination and removal of tracking marks.

  • Tracking: finds tracking marks, tracks them with a homography per frame (learning the marker layout as it goes), smooths the result, exports corner pins.

  • Shadows: where an actor's shadow falls on the backdrop, from the light position and the actor-to-wall gap.

  • Grain: measures noise from the screen itself and synthesises matching grain. On the demo plate it recovers the true noise to within 3%.

  • Compositing: linear-light mix with shadow and grain, plus audio alignment of a trimmed export to the camera file.

Related MCP server: blender-render-mcp

Install

pip install "git+https://github.com/LucidMach/LightningEmperor"          # library + CLI (needs ffmpeg)
pip install "lightning-emperor[mcp] @ git+https://github.com/LucidMach/LightningEmperor"   # + MCP server

(A PyPI release is planned.) Blender add-on (4.2+): download lightning_emperor-<version>.zip from Releases, then Edit > Preferences > Get Extensions > Install from Disk. Agent skill: copy skill/lightning-emperor/ into your agent's skills folder. MCP client setup: docs/mcp.md.

Try it in two minutes

python examples/make_demo.py demo_out      # needs Blender + ffmpeg; renders, keys, measures grain, casts a shadow, composites
lightning-emperor distance --size-px 215 --focus-m 3.0
lightning-emperor key plate.mov out/ --frame 100 --screen green     # look at out/preview_on_grey.png
lightning-emperor comp plate.mov cg.png out.png --screen green --grain grain.json --shadow-offset 120,20

Or connect the MCP server and ask your agent: "Key frame 100 of plate.mov, tell me if the matte is good, then composite it over cg.png."

How well does it work? (honestly)

On the demo plate the grain measurement recovers the true noise (0.0110, 0.0092, 0.0141 measured vs 0.011, 0.009, 0.014 true) and its softness within 5%. Reproduce with examples/make_demo.py; numbers in docs/img/demo_numbers.json. It has also been used on real blue-cloth footage with tracking tape, where it removes the cloth cleanly and tracks the markers frame to frame. Known limits, so you do not find them the hard way:

  • Fine hair: a difference key loses strands thinner than a pixel (the demo's flyaway hairs mostly vanish). Hero shots need a dedicated hair matte.

  • Dark clothing lit by bounce from the screen can leave small grey patches near edges.

  • Over-exposed or near-clipped screens defeat the self-calibration (a pastel hot spot reads as foreground). Expose the screen properly.

  • Tracking needs markers in view. With none visible the backdrop can only be held or interpolated. There is no 3D camera solve.

  • Camera metadata is Blackmagic RAW only; other cameras need focal length and focus entered by hand.

  • Shadows are a 2D approximation, not ray-traced contact shadows.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[mcp,dev]" && pytest          # 19 tests on synthetic ground truth
python scripts/build_addon.py                   # vendors the core into the add-on and builds the extension zip (needs Blender)

Want to help? See docs/ROADMAP.md for contributor-sized tasks, and CONTRIBUTING.md. Built with the help of Claude Code.

Licence

GPL-3.0-or-later. See LICENSE. Blender add-ons that use its Python API must be GPL-compatible, so the whole project uses one licence.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables AI-powered control of Blender through natural language, allowing users to create, manipulate, and automate 3D scenes, objects, materials, animations, and more via Claude or other MCP clients.
      71
      67
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude Code and Codex to drive Blender through natural language: searching Sketchfab and importing ranked models with auto-recorded credits, auto-rigging characters and applying Mixamo animations, converting a single image to 3D, and splitting Cycles renders across a Mac (Metal) and Windows (OptiX) machine. A one-prompt installer sets up Blender, the MCP connection, and agent registration on macOS and Windows.
      2
      MIT