PremiereProMCP MCP Server

Premiere Pro MCP (PPMCP)

Control Adobe Premiere Pro from Claude, Cursor, or any MCP-compatible AI client — real timeline editing, not just project metadata.

Developer: CaYaDev · cayadev.com

[!IMPORTANT] To install: go to Releases, download PPMCP-Setup-x.x.x.zip, extract it, then double-click Setup.bat. That single file runs the whole installer.

Language	File
English	README.md (this file)
Turkish	README.tr.md
Spanish	README.es.md
German	README.de.md
French	README.fr.md
Japanese	README.ja.md
Chinese (Simplified)	README.zh-CN.md

---

Install (start here)

Full step-by-step guide: INSTALL.md
(paths, UXP Developer Tool download, Claude / Claude Code / Cursor, Premiere panel)

Everyone (recommended): Setup ZIP from Releases

1. Open GitHub Releases.
2. Download PPMCP-Setup-x.x.x.zip.
3. Extract the folder → double-click Setup.bat.
4. The wizard shows install folder, version, and optional CEP Text Bridge.
5. If PPMCP is already installed, Setup offers:
   • Update / reinstall to this version
   • Uninstall completely
6. When finished, open the personalized guide (real full paths on your PC):
   • %APPDATA%\PPMCP\HOW-TO-USE.txt
   • %APPDATA%\PPMCP\HOW-TO-CONNECT.txt
   • %APPDATA%\PPMCP\mcp-config-snippet.json

Setup is pure PowerShell (built into Windows) — no third-party installer, commercial-safe.
The ZIP bundles portable Node.js — you do not need to install Node yourself.

You do need Adobe UXP Developer Tool once (free) to load the Premiere panel:

• https://developer.adobe.com/premiere-pro/uxp/plugins/distribution/install/
• https://developer.adobe.com/photoshop/uxp/2021/devtool/installation/
• Search: Adobe UXP Developer Tool download

Maintainers: build the ZIP

npm run release:win

Needs only Node.js + npm. Output: dist-release/PPMCP-Setup-*.zip

Developers: install from this repo

git clone https://github.com/CaYatur/PremiereProMCP.git
cd PremiereProMCP
npm install
npm run build
npm run dev:bridge

Or (Node already installed): installer\Setup.bat or installer\install.bat

Load plugin/manifest.json in UXP Developer Tool. Point MCP at server/dist/index.js.
Details: INSTALL.md.

---

Connect your MCP client

PPMCP is a local stdio MCP server — a Node process on your own PC that your AI client launches and talks to over stdin/stdout. There is no URL and no port to enter.

[!WARNING] Claude's Settings → Connectors → Add custom connector asks for a Remote MCP server URL. That dialog is for hosted servers and will not work for PPMCP. Use the client's local config file (or claude mcp add) instead.

Every client needs the same two values, and Setup already wrote them — with your real paths — into %APPDATA%\PPMCP\HOW-TO-CONNECT.txt and mcp-config-snippet.json:

Value	Default
command	%LOCALAPPDATA%\PPMCP\node\node.exe
args[0]	%LOCALAPPDATA%\PPMCP\server\dist\index.js

Escaping: inside a .json file every backslash must be doubled (C:\\Users\\You\\...); on a command line it must not be. This is the most common connection failure.

Claude Desktop — Setup writes this for you. By hand: edit %APPDATA%\Claude\claude_desktop_config.json (create it if missing), merge into the existing "mcpServers" object, then fully quit and reopen the app — closing the window is not enough.

{
  "mcpServers": {
    "premiere-pro": {
      "command": "C:\\Users\\You\\AppData\\Local\\PPMCP\\node\\node.exe",
      "args": ["C:\\Users\\You\\AppData\\Local\\PPMCP\\server\\dist\\index.js"]
    }
  }
}

Claude Code (CLI) — --scope user makes it available in every project; check with claude mcp list.

claude mcp add premiere-pro --scope user -- "C:\Users\You\AppData\Local\PPMCP\node\node.exe" "C:\Users\You\AppData\Local\PPMCP\server\dist\index.js"

Cursor — same JSON as Claude Desktop, in %USERPROFILE%\.cursor\mcp.json (global) or .cursor\mcp.json (this project only).

VS Code / GitHub Copilot agent mode — the one client with a different shape: the key is servers, not mcpServers, and it needs an explicit "type": "stdio". Put it in .vscode/mcp.json, or run the MCP: Open User Configuration command.

{
  "servers": {
    "premiere-pro": {
      "type": "stdio",
      "command": "C:\\Users\\You\\AppData\\Local\\PPMCP\\node\\node.exe",
      "args": ["C:\\Users\\You\\AppData\\Local\\PPMCP\\server\\dist\\index.js"]
    }
  }
}

