# motion-previs-mcp

MCP (Model Context Protocol) stdio bridge for **[Motion Previs Studio](https://github.com/wassermanproductions/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](https://github.com/wassermanproductions/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](https://github.com/wassermanproductions/motion-previs-studio) (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):

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

### Claude Code

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

### Any MCP client (generic stdio config)

```json
{ "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](LICENSE). Per the [NOTICE](NOTICE) file, use, forks, and redistribution must credit **Sam Wasserman ([wassermanproductions.com](https://wassermanproductions.com))**.