Premiere Pro MCP Server

Premiere Pro MCP 服务

一个可操控 Adobe Premiere Pro 的 MCP 服务：管理项目和素材箱、序列及其设置、时间线编辑、标记、效果、关键帧和转场、转录文本、元数据和导出。它运行在安装了 Premiere Pro 的计算机上，并通过 Premiere Pro 内部的一个小型 UXP 插件与之通信。

状态：尚未在真实的 Premiere Pro 上测试。 每个脚本都依据 Premiere Pro 的 UXP API 参考进行检查，并在测试中的替代 DOM 上运行，但目前尚未在 Premiere Pro 中运行过。可能存在一些问题；请参阅目前尚不确定的内容。

需要 Premiere Pro 25.6 或更高版本（macOS 或 Windows）、用于加载插件的 UXP Developer Tool，以及 Node.js 18 或更高版本。

为什么需要插件

Premiere Pro 没有本仓库中其他服务使用的外部脚本接口：没有 AppleScript 字典，Windows 上也没有 COM 对象，而其 /C es.processFile 命令行仅在 Premiere Pro 启动时有效、不返回结果，且不受支持。Adobe 支持的 Premiere Pro 自动化方式是在其内部运行插件，而 UXP 是 Adobe 正在转向的平台（从 Premiere Pro 25.6 起普遍可用；CEP 将于 2027 年 12 月停止接受新的 Marketplace 提交，并于 2029 年 12 月移除）。

UXP 插件可以打开 WebSocket 连接，但无法接受连接。因此，此服务监听 127.0.0.1，由插件连接到它：

MCP client --stdio--> adobe-mcp-premiere --ws://127.0.0.1:3011--> MCP Bridge panel (in Premiere Pro)

只需运行一个进程：MCP 服务同时也是 WebSocket 服务。

安装

1. 将此服务添加到你的 MCP 客户端。

   Claude Code：

   claude mcp add premiere -- npx -y adobe-mcp-premiere
   

   任何读取 mcpServers 块的客户端：

   {
     "mcpServers": {
       "premiere": {
         "command": "npx",
         "args": ["-y", "adobe-mcp-premiere"],
         "env": { "BRIDGE_TOKEN": "a long random string" }
       }
     }
   }
   

2. 在 Premiere Pro 中加载插件。在插件正式发布之前，请使用 UXP Developer Tool 加载：

   • 在 Premiere Pro 中，前往 Plugins 设置并开启 Developer Mode。
   • 从 Creative Cloud 应用安装并打开 UXP Developer Tool。
   • 点击 Add Plugin，并从此软件包中选择 uxp/plugin/manifest.json：在克隆的仓库中，路径为 packages/premiere/uxp/plugin；运行 npm install adobe-mcp-premiere 后，路径为 node_modules/adobe-mcp-premiere/uxp/plugin。premiere_status 会打印服务运行所用副本的文件夹路径。
   • 点击 Load，然后从 Premiere Pro 的 Window 菜单中打开 MCP Bridge 面板。

3. 在面板中设置端口（除非你更改了 PREMIERE_WS_PORT，否则为 3011）和令牌（如果设置了 BRIDGE_TOKEN），然后点击 Connect。面板会记住这两项设置，并在连接断开时每隔 3 秒重新连接，因此 MCP 服务重启后会自动重新连接。

4. 请客户端运行 premiere_status。它会显示端口、插件是否已连接、Premiere Pro 版本以及当前项目。

使用约定

