Studio State

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: [email protected]