studio-state — MCP server for AI film & video production state

Keep AI-generated characters, locations, and shots consistent across an entire
project — by giving Claude (or any MCP client) a single source of truth for where
your production stands.

studio-state is a small, stateless Model Context Protocol
server for people producing AI-generated film, video, episodic shows, and animation
with tools like Higgsfield, Runway, Kling, Seedance, nano-banana, Veo, and ElevenLabs.
It reads your project's plain files on every call and answers three questions an AI
filmmaking assistant constantly needs to re-establish:

- orient — "Where am I right now?" Project, phase, active episode, budget/spend
posture, open blockers, next actions, and the scene index — one call instead of a
50-line copy-paste at the start of every session.
- get_shot_status — "What's the state of this scene?" Per-shot status
(planned / pending / fired / locked / needs-rework / dropped) reconciled from your
shot plan, your canonical lock state, and the server's own working notes.
- update_shot — "Mark this shot fired/locked and attach the generation job + still."

It's the free companion tool to The Studio Method —
a complete system for getting consistent characters and zero-retry continuity out of
generative video models.

---

Why this exists

AI generation tools drift. Across a long shoot they hallucinate characters, swap faces,
reinvent backgrounds, and contradict your references — and the human becomes the only
thing holding continuity together. Most of that pain is state pain: the assistant
helping you forgets where the production stands the moment a session resets.

studio-state fixes the state half structurally. Truth lives in your files, not in a
chat history or a server-side database. Every tool call re-reads the files, so it is
crash-proof and always current, and it never mutates your canonical files — the
only thing it writes is its own per-scene shot_status.json sidecar.

What makes it safe

- Read-dominant. 2 of 3 tools are pure reads. The one writer only ever touches a
shim-owned sidecar file — your shot plans, render manifests, and state file are never
modified.
- Stateless. No server-side store, no daemon state. Kill it mid-call and nothing
corrupts (atomic sidecar writes).
- Path-sandboxed. Scene/episode arguments are validated — no path traversal out of
your project tree.
- Hardened. Reviewed adversarially across multiple frontier models before release;
malformed files return structured errors instead of crashing the assistant.

Quick start

# 1. Python 3.9+ and the MCP SDK
python3 -m pip install "mcp[cli]"          # add --break-system-packages if needed
2. Try it against the bundled demo project (no setup)
python3 tests/test_acceptance.py           # expect: 4/4 checks passed
3. Point it at your own project (a folder containing _pipeline/STATE.json + episodes/)
export STUDIO_ROOT="/path/to/your_show"
python3 server.py

Then register it in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "studio-state": {
      "command": "python3",
      "args": ["/abs/path/studio-state-public/server.py"],
      "env": { "STUDIO_ROOT": "/abs/path/your_show" }
    }
  }
}

Full walkthrough: INSTALL.md.

Does my project work with this?

studio-state expects a lightweight, file-based project layout:

your_show/
  _pipeline/STATE.json                         # project phase, episode, budget, scenes
  episodes/episode_001/scenes/<SCENE>/
    phase_04_IRs.json                          # the shot plan (shot anchors + types)
    phase_05_render_manifest.json              # canonical lock/render state (optional)

A complete synthetic example ships in examples/demo_project/ —
copy its shape to adapt your own pipeline, or adopt the full convention via the paid pack
below.

The Studio Method (paid companion)

This tool tracks state. The hard part — getting the same character to render
consistently, shot after shot, with near-zero retries — is a method. The Studio
Method Starter Pack is the full system: the character/location/camera "bible" templates,
the pre-fire ritual, the prompt-assembly formula, and the anti-default doctrine that make
generative models hold continuity.

→ Get the Starter Pack: https://dkf2studios.gumroad.com/l/flplx
(Use code EARLY for the launch discount.)

Tools reference

| Tool | Type | Reads | Writes |
|---|---|---|---|
| orient | read | _pipeline/STATE.json | — |
| get_shot_status | read | scene IRs + render manifest + sidecar | — |
| update_shot | write | scene IRs (to validate) | shot_status.json sidecar only |

Keywords

AI filmmaking · AI video production · generative video pipeline · character consistency ·
continuity · shot tracking · render manifest · production state · Model Context Protocol ·
MCP server · Claude Desktop · Higgsfield · Runway · Kling · Seedance · nano-banana ·
ElevenLabs · AI short film · AI episodic show · previs · session orientation

License

MIT © 2026 DKF2 Studios. Contact: dkf2studios@gmail.com