• 序列通过 sequence 选择：{ name }、{ guid }（来自 list_sequences），或省略以使用当前序列。
• 项目项通过 item 选择：{ id }（来自 list_project_items）、{ path: "Footage/Interviews/a.mov" }（相对于项目根目录的素材箱），或 { name }（仅当名称唯一时）。
• 序列中的剪辑通过 clip: { track, trackIndex, clipIndex } 选择，具体格式见 list_clips 的报告：track 为 video 或 audio，索引从 0 开始（轨道 0 为 V1 或 A1）。需要多个剪辑的工具使用 clips: { items: [...], selected: true }，其中 selected 会添加时间线中当前选定的剪辑。编辑后索引会变化；请重新列出。
• 效果通过 list_clip_effects 返回的组件索引和参数名称（或索引）选择。
• 时间以秒为单位。文件必须使用用户主目录内或 PREMIERE_ALLOWED_DIRS 中目录下的绝对路径；除非传入 overwrite: true，否则写入文件的工具不会覆盖现有文件。

工具

区域	工具
项目	get_project_info、create_project（新建空项目或使用模板）、open_project（关闭对话框）、save_project（或另存为）、close_project（或关闭所有项目）、revert_project、list_project_items（或选择“项目”面板中的项目）、search_project_items（按名称、媒体路径、类型、脱机状态搜索）、get_clip_info（媒体路径、入点/出点、脱机状态、代理、素材解读）、import_media（导入任何可导入的格式、导入到素材箱、图像序列）、create_bin（或搜索素材箱）、manage_items（重命名、移至素材箱、标签颜色、删除）
媒体	import_project_sequences（从其他项目导入指定序列）、import_after_effects_comps（动态链接）、relink_media（单个剪辑，或按文件名查找脱机剪辑）、manage_media（刷新、设为脱机、附加代理或全分辨率媒体）、modify_footage（解读素材、时间码、缩放至帧大小）、reveal_media_file（在 Finder 或 Explorer 中显示）、get_project_media_settings、set_project_media_settings（摄取、暂存磁盘、增长文件）
序列	list_sequences、create_sequence（默认设置、.sqpreset 或根据剪辑创建）、open_sequence、get_sequence_settings、set_sequence_settings（帧大小、帧速率、像素纵横比、场、编辑模式、显示格式、采样率、预览、位深、渲染质量、线性色彩）、duplicate_sequence、delete_sequence、close_sequence、create_subsequence（创建子序列）、set_sequence_times（入点/出点、零点、工作区、播放头）、move_playhead（帧、编辑点、间隙、标记、入点/出点）、run_scene_edit_detection（切点、标记或子剪辑）、get_sequence_properties、set_sequence_properties（自定义属性）
时间轴	list_tracks（视频、音频、字幕）、list_clips（或按名称查找）、insert_clip、overwrite_clip（可选源范围）、trim_clip（源入点/出点、序列起点/终点）、edit_clips（滑移、滚动、滑动、修剪至播放头）、select_clips（指定剪辑、全部、无、播放头处、向前、向后、下一个、上一个）、fit_clips_to_frame（设置为帧大小）、move_clips、remove_clips（清除或波纹删除）、set_clip_properties（名称、启用）、set_track_properties（静音、重命名）、insert_mogrt
标记	list_markers、add_marker、edit_marker（名称、备注、类型、持续时间、颜色、移动）、remove_markers（序列或剪辑标记）、mark_clips（标记剪辑、标记所选内容）
源	create_subclip、set_source_in_out（设置或清除；也会标记要编辑的音频范围）、scale_to_frame_size、control_source_monitor（打开、播放、关闭、匹配帧）
效果	list_available_effects（视频效果、音频效果、视频转场）、list_clip_effects、apply_effect（视频效果按匹配项或显示名称应用，音频效果按显示名称应用）、remove_effect、set_effect_param、add_keyframes（带插值）、remove_keyframes、add_transition（开始、结束或两端；持续时间；单侧；替换）、remove_transition、set_clip_transform（运动或矢量运动、不透明度、混合模式）、copy_clip_effects（粘贴属性）、manage_source_effects（源剪辑效果）
关键帧	jump_to_keyframe（下一个或上一个）、copy_keyframes（复制到其他参数或剪辑）、retime_keyframes（拉伸或压缩动画）、fade_clips（不透明度或音量淡入淡出）
颜色	set_lumetri_color（按名称设置基本校正、创意、颜色轮、HSL 二级和晕影参数，或按索引设置任意参数）、set_clip_input_lut（覆盖输入 LUT）
音频	set_clip_volume（音量效果的级别）、adjust_clip_audio（以 dB 为单位调整音量、声像或平衡）
图形和字幕	list_graphics_templates（已安装的 .mogrt 文件）、insert_library_mogrt（从 Creative Cloud 库插入）、list_transcription_languages（及语言包）、import_captions（SRT、SCC、MCC、DFXP、STL、XML）
转录文本	transcribe_clip、export_transcript（返回内容或写入 .json）
导出	export_sequence（编码器预设；立即导出、加入 Media Encoder 队列或加入 Premiere Pro 队列；完整序列或入点至出点；XMP；导入结果）、encode_media（将项目项或媒体文件加入 Media Encoder 队列）、export_frame（PNG、JPEG、TIFF、DPX、EXR、……）、export_timeline（Final Cut Pro XML、OpenTimelineIO、AAF）
元数据	get_metadata（项目元数据和 XMP）、set_metadata、get_metadata_display（“项目”面板列）、set_metadata_display（列、新建架构字段）
应用程序	wait_for_event（项目、序列、Media Encoder、导出和导入事件）、clear_media_cache、recover_project（崩溃后恢复自动保存副本）
实用工具	premiere_status、execute_premiere_code、help
help({ tool }) 用于说明任意工具的参数。

