Premiere Pro Full MCP (v2.0)

Local-first MCP server for Adobe Premiere Pro. Rebuilt from scratch to be a safe, local-only tool.

Highlights

• No external account or API token. CEP is loopback-local and UXP uses a machine-local HMAC key. There is no remote auth, approval envelope, actionId, plan-hash, or preview/confirm lifecycle.

• One persistent dual-track connection. The Node server opens a loopback WebSocket to the CEP extension (the classic ExtendScript host) AND a HMAC-authenticated UXP bridge. Tools that Premiere 26.x only exposes through UXP (export_frame / capture_frame via Exporter, the SequenceEditor transaction actions, clip move/remove/trim, effect add/remove, video transitions, track mute) automatically route over the UXP track; everything else runs over CEP/ExtendScript. No file polling, no leader lease.

• 354 flat tools (266 official adobe-premiere-pro-mcp v1.2.0 names + 87 project-specific extras + premiere_capabilities). Every tool is its own MCP tool named premiere_<snake_case_tool>. No actionId anywhere.

• UXP-only operations actually work. The previously-missing capabilities — frame capture, video transition add, clip effect add/remove, clip move/remove/trim, track mute — are implemented on the UXP panel bridge. The server reports uxpConnected, uxpOperations, and uxpCatalogCounts so an agent can see which track is live before mutating.

• Frame capture is fixed. Premiere 26.x CEP has no exportFramePNG; the export_frame / capture_frame tools now use the UXP Exporter path, so they produce a real, distinct frame at the requested playhead position.

• Host failures fail closed. Request timeouts are carried end to end, CEP disconnect/replacement settles pending work immediately, and timed-out mutations are recorded as UNKNOWN rather than treated as safe retries. The daemon serializes CEP work, holds one mutation lease across mixed CEP/UXP subrequests, and quarantines later mutations until recovery is explicitly acknowledged against the observed project fingerprint. When the coordinator is enabled, untagged CEP/UXP mutation requests are rejected.

• Large raw scripts are bounded. premiere_execute_extendscript accepts a real timeout up to 120 seconds, but is limited to 16 KiB and one risky operation class. Placement, keyframe, and project-save APIs cannot be mixed in one raw script; use their dedicated MCP tools as separate stages.

Related MCP server: MCP Bridge for Adobe Premiere Pro

Layout

src/                  TypeScript MCP server (thin)
  index.ts            stdio entry; connects to the always-on bridge daemon
  server.ts           registers 354 flat MCP tools routed over one persistent bridge
  daemon.ts           always-on bridge daemon entry (auto-starts at logon)
  auto-start.ts       daemon auto-start wiring
  bridge/ws-host.ts   WS server + endpoint files (%LOCALAPPDATA%\PremiereMCP)
  bridge/ws-client.ts loopback WS client used by MCP servers
  bridge/uxp-host.ts  UXP bridge (HMAC /uxp WebSocket) for UXP-only operations
  bridge-types.ts     wire contract ({ kind, requestId, script } -> response)
  operations/         daemon ledger, tool policy, queues, recovery coordinator
  tool-names.ts       266 official + 87 extra tool names (single source of truth)
vendor/upstream/      official adobe-premiere-pro-mcp v1.2.0 handlers (validated)
cep-plugin/           Adobe CEP extension (Premiere side, fallback track)
  main.ws.js          CEF client: reads endpoint, connects WS, evalScript to host
  CSInterface.js      CEP bridge shim
  index.html          minimal panel bootstrap
  CSXS/manifest.xml   extension manifest
uxp-plugin/           Adobe UXP plugin (Premiere side, primary edit/export track)
  manifest.json       UXP manifest (id com.codex.premiere-pro-full-mcp, v2.0.0)
  main.cjs            WebSocket client + UXP-only ops
  main.js             panel bootstrap; auto-connects on create/show
  auth.cjs            HMAC handshake helpers (shared with daemon)
  api-catalog.cjs     generated Adobe UXP member allowlist (761 members)
  icons/icon.svg      panel icon
scripts/
  smoke.mjs           assert >= 354 tools are advertised
  _e2e-bridge.mjs     daemon<->CEP wire-path exercise (mock host)
  _live-probe.mjs     ping the running daemon's CEP host and UXP bridge
  _syntax-check.mjs   wrapped-script parse audit (no top-level return leak)
  build-ccx.mjs       package uxp-plugin/ into a .ccx (ZIP with manifest at root)
  install-daemon.ps1  register always-on daemon (Task Scheduler, logon)
  install-cep.ps1     deploy the CEP extension into Premiere's CEP folder
  install-uxp.ps1     deploy the UXP plugin into Premiere's UXP folder (no dev tool)
tests/                vitest: tool surface, server, bridge contract

Build & verify

npm run build        # tsc (src -> dist)
npm run typecheck
npm test             # vitest (tool count, server 353+, bridge round-trip)
npm run check        # typecheck + test + build + smoke + e2e + syntax
node scripts/smoke.mjs   # assert >= 354 tools advertise
npm run verify:release   # version/manifest coherence before staging a release

Release staging

Do not reuse an old ZIP or tarball after changing the CEP bridge. Stage a new release only after the source checks pass, then verify every archive against the current source before publishing:

node scripts/build-release.mjs --out .release-staging
node scripts/verify-release.mjs .release-staging\premiere-pro-full-mcp-2.0.0.tgz