Windsurf — %USERPROFILE%\.codeium\windsurf\mcp_config.json (or Cascade panel → MCP icon → Configure), mcpServers shape, then reload Windsurf.

Any other MCP client — Cline, Roo Code, Continue, Zed, LM Studio, JetBrains AI, Gemini CLI, Codex CLI, or your own host: give it transport stdio (some clients call it "local", "command", or "process"), the Node path as the command, and the server path as the single argument. Nearly all of them use the mcpServers shape above; VS Code's servers + "type": "stdio" is the only common variant. A client that offers only a remote URL field cannot run PPMCP.

Test without any client — this should print a startup line and then wait (Ctrl+C to stop). If it does, the server is fine and the problem is your client's config:

"C:\Users\You\AppData\Local\PPMCP\node\node.exe" "C:\Users\You\AppData\Local\PPMCP\server\dist\index.js"

Building from source instead of the Setup ZIP? Run npm run build, then use node (system Node 18+) as the command and the absolute path to your clone's server/dist/index.js as the argument.

The tool surface — a starting point, not a cap

All 283 tools are loaded. A profile only decides how many are registered when the session starts, because putting 283 schemas in front of a model costs thousands of tokens and measurably worsens tool selection.

PPMCP_PROFILE	Registered at start	Use when
core	19	Small/cheap models; edit_bootstrap → edit_auto → edit_verify only
standard (default)	112	Live-verified tools plus the atomics a real cut uses
full	283	Entire catalog resident from the first turn, as in 1.0.x

The model can widen this itself, mid-session. If it decides it needs more, it calls tool_profile — no restart, no config edit, no asking you:

tool_profile { profile: "full" }     // register all 283
tool_profile { category: "color" }   // register one area, additive
tool_profile { enable: ["clip_reverse"] }

The server registers them and emits notifications/tools/list_changed, so your client refreshes its own tool list. Alongside that, tool_search finds tools that are not registered and tool_invoke runs any tool whether registered or not — so nothing is ever unreachable, whichever profile you pick.

"env": { "PPMCP_PROFILE": "standard" }

Full per-client walkthrough and a troubleshooting table: INSTALL.md.

---

What is this?

PPMCP is a Model Context Protocol server that connects an AI agent to a live Adobe Premiere Pro session. The model can:

• Create sequences and assemble media
• Cut, overwrite, and trim clips
• Place titles, shapes, and motion graphics
• Mix audio (SFX, music beds) with safe gain defaults
• Grade, transitions, quality pass, export, screenshots

UXP-first core editing. Optional CEP bridge only for editable MOGRT titles (PNG titles work without it).

MCP Client (Claude / Cursor / ...)
    <-> stdio
MCP Server (Node)
    <-> WebSocket :8265
Bridge / Relay
    <->
UXP Plugin (inside Premiere Pro)

---

Requirements

Requirement	Notes
Windows	Primary tested platform
Adobe Premiere Pro	26.0 or newer (UXP; plugin manifest minVersion 26.0.0)
UXP Developer Tool	Required to load the panel (download)
MCP client	Claude Desktop, Cursor, Claude Code, etc.
Node.js 18+	Only if you install from source (EXE includes portable Node)

Optional: ffmpeg / ffprobe for media analysis scripts.

---

After install (quick checklist)

1. Bridge running (Desktop PPMCP Bridge if needed)
2. UXP Developer Tool → Add Plugin → ...\plugin\manifest.json → Load
3. Premiere panel shows Active (footer: CaYaDev · cayadev.com)
4. MCP client uses paths from %APPDATA%\PPMCP\mcp-config-snippet.json
5. Call edit_bootstrap

Agent workflow: docs/AGENT_USAGE.md · skill/SKILL.md

---

Features

Timeline and media

• Import media, create sequences, set active sequence by exact name
• Place clips with overwrite; trim in/out
• Markers; sequence screenshots for visual QA

Text and graphics

• text_write (PNG always; editable MOGRT with optional CEP)
• Shapes, colors, Motion keyframes (scale / position / rotation / opacity)

Audio

• SFX and music beds; dB API (0 dB = unity)
• Scoped gain (does not mass-overwrite the user’s mix)

Color, polish, export

• quality_pass (batched for large timelines), transitions, export
  • edit_quality_pass { maxTransitions: 0 } grades with hard cuts (no dissolves); fadeEdges: false also skips the sequence fade-in/out.
  • Grading sets absolute Lumetri values per look, so it overwrites existing per-clip corrections. Check current values with effect_list_applied / color_get_params first on already-graded timelines.

Safety

Feature	Why
Rate limits	Protects Premiere from tool spam (RATE_LIMITED)
Checkpoints	Snapshot / restore project before risky edits
Playbooks / edit_run	Multi-step edits without thrash
Agent docs	Shared rules for different AI models