大多数工具适用于 Premiere Pro 25.6。以下功能需要更高版本，并会在描述中注明：export_timeline（26.2；AAF 需要 26.3）、重命名轨道（26.3）、export_sequence 的 startQueue 和 xmp（26.3）、set_sequence_settings 中的帧速率（26.2）、close_sequence（26.2）、create_subclip（26.3）、定位源监视器（26.3）、set_sequence_times 中的工作区间（26.5）、transcribe_clip 和 clear_media_cache（26.5）。在较旧版本中，这些调用会失败，并显示一条消息 transcribe_clip（26.5）、在 list_transcription_languages 中列出语言（26.3；较早版本可检查给定代码）。在较旧版本中，这些调用会失败，并显示一条消息 指出所需版本。

以下功能未提供，因为 Premiere Pro 的 UXP API 没有对应调用：链接和取消链接片段、音频转场、播放节目监视器、片段速度、片段增益（音量效果的电平除外）、编辑字幕文本、轨道目标、嵌套、菜单命令、撤销、Lumetri 的自动按钮，以及 Lumetri 曲线（RGB 和色相饱和度曲线点并非简单的参数值）。

如何让它不打扰你

• 每次调用仅执行一个撤销步骤。 编辑在 project.lockedAccess 中构建，并通过 project.executeTransaction 执行，这是 Premiere Pro 从 26.3 起的要求，因此每次调用在“编辑”>“撤销”中对应一条记录。Premiere Pro 不会记录的少数步骤（播放头、轨道静音、工作区间、保存）会明确说明。
• 不显示对话框。 打开和关闭项目时会关闭 Premiere Pro 的提示；导入时会传入 suppressUI。
• 一次只运行一个脚本。 插件按顺序运行脚本，不会同时运行多个脚本。
• 超时会说明原因。 如果 Premiere Pro 在 PREMIERE_SCRIPT_TIMEOUT_MS（默认 120 s）内未响应，错误会提示可能有对话框处于打开状态。长时间导出和转录时请调高此值。
• 脚本中不包含原始输入。 调用方传入的每个值都会经过验证，并作为 JSON 字面量写入脚本。

配置

变量	用途
PREMIERE_WS_PORT	插件连接到 127.0.0.1 的端口。默认值为 3011。请在面板中设置相同的端口。
BRIDGE_TOKEN	共享密钥。设置后，插件必须发送该密钥才能连接；请在面板中输入。若需要使用与 InDesign 桥接不同的令牌，PREMIERE_BRIDGE_TOKEN 优先。
PREMIERE_ALLOWED_DIRS	用于导入、保存和导出的额外目录（macOS 上以 : 分隔，Windows 上以 ; 分隔）。
PREMIERE_SCRIPT_TIMEOUT_MS	等待脚本的时长。默认值为 120000。
PREMIERE_CONNECT_WAIT_MS	调用等待插件连接后再报错的时长。默认值为 4000。

