# Premiere Pro MCP for Claude Code

> Make Claude a real **operator** for Adobe Premiere Pro 2025 — not a chatbot that talks *about* Premiere, but an MCP server that actually opens projects, imports media, builds sequences, keyframes motion, color-grades, cuts footage to the beat, and renders **fully automatic cinematic intros** in four broadcast-grade styles.

A [Model Context Protocol](https://modelcontextprotocol.io) server (Node/TypeScript, stdio) with **59 tools**, packaged as a one-click `.mcpb` desktop extension. Built and verified live against **Premiere Pro 2025 (v25.5.0)** on Windows.

> ⚠️ Independent open-source project. Not affiliated with, endorsed by, or supported by Adobe. "Adobe" and "Premiere Pro" are trademarks of Adobe Inc.

---

## Why this exists

Premiere has **no official REST API, no usable CLI, and no local database** to drive it. The strongest automation surface is its **ExtendScript DOM**, reachable only from inside the app. So this project ships a tiny **CEP bridge panel** that runs a local HTTP server inside Premiere and forwards calls to ExtendScript — the same proven pattern used by tools like `pymiere`. On top of that sits a Node MCP server with file/registry access, process control, a UI-automation fallback, **and** a creative engine (Remotion-rendered visuals + synthesized sound design) for one-call cinematic intros.

```
Claude (Code / Desktop)
        │  MCP (stdio)
        ▼
  premiere-mcp  (Node/TypeScript server — this repo)
        │ HTTP 127.0.0.1:3030   │ file/registry        │ process + UI       │ Remotion + ffmpeg + numpy
        ▼                       ▼                       ▼                    ▼
  CEP Bridge Panel        recent/logs/prefs/        launch/quit/         cinematic intro visuals,
  (inside Premiere)       .prproj inspect           screenshot           SFX beds, beat detection
        │ CSInterface.evalScript
        ▼
  ExtendScript host ($._PPRO_MCP)  ──►  Premiere DOM + QE DOM
```

---

## Highlights

- 🎬 **One-call cinematic intros** — `premiere_create_brand_intro` renders a parameterized Remotion visual, synthesizes a timed sound-design bed, composites it in Premiere and exports **16:9 and 9:16** with audio.
- 🎨 **4 polished style presets** — `neural`, `stadium` (broadcast god-rays + lens-flare logo), `datagrid` (HUD control-room), `glass` (glassmorphism) — each with its own palette, color grade, logo treatment and sound design.
- ✂️ **Beat-cut short-video mode** — `premiere_beat_cut_video`: footage folder + music → detect beats → cut shots exactly on the beat → export.
- 🎛️ **Real timeline control** — silent sequence creation, trimmed clip placement, titles via Motion Graphics Templates (.mogrt) with dynamic text, audio, transitions, effects, **keyframes with Bézier easing**, overlays with blend modes.
- 🗂️ **Works even when Premiere is closed** — read recent projects, logs, preferences, inspect `.prproj` (gzipped XML), back up projects, list auto-saves.
- 🛡️ **Safe by design** — read-only by default, confirmation gates on destructive ops, dry-run, auto-backup before overwrite, write-allowlist, hard timeouts, audit log, secret redaction.
- 📦 **One-click install** — ships as a `.mcpb` bundle (server + bridge panel + assets).

---

## Requirements

- **Windows** + **Adobe Premiere Pro 2025** (host id `PPRO`, CEP 12).
- **Node.js 18+**.
- For the intro/cut features (optional): **ffmpeg**, **Python 3 + numpy**, and **Remotion** (installed in the bundled `remotion-intro/` project — `npm install` there). Chromium is fetched by Remotion on first render.
- Adobe Media Encoder is **not** required — exports use Premiere's built-in direct exporter.

---

## Install

### Option A — One-click `.mcpb` (recommended)

```powershell
npm install
npm run build
npm run build:mcpb        # -> build/premiere-mcp.mcpb
```

1. In **Claude Desktop**: *Settings → Extensions → "Install Extension"* → pick `build/premiere-mcp.mcpb`.
2. Ask Claude to run `premiere_install_bridge_panel` (sets the registry flag + copies the panel — no admin).
3. **Restart Premiere**, open **Window → Extensions → Premiere MCP Bridge**.
4. Verify: ask Claude to run `premiere_status`.

### Option B — Manual (dev)

```powershell
npm install
npm run build
npm run install-extension   # installs the CEP bridge panel + sets PlayerDebugMode
```

Add to your Claude config (`claude-config-example.json` has a template):

```jsonc
{
  "mcpServers": {
    "premiere": {
      "command": "node",
      "args": ["C:\\path\\to\\Premiere-MCP\\dist\\index.js"],
      "env": { "PREMIERE_MCP_BRIDGE_PORT": "3030" }
    }
  }
}
```

- **Claude Desktop:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Code (CLI):** `claude mcp add premiere -- node "C:\path\to\Premiere-MCP\dist\index.js"`

Full step-by-step in [INSTALL.md](INSTALL.md).

---

## Tool catalog (59)

<details>
<summary><b>Setup &amp; lifecycle</b></summary>

`premiere_bridge_panel_status` · `premiere_install_bridge_panel` · `premiere_status` · `premiere_launch` · `premiere_quit` · `premiere_restart`
</details>

<details>
<summary><b>Projects</b></summary>

`premiere_get_app_info` · `premiere_get_project_info` · `premiere_get_preferences` · `premiere_open_project` · `premiere_new_project` · `premiere_save_project` · `premiere_save_project_as` · `premiere_close_project`
</details>

<details>
<summary><b>Media &amp; bins</b></summary>

`premiere_import_files` · `premiere_create_bin` · `premiere_list_project_items` · `premiere_find_project_item` · `premiere_remove_project_item`
</details>

<details>
<summary><b>Sequences &amp; timeline</b></summary>

`premiere_list_sequence_presets` · `premiere_list_sequences` · `premiere_get_active_sequence` · `premiere_create_sequence` · `premiere_new_sequence` (silent) · `premiere_set_active_sequence` · `premiere_get_sequence_tracks` · `premiere_add_marker` · `premiere_list_markers`
</details>

<details>
<summary><b>Auto-edit primitives</b></summary>

`premiere_place_clip` · `premiere_add_title` (MOGRT + dynamic text) · `premiere_add_audio` · `premiere_add_transition` · `premiere_add_effect` · `premiere_keyframe` (Bézier) · `premiere_add_overlay` (blend modes) · `premiere_apply_lumetri`
</details>

<details>
<summary><b>High-level creative</b></summary>

`premiere_build_video` (assemble from a JSON edit-spec) · `premiere_create_intro` · `premiere_create_brand_intro` (the flagship) · `premiere_detect_beats` · `premiere_add_beat_markers` · `premiere_beat_cut_video`
</details>

<details>
<summary><b>Export</b></summary>

`premiere_list_export_presets` · `premiere_export_sequence` (direct, no AME)
</details>

<details>
<summary><b>Files / registry (offline)</b></summary>

`premiere_list_recent_projects` · `premiere_get_logs` · `premiere_get_preference_files` · `premiere_inspect_project_file` · `premiere_backup_project` · `premiere_list_autosaves`
</details>

<details>
<summary><b>UI fallback &amp; advanced</b></summary>

`premiere_screenshot` · `premiere_focus_window` · `premiere_ui_describe` · `premiere_send_shortcut` · `premiere_get_capabilities` · `premiere_run_extendscript` (guarded) · `premiere_run_menu_command` · `premiere_generate_report` · `premiere_bridge_selftest`
</details>

---

## The creative engine

> **Premiere is the compositor/exporter; the heavy animation lives in the render layer (Remotion).** This is the reliable path to broadcast-grade quality — speed curves, glow, grading and kinetic type are deterministic in Remotion, while Premiere does compositing, sound and export.

### Cinematic intro — one call

```jsonc
premiere_create_brand_intro {
  "title": "M.P",
  "subtitle": "AI · AUTOMATION · VIDEO",
  "style": "stadium",        // neural | stadium | datagrid | glass
  "aspect": "both",          // 16:9 and 9:16
  "logoPath": "C:\\…\\logo.png",   // optional; defaults to the bundled brand logo
  "musicPath": "C:\\…\\track.wav", // optional; a synthesized SFX bed is added either way
  "outputDir": "C:\\…\\out"
}
```

Each `style` brings its own palette, **color grade** (`grade`: `neon` / `teal-orange` / `mono`, with `gradeStrength`), **title treatment** (`titleStyle`: `stack` / `spread` / `minimal`), **logo treatment** (stadium lens-flare, datagrid HUD frame, glass card) and **sound-design bed** (stadium crowd-whoosh + big impact, datagrid UI-bleeps + riser, glass chime + shimmer). Every parameter is overridable.

### Build any video from an edit-spec

```jsonc
premiere_build_video {
  "sequence": { "name": "My Short", "presetPath": "…/HD 1080p 25 fps.sqpreset" },
  "video":  [ { "path": "a.mp4", "track": 1, "at": 0, "in": 2, "out": 5 } ],
  "titles": [ { "text": "Hello", "track": 2, "at": 0.5, "duration": 3 } ],
  "audio":  [ { "path": "music.wav", "track": 2, "at": 0 } ],
  "transitions": [ { "name": "Cross Dissolve", "videoTrack": 1, "clipIndex": 0 } ],
  "export": { "outputPath": "C:\\…\\short.mp4", "confirm": true }
}
```

### Beat-cut a reel

```jsonc
premiere_beat_cut_video {
  "footageDir": "C:\\…\\footage",
  "musicPath": "C:\\…\\track.mp3",
  "beatsPerCut": 2,          // 1 = cut on every beat
  "order": "shuffle",
  "aspect": "16:9",
  "outputPath": "C:\\…\\reel.mp4"
}
```

Times are **seconds**, tracks are **1-based** (V1/A1 lowest), all paths **absolute**.

---

## Configuration (environment variables)

| Variable | Default | Purpose |
|---|---|---|
| `PREMIERE_MCP_BRIDGE_PORT` | `3030` | Port of the in-Premiere bridge panel |
| `PREMIERE_MCP_BRIDGE_HOST` | `127.0.0.1` | Bridge host (keep localhost) |
| `PREMIERE_MCP_ALLOWED_ROOTS` | Documents;Videos;Desktop;Downloads | Write/delete allowlist (`;`-separated) |
| `PREMIERE_MCP_EXE` | the 2025 path | Premiere executable |
| `PREMIERE_MCP_VERSION_FAMILY` | `25.0` | Prefs/registry version folder |
| `PREMIERE_MCP_REMOTION_DIR` | `./remotion-intro` | Remotion intro renderer project (must be in a path **without `!`** — webpack limitation) |
| `PREMIERE_MCP_OUTPUT_DIR` | `~/Videos/premiere-mcp` | Default output folder for rendered files |
| `PREMIERE_MCP_LOG_DIR` | `%APPDATA%\premiere-mcp\logs` | Server audit log location |

---

## Safety model

- **Read-only by default** — all `get/list/inspect/find/report` tools are non-destructive.
- **Confirmation gates** — destructive actions require `confirm: true` (quit/restart, close-without-save, overwrite a project/export output, delete a bin, raw ExtendScript, QE menu command).
- **Dry-run** — `premiere_run_extendscript` defaults to `dryRun: true`.
- **Auto-backup** — overwriting a `.prproj` writes a timestamped `.bak-…` first.
- **Write allowlist** — writes/deletes are confined to configured roots.
- **Hard timeouts** — a modal Premiere dialog can freeze ExtendScript; every bridge call times out with an actionable message instead of hanging.
- **Audit log + secret redaction** — every tool call is logged (stderr + file); tokens/passwords are redacted. stdout is reserved for the MCP protocol.

---

## Capability matrix (what's reliable vs render-layer)

| Area | Status | Notes |
|---|---|---|
| Status / launch / quit / restart | ✅ Full | process + bridge |
| Open / new / save / save-as / close project | ✅ Full | overwrite gated + auto-backup |
| Import media, bins, list/find items | ✅ Full | |
| Create sequence (silent) | ✅ Full | `app.project.newSequence` + `.sqpreset` |
| Create sequence (custom settings) | ⚠️ Dialog | Premiere 2025 opens its New Sequence dialog on scripted `createNewSequence` |
| Place clip / trim / multi-track | ✅ Full | |
| Title (MOGRT) + dynamic text | ✅ Full | sets the source-text param |
| Audio / music | ✅ Full | |
| **Keyframes (scale/opacity/rotation/position, Bézier)** | ✅ Full | verified live |
| Transitions / effects by name | ⚠️ QE | works on 25.5; QE DOM is unsupported by Adobe |
| Lumetri / LUT | ⚠️ Best-effort | param/LUT scripting is fragile → bake the grade into Remotion |
| Speed ramps / adjustment layers | ❌ Render-layer | not reliably scriptable in Premiere → do in Remotion |
| Direct export (no AME) | ✅ Full | `exportAsMediaDirect`, blocking |
| Beat detection / beat-cut | ✅ Full | ffmpeg + numpy onset detection |
| Cinematic intros (4 styles) | ✅ Full | Remotion visual + sound + composite + dual export |
| Recent projects / logs / prefs / `.prproj` inspect / backups | ✅ Full | works with Premiere closed |
| Screenshot / focus / keystrokes | ✅ Fallback | UI automation |

---

## Project structure

```
Premiere-MCP/
├── src/                      MCP server (TypeScript)
│   ├── index.ts              entry: registers all tools over stdio
│   ├── config.ts             paths/ports/allowlist (env-overridable)
│   ├── bridge.ts             HTTP client to the in-app panel
│   ├── safety.ts             allowlist, confirm/dry-run, backups
│   ├── exec.ts logger.ts     PowerShell exec + stderr/file logging
│   └── tools/                the 59 tools, grouped by domain
├── bridge-extension/com.mp.premiere.mcp/   the CEP panel (installed into Premiere)
│   ├── CSXS/manifest.xml     CEP 12 manifest (PPRO 25, Node enabled)
│   ├── client/               panel UI + Node HTTP server + CSInterface
│   └── host/index.jsx        ES3 ExtendScript host ($._PPRO_MCP) + JSON serializer
├── remotion-intro/           parameterized cinematic intro renderer (Remotion)
│   └── src/                  BrandIntro, styles (4 presets), overlay loops
├── assets/
│   ├── sfx/generate_sfx.py   synthesized sound-design kit + per-style beds
│   ├── audio/detect_beats.py beat/onset detector (ffmpeg + numpy)
│   └── overlays/             light-leak / grain loops
├── scripts/                  install / uninstall / build-mcpb (PowerShell)
├── mcpb/manifest.json        Desktop Extension manifest
└── test/                     mock bridge + stdio integration test
```

Run the offline tests any time (no Premiere needed): `npm run build && npm run test:server`.

---

## Building the `.mcpb`

```powershell
npm run build:mcpb     # bundles server + deps + bridge panel + assets -> build/premiere-mcp.mcpb
```

The packer writes ZIP entries with forward slashes (Windows `Compress-Archive` uses backslashes, which breaks the loader).

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `premiere_status` says bridge not connected | Open **Window → Extensions → Premiere MCP Bridge** (green dot) |
| Panel not in the Extensions menu | Re-run `premiere_install_bridge_panel` / `npm run install-extension`, fully **restart** Premiere |
| A tool times out | Premiere is likely showing a modal dialog — run `premiere_screenshot` to see it |
| Export "Unknown error" | The `.epr` preset path is wrong/empty, or the output extension doesn't match the preset format |
| Remotion render fails with a webpack "!" error | The Remotion project path contains `!` — move it to a path without `!` and set `PREMIERE_MCP_REMOTION_DIR` |
| `EvalScript error` | Host JSX failed — reopen the panel; check `%TEMP%` CEP logs |

---

## Acknowledgements

- The CEP bridge pattern follows the lineage of [`pymiere`](https://github.com/qmasingarbe/pymiere) and the Adobe-CEP samples.
- Built with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and [Remotion](https://www.remotion.dev/).

## License

[MIT](LICENSE) © Maurice Putinas