Example use cases

Rough cuts · cinematic SFX · music-rhythm cuts · ad-style motion cards · QA before export

---

Tool status: what's actually tested

283 MCP tools across ~20 categories. Since 1.1.0 the server registers a profile (112 by default) rather than the whole catalog — the rest stay one call away via tool_search → tool_schema → tool_invoke, and PPMCP_PROFILE=full restores the old surface. The catalog spans project, sequence, track, clip, transitions, effects — including 52 one-shot dedicated effect/audio/transition shortcuts — color/Lumetri, audio, text/titles/shapes, markers/metadata, multicam, proxy/media, export, analysis, batch, selection/system, checkpoints, agent-orchestration/edit-pipeline, plus ~22 high-level workflow tools). Most of that surface maps to a real, documented method in Adobe's own @adobe/premierepro UXP API. Real end-to-end sessions have now exercised a much wider slice of it than the ~48s smoke sequence below; the issues surfaced so far are the ones flagged below (see "Still broken" and "Lower-confidence claims") — see docs/FEATURES.md for the full tool-by-tool verification tier (type-verified / live-verified / verified-composed / known-broken).

What holds up well under real, end-to-end testing (a real ~48s multi-track sequence built from scratch, video + 4 audio tracks, transitions, gain, keyframed fades, markers, title, screenshot, save): sequence/project creation, clip_overwrite, trim, roll/slip/slide, split, ripple delete, shape add + position + fill color, text_write's PNG fallback path, listing effects/transitions, gain/dB control, and project save/screenshot. clip_append is now confirmed working in a real session — it appends clips in the correct order (it previously failed with "Script action failed to execute"; the shared-retry fix held up live). sequence_set_in_out is confirmed working too (re-tested 2026-07-11) — it set the in/out points via "via": "sequence.createSetInPointAction + sequence.createSetOutPointAction", confirming the 1.0.1 root-cause fix (the factory is on the Sequence object, not SequenceEditor). Multi-step edits (roll/slip/slide and composite workflow tools) are committed through Premiere's Project.executeTransaction() — several primitive actions run as one atomic unit, so a failure partway through doesn't leave the timeline half-edited. That transaction design has been the most reliable part of the whole plugin.