安全

• 仅限本地。 服务只监听 127.0.0.1，不会监听其他网络接口。
• 令牌。 如果未设置 BRIDGE_TOKEN，当没有插件连接时，本机上的任何程序都可以作为插件连接到该端口（随后会收到脚本并可以作答），也可以通过下文所述的 HTTP 端点发送脚本。在其他人或不受信任软件会使用的机器上，请设置 BRIDGE_TOKEN。设置令牌后，插件的第一条消息必须携带该令牌（令牌错误时，连接会以代码 4001 关闭；5 s 内未收到消息时，会以代码 4002 关闭），HTTP 端点则要求提供 Authorization: Bearer <token>。令牌采用恒定时间比较。
• 仅限一个插件。 插件连接期间，任何其他连接都会以代码 4009 关闭，即使令牌正确也一样。
• 不接受网页请求。 带有 Origin 标头的 HTTP 请求（即来自浏览器页面的请求）会被拒绝。
• 插件能够执行的操作。 面板会以插件的权限运行服务器发送的任何内容：Premiere Pro DOM 和网络访问权限（清单允许访问所有域名，因为端口可配置；插件本身只连接到 127.0.0.1）。插件不会请求文件系统权限：Premiere Pro 会自行读取和写入文件，且路径已由服务器检查。 execute_premiere_code 会不受限制地运行你自己的代码。
• 面板会以纯文本形式将令牌存储在其 localStorage 中。

同时运行两个 MCP 客户端

每个 MCP 客户端都会启动自己的服务器副本，但只有一个进程可以监听该端口。第一个副本开始监听；后启动的副本会发现该端口已被本服务器的另一个副本占用（它会请求 GET /status），于是通过 HTTP（使用令牌的 POST /execute）将脚本转发给它。随后，两个客户端的脚本都会通过同一个插件连接逐个运行。如果第一个服务器退出，另一个服务器收到下一次调用时会接管该端口，并等待面板最多 PREMIERE_CONNECT_WAIT_MS，面板会在 3 s 内重新连接。

如果端口被其他程序占用，调用会失败并提示这一情况：请选择其他 PREMIERE_WS_PORT，并在面板中也设置该端口。如果第二个副本使用了不同的令牌，系统会提示令牌不一致。

在 adobe-mcp-suite 中，端口会在首次调用 Premiere Pro 时打开，而非在启动时打开。

目前尚不确定的内容

这些内容依据 Adobe 的 UXP 参考文档，但尚未确认能在 Premiere Pro 中正常运行：

