motion-previs-mcp

MCP (Model Context Protocol) stdio bridge for Motion Previs Studio — the open-source desktop app that turns real reference footage into AI-generator control packs. With this server connected, an AI agent can import a shot (local file or URL), trim the range, pick what to preserve (camera move, actor performance, object motion, or the full scene), run the analysis pipeline, watch its progress, export the bundle (depth passes, OpenPose skeleton video + keypoints, camera path, prompts), and send layers straight to the Blockout previs app.

Zero dependencies. Node ≥ 18. One file.

Requirements

1. Motion Previs Studio v4.1+ must be running. Get it from the app repo (build from source or use a release DMG).
2. On launch, the app starts a localhost-only control server on a random port and writes a discovery file to ~/.config/motion-previs/control.json (random bearer token, mode 0600, removed on quit). This bridge reads that file automatically — nothing to configure, no credentials to enter.

Connect

Hermes

Add to ~/.hermes/config.yaml (or install from the Hermes MCP catalog once listed):

mcp_servers:
  motion-previs:
    command: "node"
    args: ["/absolute/path/to/motion-previs-mcp/motion-previs-mcp.mjs"]

Claude Code

claude mcp add motion-previs -- node /absolute/path/to/motion-previs-mcp/motion-previs-mcp.mjs

Any MCP client (generic stdio config)

{ "mcpServers": { "motion-previs": { "command": "node", "args": ["/absolute/path/to/motion-previs-mcp/motion-previs-mcp.mjs"] } } }

Tools (11)

get_state · import_file · import_url · set_range · set_mode · set_settings · run_analysis · export_pack · list_bundle · send_to_blockout · screenshot

The agent workflow: import_file/import_url → set_range + set_mode (camera_only | actor_motion | object_motion | full_scene) → run_analysis → poll get_state until analysis.status is done → export_pack → optionally send_to_blockout (reference / depth / ai_depth / pose / openpose).

Security

The app's control server binds to 127.0.0.1 only, uses a per-launch random bearer token, and validates every action against a whitelist. Nothing is exposed off-machine.

License & credit

Apache-2.0 — see LICENSE. Per the NOTICE file, use, forks, and redistribution must credit Sam Wasserman (wassermanproductions.com).