clip_insert and marker_add are more reliable than earlier testing suggested. Both now retry ~10-15 internal variants (different track-index/limit-shift/marker-type combinations) inside the plugin before giving up — in the latest real session, clip_insert succeeded on every one of ~19 video/audio clips (via one of those retry variants), and marker_add added 7 markers with no reported error. This retry loop is also part of why individual calls can feel slow. Update 2026-10-14 (Premiere 26.5.2): marker_add is live-verified on the native path ("source": "native" in the response, markers visible in Premiere's marker UI), and name, comment and duration all round-trip through marker_list.

Fixed and live-verified (2026-10-14, Premiere 26.5.2, UXP 9.3):

Tool	What was wrong	What changed / live result
app_get_version	Always returned null (read version off the Application class)	Reads require("uxp").host.version (1.0.2). Live: { version: "26.5.2", host: "premierepro", uxpVersion: "uxp-9.3.0-local" }
media_get_info / media_analyze_file_info	Never returned duration or frame rate	Duration now comes from ClipProjectItem.getMedia().getDuration(), frame rate and pixel aspect ratio from getFootageInterpretation(). Live: 3 s 25 fps test clip -> durationSeconds: 3, frameRate: 25. Width/height are still not reported: ClipProjectItem has no frame-size getter in UXP
marker_add (via workflow/analyze tools)	Markers from workflow_clean_silence, analyze_silence etc. had an empty comment and zero duration (tools sent comments, plugin read comment)	Fixed key + silence markers now carry their length. Live: SILENCE 1.0s marker with comment and durationTicks = 1.0 s
workflow_clean_silence	Markers were placed at source-file time, not sequence time	Maps each silence region through every sequence clip that uses the file (start, in-point, speed). Live: markers at 6.005 s / 8.005 s for a clip at 5.5 s trimmed by 0.495 s
shape_set_size	Width/height averaged into one uniform Scale, so only 2:1 sizes came out right	Turns off uniform scale and sets Scale Width = w/400, Scale = h/200 (the Basic Shape rectangle is 400x200 px). Live: 600x100 -> rendered red box measured 604x104 px in an exported frame (anti-aliased edges)
export_frame / sequence_export_still / sequence_export_frame	Fell back to a screenshot of the whole Premiere window (the plugin only tried non-existent exportFrame methods)	Uses Premiere's documented Exporter.exportSequenceFrame first: a real 1920x1080 sequence frame, no UI, no AME, playhead untouched. Live: PNG and JPEG
transcript_get / transcript_find_phrase (new)	No way to read Premiere's transcript	Uses Premiere's UXP Transcript API (transcribeClipProjectItem, exportToJSON) and maps every segment/word to sequence time for each instance of the clip (in point, speed and trims respected). Live: TTS test clip transcribed by Premiere via the tool; "lazy dog" found at 6.14-6.98 s and, in a second copy trimmed to source 4.0 s and placed at 19 s, at 21.14-21.98 s; markers added
workflow_cut_silence (new)	Silence could only be marked, not cut	Dry run returns the exact ranges, total seconds and a planToken; confirm: true + that token splits and ripple-deletes each range (linked A/V too), latest first. Refuses a wrong or stale token. Live: 11.84 s clip -> 3 cuts, 5.48 s removed, 6.36 s left in 3 gap-free pieces; every sentence still found by transcript_find_phrase afterwards
clip_split	Splitting at a time that isn't on a frame boundary left a half-done split ("could not find the clone"), losing the left part	Cut time is snapped to the nearest sequence frame first. Live: split at 8.0003 s -> clean split at 8.0 s

Still broken — confirmed Adobe platform limitation, not a plugin bug:

Tool	Issue	Use instead
track_add / track_add_video / track_add_audio	The Premiere UXP API exposes no method to add an empty track — verified 2026-07-11 against Adobe's official reference: neither the Sequence class nor SequenceEditor has any addTrack/addVideoTrack/addAudioTrack/createAddTrackAction. This is missing from Premiere itself; no plugin-side code can add it. Re-checked live 2026-10-14 on Premiere 26.5.2 by listing the Sequence prototype: still only track getters/counts	Choose the track count when you create the sequence (sequence_create, or a sequence preset that already has enough tracks). There is no way to add tracks afterward — and the earlier "drop a clip at a higher track index to auto-create tracks" idea does not work here either: it was tested 2026-07-11 and failed with "[INTERNAL_ERROR] BE: An invalid track index was passed to the sequence"
sequence_create / sequence_create_from_media track count	You get the preset's fixed track count (≈3 video + 3–4 audio) and — because of the track_add limitation above — can't add tracks afterward, by any means	Plan the track count at creation (a preset with enough tracks). Inserting clips beyond the existing track count fails rather than growing the track list

text_set_content on pure UXP - re-checked live 2026-10-14, still a platform gap: writing a string into a MOGRT Text or Simple Text param still fails with "Illegal Parameter type" (ComponentParam.createKeyframe() accepts no string values in UXP on 26.5.2). Editing existing text works only through the optional CEP Text Bridge with an AE-authored MOGRT; for new text use text_write / text_add. (shape_set_size, the other former lower-confidence item, is fixed - see the table above.)

Also found and fixed: a fade/keyframe ordering footgun, not a bug. workflow_audio_fade/workflow_fade_clip calculate fade keyframes from the clip's current start/end at the moment you call them — correct in isolation, but if you trim the clip's length after adding fades, the old fade-out keyframe can end up past the new out-point and silently stop applying (fade-in still works, fade-out doesn't). Both tools' descriptions now explicitly warn the model to trim to final length first.

This section gets updated as real Premiere sessions surface more ground truth — static code analysis alone has already been wrong once here (clip_insert).

---

Architecture

Path	Role
server/	MCP tools, rate limit, checkpoints
bridge/	WebSocket relay (:8265)
plugin/	UXP panel in Premiere
installer/	Windows PowerShell Setup (Setup.bat) + release packager
docs/	Architecture, agent usage, roadmap
skill/	Compact AI skill
scripts/	Smoke runs + the CI catalog/profile checks

See docs/ARCHITECTURE.md, docs/FEATURES.md and docs/ROADMAP.md.

---

Rate limits (summary)

• Soft gap between plugin calls ~100 ms
• Min gap between MCP tools ~220 ms
• High per-minute caps; too fast → RATE_LIMITED

---

Development

npm ci                 # restores workspace links; plain npm install also works
npm run build
npm run typecheck
node scripts/check-catalog.mjs   # catalog integrity, no Premiere needed
node scripts/check-profiles.mjs  # tool-profile integrity
npm run dev:bridge
npm run release:win    # build Setup ZIP (PowerShell wizard + portable Node)

npm run check runs all of the checks above plus the end-to-end MCP session and release-step tests. CI runs it on Windows and Linux (Node 20 / 22). Anything needing a live Premiere Pro session stays in scripts/smoke-*.mjs and is run by hand.

Releases are automatic: merging a PR into main bumps the version, dates the CHANGELOG's [Unreleased] section, builds the Setup ZIP and publishes the GitHub release. Bump labels: release:patch (the default), release:minor, release:major, or no-release. See docs/RELEASING.md.

---

License

MIT · CaYaDev · cayadev.com

Not affiliated with Adobe. Keep project backups / checkpoints.