• 项目项。 通过 FolderItem.cast 和成功调用 getItems() 来区分素材箱与剪辑，并通过 ClipProjectItem.isSequence() 来识别序列。数值型 ProjectItem.type 会原样报告，因为其取值未见文档说明。
• 移动剪辑。 move_clips 将偏移量传给 createMoveAction；参考文档仅说明该方法接受 TickTime 参数。
• 关键帧时间。 add_keyframes 设置 Keyframe.position；其时间是相对于剪辑还是序列尚无文档说明，因此请使用 list_clip_effects 报告的时间。
• 音量。 set_clip_volume 通过英文显示名称查找 Volume 效果及其 Level 参数。adjust_clip_audio 会将 Level 乘以分贝比例，因此不依赖 Level 到 dB 的映射方式；它传入的声像值与效果控件中显示的一致（-100 至 100），但尚未确认 Panner 如何存储该值。
• 按名称查找效果。 set_clip_transform、fade_clips、copy_clip_effects 和 set_lumetri_color 通过英文显示名称查找效果和参数（Motion、Opacity、Blend Mode、Lumetri Color 及其设置）。尚未在 Premiere Pro 中核实任何 Lumetri 名称，也未核实 Input LUT、Look、色轮和 HSL Secondary 范围的值类型；如果效果中没有相应名称，会报告该效果实际包含的名称。混合模式按其在 Blend Mode 菜单中的位置写入（Normal = 0）；blendModeIndex 接受原始值。
• 相对于剪辑的关键帧。 jump_to_keyframe、copy_keyframes、copy_clip_effects 和 fade_clips 将关键帧时间视为剪辑的源时间（In 点是剪辑的第一帧），与 ExtendScript 的处理方式一致。开启动画是否会自动添加一个关键帧，尚不清楚。
• 源剪辑效果。 文档未说明如何使用 manage_source_effects 应用或移除这些效果；该工具会检查效果数量是否发生变化。
• 导出的帧。 exportSequenceFrame 接受文件名和文件夹；服务会分别传入基本文件名和文件夹。
• 媒体。 分层文件会以合并方式导入（importFiles 没有图层选项），而 EDL、AAF 和 FCP XML 与其他文件一样通过 importFiles 导入。 modify_footage 使用 FootageInterpretation 对象携带的 FIELD_TYPE_* 和 ALPHACHANNEL_* 值设置场序和 Alpha。 set_project_media_settings 传入临时磁盘文件夹路径，而参考文档仅列出 ScratchDiskFolder 常量。素材箱搜索查询会按原样传入；其语法未见文档说明。
• Media Encoder 作业。 encode_media 按 Adobe 示例传入范围值：0（全部）、1（入点到出点）或 2（工作区）；对于整个文件，它会传入无效的结束时间（将 TickTime 除以零生成，参考文档称其会返回 TIME_INVALID），与示例传入 TickTime.TIME_INVALID 的方式一致。
• 事件。 wait_for_event 报告的事件信息取决于事件对象携带的普通值；参考文档未对此作出说明。
• 自动保存副本。 recover_project 会在自动保存临时磁盘中查找以项目命名的副本；如果 Premiere Pro 以符号形式报告默认位置，则会在项目旁的 "Adobe Premiere Pro Auto-Save" 中查找。
• 面板的 WebSocket。 Premiere Pro 的 UXP 是否会发送 Origin 标头，以及带端口的、更窄范围的 network.domains 条目是否可用，尚不清楚；premiere_status 会显示其检测到的来源。

请提供你发现的情况，并注明 Premiere Pro 版本。

ArtCraft（FilmCraft）支持

此服务通过透明的适配器支持 Storytold 的 FilmCraft 非线性时间线视频编辑器。如果未安装或未运行 Premiere Pro，或者设置了 PREMIERE_TARGET=craft（或 ADOBE_TARGET=craft），兼容的工具会直接路由到 FilmCraft 的 loopback bridge 协议（默认端口为 127.0.0.1:9876，也可通过 FILMCRAFT_CONTROL_PORT 设置）。

开发

npm test         # bridge over real sockets, plugin runtime, definitions, arguments, scripts, static audit
npm run audit    # the audit alone, with findings listed
npm run check    # syntax check

审计会使用示例参数运行每个工具，并解析其生成的每个脚本；每个 ppro.<Class>、静态成员、构造函数和 ppro.Constants.<Enum>.<VALUE> 都必须存在于 tests/fixtures/premiere-uxp-api.json 中，其他每个成员都必须属于某个 UXP 类或原生 JavaScript，而使用 25.6 之后新增成员的工具必须声明所需版本。 该 fixture 列出能力图谱记录的 67 个类，以及它们在 Adobe 的 Premiere UXP 参考（AdobeDocs/uxp-premiere-pro，Apache-2.0）中的成员和常量；运行 npm run fixtures 可重新生成它（参见 scripts/generate-fixtures.js）。tests/fixtures/feature-ids.json 列出了工具可声明的图谱功能 ID。