The staging command refuses a non-empty output directory and a dirty worktree. It runs the acceptance gate, then emits and verifies the npm tarball, Windows ZIP, UXP CCX, per-artifact SHA-256 files, and release-manifest.json. For a local non-publishable verification build, add --allow-dirty.

CEP upgrade and legacy-conflict guard

Close Premiere Pro before upgrading the CEP bridge and daemon. The CEP ready handshake is protocol-versioned and identity-checked, so the CEP files and daemon must use a compatible bridge protocol. Installing both from the same release is the supported upgrade path; install them together, then reopen Premiere:

powershell -ExecutionPolicy Bypass -File scripts/install-all.ps1 -RestartDaemon

The installer audits each immediate child of %APPDATA%\Adobe\CEP\extensions by its CSXS\manifest.xml bundle ID. If the obsolete com.local.ppmcp.cep.2026 bundle is present, installation fails closed with CEP_LEGACY_CONFLICT; similarly named folders and unrelated extensions are not changed. To migrate that exact legacy bundle, opt in to reversible quarantine:

powershell -ExecutionPolicy Bypass -File scripts/install-all.ps1 `
  -RestartDaemon -QuarantineKnownLegacyCep

The legacy folder is moved outside CEP discovery under %LOCALAPPDATA%\PremiereMCP\quarantine\cep\<timestamp-id>\. Its original path, bundle ID, manifest SHA-256, quarantine time, and restore location are recorded in quarantine.json; it is not permanently deleted by the installer. Restarting Premiere after the move is required because terminating or moving a loaded CEP folder does not unload that runtime from the current Premiere process.

UXP plugin install (.ccx)

The UXP bridge is what lets the MCP server reach the Premiere 26.x APIs that CEP/ExtendScript cannot. It ships both as an unpacked plugin folder and as a single .ccx package:

node scripts/build-ccx.mjs      # -> dist/premiere-pro-full-mcp-2.0.0.ccx
powershell scripts/install-uxp.ps1

install-uxp.ps1 copies uxp-plugin/ into %APPDATA%\Adobe\UXP\Plugins\External\com.codex.premiere-pro-full-mcp_<version>\ (which Premiere auto-discovers) and seeds the shared HMAC key + bridge-settings-v1.json into the plugin data folder so the panel authenticates and finds the daemon immediately. Some Premiere/UXP builds gate the External loader behind Adobe UXP Developer mode; the installer enables that flag when the Developer settings path is present unless -NoDevMode is supplied. A CCX installed through Adobe's trusted loader does not need that development flag. install-all.ps1 runs daemon + CEP + UXP in one shot.

The panel opens via Window > Extensions > Premiere Pro Full MCP. It connects on load and reconnects automatically on daemon restart or panel re-show (the bridge module is idempotent and never tears down the socket on hide/destroy).

MCP registration

Point your MCP client at this package's entry (dist/index.js) with stdio transport. The server prints the loopback WebSocket port to stderr on startup; the CEP extension reads %LOCALAPPDATA%\PremiereMCP\bridge-endpoint.json to connect back. The UXP panel reads the bridge port from its plugin data folder.

Tool surface

• Every tool is premiere_<name> and takes only that tool's arguments.

• premiere_capabilities returns the connected host, uxpConnected, uxpOperations, uxpCatalogCounts, operation protocol versions, and recovery status.

• premiere_connection_status reports daemon/CEP/UXP session state, queues, quarantine, and unresolved operations. premiere_health_check performs a short callback/transport probe by default, performs an actual read-only app.project probe with mode: "dom_readiness", or acknowledges one recovery item with its current fingerprint. The default responsive: true proves only that the CEP evalScript callback returned; it is deliberately separate from transportResponsive and domReady in the DOM-readiness result. Before resuming mutations after a host error, require three DOM-readiness successes in the same session/generation (`operationStatus.domReadiness.consecutiveSuccesses

  = 3). Premiere exposes no reliable generic modal-state API, so modalStateremainsunknown`. Each mutation still requires its own 5-second target snapshot preflight; a blocked UI or DOM failure prevents dispatch.

• Read-only operations never use mutation postflight snapshots and terminate as FAILED, not UNKNOWN, even when the transport retains outcomeUnknown: true as a diagnostic. Mutation UNKNOWN, quarantine, and recovery semantics remain unchanged.

• Tools remain flat and need no approval dialog, but mutating calls receive a bounded operation ID, pre/post project fingerprint, script hash, target sequence hint, and terminal status in %LOCALAPPDATA%\PremiereMCP\operations\operation-ledger-v1.jsonl. Script, argument, and result bodies are not persisted.

• Recovery fingerprints use a bounded projection: up to 128 project sequences, 512 project items, 32 tracks per media type, and 256 target-sequence clips. Effect/keyframe/raw-script operations also inspect components and up to 256 properties across 16 clips. Time-varying properties are sampled at clip start/mid/end without materializing unbounded key arrays. Sequence settings use a fixed field projection. BOUNDED_MATCH means only that this projection matches the preflight snapshot; truncation metadata remains part of the fingerprint and it is not a full-project proof. Fingerprints from a different projection version are reported as INCOMPARABLE_PROJECTION, never as a project change or match.

Premiere does not expose a rollback transaction across multiple host calls. Treat a CUT edit as a staged workflow: inspect/checkpoint, bounded placement, verify, save_project, bounded keyframes, verify, and save_project again. Stop after any failure or UNKNOWN; never replay a timed-out mutation automatically.

License

MIT. The official adobe-premiere-pro-mcp (MIT) tool-name list is used as a compatibility floor; implementations are original and local-first.