内容
# Premiere Pro MCP (PPMCP)
**通过 Claude、Cursor 或任何兼容 [MCP](https://modelcontextprotocol.io) 的 AI 客户端控制 Adobe Premiere Pro - 真实的 timeline 编辑，而不仅仅是项目元数据。**
**开发者：** [CaYaDev](https://cayadev.com) · [cayadev.com](https://cayadev.com)
> [!IMPORTANT]
> **安装：**前往 **[Releases](https://github.com/CaYatur/PremiereProMCP/releases)**，下载 `PPMCP-Setup-x.x.x.zip`，解压，然后双击 **`Setup.bat`**。该文件运行整个安装程序。
| 语言 | 文件 |
|----------|------|
| **中文（简体）** | [README.zh-CN.md](./README.zh-CN.md)（此文件） |
| 土耳其语 | [README.tr.md](./README.tr.md) |
| 西班牙语 | [README.es.md](./README.es.md) |
| 德语 | [README.de.md](./README.de.md) |
| 法语 | [README.fr.md](./README.fr.md) |
| 日语 | [README.ja.md](./README.ja.md) |
| 英语 | [README.md](./README.md)（此文件） |
---
# 安装（从这里开始）
**完整的逐步指南：** **[INSTALL.md](./INSTALL.md)**
（路径，UXP 开发者工具下载，Claude / Claude Code / Cursor，Premiere 面板）
## 所有用户（推荐）：从 Releases 安装 ZIP
1. 打开 **[GitHub Releases](https://github.com/CaYatur/PremiereProMCP/releases)**。
2. 下载 **`PPMCP-Setup-x.x.x.zip`**。
3. 解压文件夹 → 双击 **`Setup.bat`**。
4. 安装向导显示 **安装文件夹**、**版本** 和可选的 **CEP 文本桥**。
5. **如果 PPMCP 已经安装**，安装向导提供：
- **更新/重新安装** 到此版本
- **完全卸载**
6. 完成后，打开个性化指南（您 PC 上的实际完整路径）：
- `%APPDATA%\PPMCP\HOW-TO-USE.txt`
- `%APPDATA%\PPMCP\HOW-TO-CONNECT.txt`
- `%APPDATA%\PPMCP\mcp-config-snippet.json`
安装是 **纯 PowerShell**（内置于 Windows）- 没有第三方安装程序，商业安全。
ZIP 捆绑了 **便携式 Node.js** - 您不需要自己安装 Node。
您 **需要** Adobe **UXP 开发者工具** 一次（免费）来加载 Premiere 面板：
- https://developer.adobe.com/premiere-pro/uxp/plugins/distribution/install/
- https://developer.adobe.com/photoshop/uxp/2021/devtool/installation/
- 搜索：**Adobe UXP 开发者工具下载**
### 维护者：构建 ZIP
```bash
npm run release:win
```
只需要 Node.js + npm。输出：`dist-release/PPMCP-Setup-*.zip`
## 开发者：从此仓库安装
```bash
git clone https://github.com/CaYatur/PremiereProMCP.git
cd PremiereProMCP
npm install
npm run build
npm run dev:bridge
```
或者（已安装 Node）：`installer\Setup.bat` 或 `installer\install.bat`
在 UXP 开发者工具中加载 `plugin/manifest.json`。在 MCP 中指向 `server/dist/index.js`。
详情： **[INSTALL.md](./INSTALL.md)**。
---
## 连接您的 MCP 客户端
PPMCP 是一个 **本地 stdio MCP 服务器** - 一个 Node 进程在您的 PC 上，您的 AI 客户端直接与其通信。它 **不是** 一个托管的“远程 MCP 连接器”，因此您可能在 Claude 的连接器设置中看到的“添加自定义连接器”→远程 MCP 服务器 URL 流并不适用于此处。指向本地命令。
安装后，您的确切即用路径已在 `%APPDATA%\PPMCP\HOW-TO-CONNECT.txt` 和 `mcp-config-snippet.json` 中生成。常规形式：
**Claude Desktop** - 安装程序自动将此写入 `claude_desktop_config.json`。手动操作时，将此合并到 `"mcpServers"` 对象中：
```json
{
"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）：
```bash
claude mcp add premiere-pro -- "C:\Users\You\AppData\Local\PPMCP\node\node.exe" "C:\Users\You\AppData\Local\PPMCP\server\dist\index.js"
```
**Cursor** - 设置 → MCP → 添加服务器（本地命令，不是 URL）：
- 命令：上述 Node 路径
- 参数：上述服务器路径
从源代码构建而不是安装 ZIP？使用您 PATH 上的 `node` 和存储库中的 `server/dist/index.js`。
---
## 这是什么？
PPMCP 是一个 **模型上下文协议** 服务器，它将 AI 代理连接到 **实时 Adobe Premiere Pro** 会话。模型可以：
- 创建序列和组装媒体
- 剪辑、覆盖和修剪剪辑
- 放置标题、形状和动态图形
- 混音音频（音效，音乐床）并使用安全的增益默认值
- 分级、过渡、质量检查、导出、截图
**UXP-first** 核心编辑。**可选 CEP** 桥仅用于可编辑 MOGRT 标题（PNG 标题无需此功能）。
```
MCP 客户端（Claude / Cursor / ...）
<-> stdio
MCP 服务器（Node）
<-> WebSocket :8265
桥/中继
<->
UXP 插件（在 Premiere Pro 中）
```
---
## 要求
| 要求 | 注意 |
|-------------|--------|
| **Windows** | 主要测试平台 |
| **Adobe Premiere Pro** | 支持 UXP（例如 25 / 26+） |
| **UXP 开发者工具** | 需要加载面板（[下载](https://developer.adobe.com/premiere-pro/uxp/)） |
| **MCP 客户端** | Claude Desktop, Cursor, Claude Code 等 |
| **Node.js 18+** | 仅当您从源代码安装时（EXE 包括便携式 Node） |
可选：**ffmpeg / ffprobe** 用于媒体分析脚本。
---
## 安装后（快速检查清单）
1. 桥运行（如果需要，**PPMCP Bridge**）
2. UXP 开发者工具 → 添加插件 → `...\plugin\manifest.json` → 加载
3. Premiere 面板显示 **Active**（页脚：CaYaDev · cayadev.com）
4. MCP 客户端使用 `%APPDATA%\PPMCP\mcp-config-snippet.json` 中的路径
5. 调用 **`edit_bootstrap`**
代理工作流：[docs/AGENT_USAGE.md](./docs/AGENT_USAGE.md) · [skill/SKILL.md](./skill/SKILL.md)
---
# 功能
### 时间线和媒体
- 导入媒体，创建序列，按 **确切名称** 设置活动序列
- 放置剪辑并覆盖；修剪 in/out
- 标记；序列截图用于视觉 QA
### 文本和图形
- **`text_write`**（始终为 PNG，可选 CEP 为可编辑 MOGRT）
- 形状、颜色、动态关键帧（缩放/位置/旋转/不透明度）
### 音频
- 音效和音乐床；dB API（0 dB = 统一）
- 范围增益（不覆盖用户的混音）
### 颜色、润色、导出
- **`quality_pass`**（批量处理大型时间线），过渡，导出
### 安全
| 功能 | 为什么 |
|---------|-----|
| 速率限制 | 保护 Premiere 免受工具垃圾邮件的侵害（`RATE_LIMITED`） |
| 检查点 | 在风险编辑之前快照/恢复项目 |
| 攻略/ `edit_run` | 多步骤编辑，无需反复尝试 |
| 代理文档 | 不同 AI 模型的共享规则 |
### 示例用例
粗略剪辑 · 电影音效 · 音乐节奏剪辑 · 广告风格动态卡片 · 导出前 QA
---
## 工具状态：实际测试内容
**277 个 MCP 工具**，涵盖约 20 个类别（项目、序列、轨道、剪辑、过渡、效果 - 包括 52 个一键专用效果/音频/过渡快捷方式 - 颜色/Lumetri、音频、文本/标题/形状、标记/元数据、多摄像机、代理/媒体、导出、分析、批处理、选择/系统、检查点、代理编排/编辑管道，以及约 22 个高级工作流工具）。其中大部分功能映射到 Adobe 自己的 `@adobe/premierepro` UXP API 中的真实文档方法。实际端到端会话现在已经测试了更广泛的工具，而不仅仅是下面的 ~48 秒烟雾序列；到目前为止发现的问题是下面标记的问题（参见“仍然损坏”和“较低置信度声明”）- 参见 [docs/FEATURES.md](./docs/FEATURES.md)，了解按工具验证级别划分的完整工具验证层级（类型验证/实时验证/验证组合/已知损坏）。
**实际端到端测试中表现良好**（一个真实的 ~48 秒多轨道序列，从头开始构建，视频 + 4 个音频轨道，过渡，增益，关键帧淡入，标记，标题，截图，保存）：序列/项目创建、`clip_overwrite`，修剪，滚动/滑动/滑行，分裂，删除并涟漪删除，添加形状 + 位置 + 填充颜色，`text_write` 的 PNG 回退路径，列出效果/过渡，增益/ dB 控制，和项目保存/截图。 **`clip_append` 现已确认有效** - 它按正确顺序追加剪辑（以前失败并显示 `"Script action failed to execute"`；共享重试修复程序已生效）。 **`sequence_set_in_out` 也已确认有效**（重新测试 2026-07-11）- 它通过 `"via": "sequence.createSetInPointAction + sequence.createSetOutPointAction"` 设置 in/out 点，确认 1.0.1 根原因修复（工厂位于 Sequence 对象上，而不是 `SequenceEditor`）。多步骤编辑（滚动/滑动/滑行和复合工作流工具）通过 Premiere 的 `Project.executeTransaction()` 提交 - 几个基本操作作为一个原子单元运行，因此在过程中失败的部分不会使时间线部分编辑完毕。 该交易设计是整个插件中最可靠的部分。
**`clip_insert` 和 `marker_add` 比早期测试更可靠**。两者现在在放弃之前在插件内部重试约 10-15 个内部变体（不同的轨道索引/限制转换/标记类型组合）。在最新的实际会话中，`clip_insert` 成功地完成了约 19 个视频/音频剪辑（通过其中一个重试变体），`marker_add` 添加了 7 个标记，没有报告错误。 我们尚不确定 marker_add 运行是否通过原生路径或虚拟标记回退（两者返回相同的成功消息）- 将 `marker_add` 视为“可能有效，未确认哪条路径”，而不是“已知损坏”。
**已应用修复，待实时重新测试（尚未重新确认）：**
| 工具 | 问题所在 | 更改内容 |
|------|-----------------|--------------|
| `app_get_version` | 始终返回 `null` - 代码从 `Application` **类** 读取 `version`，但根据 Adobe 的 `ppro_reference`，`version` 是实例属性（`Promise<string>`，25.6+），因此它从未解析 | 现在使用 UXP **主机** 对象 (`require("uxp").host.version`) 读取版本，这是每个 UXP 应用程序公开的构建无关路径；返回 `{ version, host, uxpVersion }`。修复在 1.0.2 中（`ppro.Application.version` 仅作为廉价防护） |
| `media_get_info` / `media_analyze_file_info` | 永远不会返回持续时间、分辨率或帧率 | 现在机会性地探测几个额外字段 (`getDuration`, `getFrameSize`, `width`/`height`, `getFrameRate`)，功能检测 - 如果此 Premiere 版本恰好公开任何，则返回它们，否则为 `undefined`（不比以前更糟） |
**仍然损坏 - 确认 Adobe 平台限制，不是插件错误：**
| 工具 | 问题 | 替代方案 |
|------|-------|--------------|
| `track_add` / `track_add_video` / `track_add_audio` | Premiere UXP API **没有** 方法添加空轨道 - 2026-07-11 验证 Adobe 官方参考：`Sequence` 类和 `SequenceEditor` 都没有 `addTrack`/`addVideoTrack`/`addAudioTrack`/`createAddTrackAction`。这是 Premiere 自身缺少的功能；插件代码无法添加它 | 选择轨道计数 **创建序列时** (`sequence_create`，或已具有足够轨道的序列预设）。 **没有办法在之后添加轨道** - 更早的“在更高的轨道索引处放置剪辑以自动创建轨道”的想法 **不适用**：它在 2026-07-11 被测试并失败，显示 `"[INTERNAL_ERROR] BE: An invalid track index was passed to the sequence"` |
| `sequence_create` / `sequence_create_from_media` 轨道计数 | 您获得预设的固定轨道计数（≈3 视频 + 3-4 音频），并且 - 由于上面的 `track_add` 限制 - 无法在之后添加轨道，任何方式 | 计划创建时的轨道计数（具有足够轨道的预设）。插入剪辑超出现有轨道计数失败，而不是增加轨道列表 |
**较低置信度声明（来自早期静态代码分析，未在此会话中重新验证）：** `text_set_content`（编辑现有 MOGRT 文本）和 `shape_set_size`（精确像素大小）之前通过代码级探针发现损坏 - 参见 [docs/FEATURES.md](./docs/FEATURES.md)，了解详细信息 - 但鉴于 `clip_insert` 结果比同类分析表明的更固定，请将这些视为“值得实时重新检查”，而不是福音。
**还发现并修复了一个脚枪，不是 bug.** `workflow_audio_fade`/`workflow_fade_clip` 根据您调用它们时的剪辑 **当前** 起始/结束时间计算淡入/渐变关键帧 - 在隔离中正确，但在添加渐变后修剪剪辑长度时，旧的渐变输出关键帧可能会超出新的输出点并默默停止应用（渐入仍然有效，渐出无效）。两个工具的描述现在明确警告模型首先修剪到最终长度。
本节会随着实际 Premiere 会话揭示更多真相而更新 - 静态代码分析已经过时一次（`clip_insert`）。
---
## 架构
| 路径 | 角色 |
|------|------|
| `server/` | MCP 工具、速率限制、检查点 |
| `bridge/` | WebSocket 中继 (`:8265`) |
| `plugin/` | Premiere 中的 UXP 面板 |
| `installer/` | Windows PowerShell 安装程序（Setup.bat）+ 发布打包器 |
| `docs/` | 架构和代理使用 |
| `skill/` | 紧凑的 AI 技能 |
参见 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) 和 [docs/FEATURES.md](./docs/FEATURES.md)。
---
## 速率限制（摘要）
- 插件调用之间的软间隔 ~100 ms
- MCP 工具之间的最小间隔 ~220 ms
- 每分钟高上限；太快 → `RATE_LIMITED`
---
## 开发
```bash
npm install
npm run build
npm run dev:bridge
npm run release:win # 构建安装 ZIP（PowerShell 向导 + 便携式 Node）
```
---
## 许可证
MIT · **CaYaDev** · [cayadev.com](https://cayadev.com)
不隶属于 Adobe。请保持项目备份/检查点。
