adobe-mcp

adobe-mcp — Adobe Creative Cloud MCP 服务（macOS）

可通过 Claude 驱动 After Effects、Photoshop、Illustrator、Premiere Pro（以及 Character Animator 木偶制作），还可使用 Blender 和 Substance 3D Painter 进行 3D 外观开发和电影级动画。完整的工具矩阵及后续计划请参阅 ROADMAP.md。 桥接流程：MCP 客户端 → 此服务 → AppleScript DoScript → AE → 临时结果文件 → 返回。

工具

工具	用途
run_extendscript	运行任意 JSX；return <value> 会以 JSON 格式返回。自动加入撤销组。
get_project_state	获取项目项树，或详细查看某个合成的图层（comp_name）。
save_frame	将合成帧渲染为 PNG，并以内联形式返回，让 Claude 查看其作品。
list_ae_scripts	列出 scripts/ 中的 .jsx/.jsxbin 工具及其头部注释中的说明。
run_ae_script	执行库脚本，类似于“文件”→“脚本”→“运行脚本文件”。

3D 与电影级 VFX 工作流（Blender + Substance 3D Painter）

两个 Python 桥接扩展了服务的 ExtendScript 功能，让一个 Agent 可以将镜头从粗略布局推进至最终合成：

                  ┌──► Blender ──────────► Python (bpy): live add-on socket :9877, or headless `blender -b`
MCP client ───────┼──► Substance Painter ─► Python: remote scripting HTTP :60041 (/run.json)
                  └──► After Effects ────► ExtendScript via osascript (as above)

工具	用途
blender_run_python	运行 bpy 代码（result = ... 会返回 JSON）。mode：live（正在运行的 Blender）、background（无头模式，可选 blend_file / save_as）、auto。
blender_get_state	场景摘要：帧范围、fps、渲染引擎、运动模糊、相机镜头/景深、通道及所有对象。
blender_render_frame	通过场景相机渲染低采样预览帧，并以内联形式返回。
blender_render_animation	按场景输出设置渲染帧范围，并将输出注册为资产。
substance_run_python	在 Substance 3D Painter 中运行 Python（substance_painter.*）。
substance_get_state	纹理集、分辨率、图层堆栈、通道、根图层。
substance_bake_mesh_maps	启动异步网格贴图烘焙（曲率/AO 可用于智能材质）。
substance_export_textures	使用预设导出 PBR 贴图（默认为 PBR Metallic Roughness）；注册每张贴图。
vfx_plan_creature_shot	将简述（“一只照片级真实的恐龙从镜头前走过，同时转动脖子”）转换为基于物理规律推导的时序，以及各阶段按顺序执行的工具调用。

免费 CC0 纹理和 HDRI 库（Poly Haven、ambientCG）： 两者发布的所有内容均为公共领域，因此可免费用于商业项目，无需署名。

工具	用途
texture_search	在两个库中搜索 PBR 材质（type=texture）或 HDRI（type=hdri）；返回 ID、标签和缩略图。
texture_download	将一个资产以 1k–8k 分辨率下载到 <workspace>/textures（会缓存），并将贴图重命名为 <id>_BaseColor/_Roughness/_Normal/_Height/_Metallic/_ARM/_AO。
blender_apply_texture	根据库资产或本地贴图文件夹（例如 Substance 导出内容）创建 Principled 材质并应用：正确的色彩空间、OpenGL 法线、真实置换、ARM 解包、实际世界比例 tile_m，以及适用于无 UV 网格的三平面投影。
blender_set_hdri	使用库中的 HDRI（强度、旋转）为场景布光，以匹配底片。

下载的文件夹也可用作 Creature_Walk_Cinematic.py 的 texture_dir。如有需要，可设置 POLYHAVEN_API / AMBIENTCG_API 指向镜像。

库脚本（使用 run_script 运行，通过 params 传递参数）：

• scripts/blender/Creature_Walk_Cinematic.py：根据物理参数为大型双足生物设置行走动画。速度取决于弗劳德数，步幅依据 Alexander（1976）计算，双脚始终稳固着地，不会滑动。颈部和尾部的每个关节依次滞后 3 帧，头部会稳定注视方向并转向镜头，胸部则呈现呼吸起伏。摄像机采用手持式支架，带有摄影师操作滞后和脚步冲击抖动。渲染设置使用 Cycles、180° 快门、阴影捕捉器，并输出 beauty、shadow、mist PNG 序列及多层 EXR。在 Blender 5.0.1（bpy）无头模式下测试；也兼容 4.x API。
• scripts/substance/Creature_Skin_LookDev.py：可选烘焙，然后创建哑光「老化鳞片」底层、腔体遮罩湿润层，以及光泽眼部／口部材质集；所有操作均可通过一次撤销完成。支持可选导出。
• scripts/ae/Cinematic_3D_Composite.jsx：导入各通道，将阴影设为正片叠底，添加预合成的边缘光包裹效果、根据 mist 生成的深度雾、可选的景深镜头模糊、CG 柔化效果，以及仅应用于 CG 的颗粒。

设置：

• Blender 实时模式：依次选择 Edit → Preferences → Add-ons → Install from Disk → bridges/blender/adobe_mcp_bridge.py，然后启用该插件（监听 127.0.0.1:9877；可通过 BLENDER_MCP_PORT 覆盖）。后台模式无需插件；它会查找 /Applications/Blender*.app 或 PATH 中的 blender（可通过 BLENDER_PATH 覆盖）。
• Substance 3D Painter：启用远程脚本功能后启动： open -a "Adobe Substance 3D Painter" --args --enable-remote-scripting（可通过 SUBSTANCE_PAINTER_PORT 覆盖端口）。
• 两个桥接服务都仅限本地访问且未经身份验证：这台机器上任何能够访问该端口的程序都可以在应用中运行 Python。完成后，请禁用 Blender 插件或退出 Painter。

知识系统（服务会在运行过程中不断学习）

服务附带一个经过整理的知识库（knowledge/lessons.jsonl），其中汇集了真实生产会话中的经验，包括 matchName 常见问题、API 特性、参数类型陷阱及相关技巧（蓝图线条提取、无缝风循环、QE 转场、自动重构……）。

以下三种机制让知识库持续发挥作用并不断扩充：

1. 自动提示常见问题 — 每次 *_run_extendscript 调用失败时，系统都会根据课程关键词进行匹配；匹配到的内容会追加到客户端看到的错误消息中（例如，在 Premiere 中遇到 Illegal Parameter type 时，错误消息会附带 autoReframeSequence 字符串预设的解决方法）。失败记录也会作为新课程的原始素材写入 $WORKSPACE/error-log.jsonl。
2. knowledge_search / knowledge_add 工具 — Agent 会在尝试不常见的脚本操作前查阅相关课程，并在解决未被自动提示的问题后记录新的常见问题。运行时课程会保存到 $WORKSPACE/learned.jsonl（每个安装独立保存，且在仓库更新后仍然保留）。
3. 服务指令和工具描述 — 最有价值的规则（明确指定文档、视觉验证、渲染超时处理、ES3 限制）已融入 MCP 指令和各工具描述中，因此全新安装也能立即具备实用知识。

每个应用对应的 scripts/ 库是同一理念的可执行实现，将技能提炼为可重复使用的脚本（list_scripts / run_script）：蓝图线条提取（PS）、无缝风循环和动态排版支架（AE）、一键纵向自动重构（Premiere）。

安装

选项 A — 一键安装，适用于 Claude Desktop 和 Cowork（无需 Node）

1. 安装要控制的 Adobe 应用。在 After Effects 中，启用 Preferences → Scripting & Expressions → "Allow Scripts to Write Files and Access Network"。
2. 从 Releases 下载最新的 adobe-mcp-x.y.z.mcpb，然后双击它（或将它拖到 Claude Desktop → Settings → Extensions）。Claude Desktop 自带 Node 运行时，无需安装其他内容。
3. 开始使用。每个应用的首次工具调用都会触发一次 macOS Automation 权限提示，点击 Allow。

升级？ 先移除旧版本（Settings → Extensions → Adobe Creative Cloud → Uninstall），再安装新的 .mcpb。覆盖安装可能会留下旧文件，但仍显示新版本号。

选项 B — 通过 npm 使用任意 MCP 客户端

需要在系统范围内安装 Node 18+（使用 nodejs.org 安装程序或运行 brew install node — 请注意，图形界面应用通常无法使用由 nvm 管理的安装）。无需克隆项目，也无需运行 npm install：以下每种客户端配置都会运行

npx -y @ajsmonty/adobe-mcp

选项 C — 从源代码安装（贡献者）

git clone https://github.com/AJSMonty/adobe-mcp.git ~/tools/adobe-mcp
cd ~/tools/adobe-mcp && npm install
# point your client at: node ~/tools/adobe-mcp/server.mjs

仅限 Premiere Pro： ppro_* 工具需要安装一次随附的 CEP 面板 — 将 cep/mcp-bridge 复制到 ~/Library/Application Support/Adobe/CEP/extensions/，并启用 PlayerDebugMode（参见备注），然后在 Premiere 中打开 Window → Extensions → MCP Bridge。

连接到 MCP 客户端

这是一个标准的 stdio MCP 服务 — 任何支持 MCP 的客户端都可以使用它（Claude Code、 Claude Desktop、Cursor、Windsurf、VS Code Copilot Agent 模式、Zed、Cline、Goose，等等）。 以下内容只是以各客户端的配置格式展示相同的一行命令： 通过 stdio 运行 npx -y @ajsmonty/adobe-mcp（如果是从源代码检出，则运行 node .../server.mjs）。

Claude Code

claude mcp add --scope user adobe -- npx -y @ajsmonty/adobe-mcp

--scope user = 在所有项目中可用；在仓库中使用 --scope project，即可通过 .mcp.json 与团队共享。验证方式：claude mcp list。

Claude Desktop

依次打开 Settings → Developer → Edit Config，并添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "adobe": {
      "command": "npx",
      "args": ["-y", "@ajsmonty/adobe-mcp"]
    }
  }
}

完全退出并重新打开 Claude Desktop。

Cursor

依次打开 Settings → MCP → Add server，或编辑 ~/.cursor/mcp.json（全局）/ .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "adobe": {
      "command": "npx",
      "args": ["-y", "@ajsmonty/adobe-mcp"]
    }
  }
}

在 Settings → MCP 中启用，然后使用 Agent 模式（composer）— 工具调用会显示审批提示。

VS Code（Copilot Agent 模式）

在工作区中的 .vscode/mcp.json（或通过 "MCP: Add Server" 命令创建用户级 mcp.json）：

{
  "servers": {
    "adobe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ajsmonty/adobe-mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json — 格式与上述 Claude Desktop/Cursor 的 mcpServers 相同。

其他客户端

只要客户端支持通过 stdio 使用 MCP，指定 npx -y @ajsmonty/adobe-mcp 即可。

客户端注意事项

• macOS Automation 权限按宿主应用分别授予。 每个新客户端（Cursor、VS Code、其他终端）首次调用工具时，都会触发该客户端控制 Adobe 应用的 Automation 权限提示 — 在 System Settings → Privacy & Security → Automation 中为每个宿主应用批准一次。
• 行内图像预览（ae_save_frame、ps_save_preview、ai_save_preview、 ppro_save_frame）会返回 MCP 图像内容。Claude 客户端和 Cursor 会将其行内渲染； 不支持图像渲染的客户端仍会收到元数据文本，模型也可以改为导出文件并从磁盘读取。
• 服务说明（操作规则和知识库指引）通过 MCP 的 instructions 字段发送；大多数客户端会将其传递给模型。如果你的客户端不会这样做，相同规则也已写入工具描述和 knowledge_search 中。

脚本库（“skills”）

将 .jsx / .jsxbin 文件放入 scripts/，即可通过 list_ae_scripts / run_ae_script 使用。

• 操作脚本（对当前选区进行操作，无 UI）以无头模式运行——先通过 run_extendscript 设置选区。
• ScriptUI 面板脚本会在 AE 窗口中打开面板，供用户点击操作。
• 带有可分离核心函数的普通 .jsx 面板，通常可以通过移除 UI 启动代码并执行源代码来以无头模式驱动。

⚠️ scripts/ 中可能包含第三方工具或付费工具。除非已获得再分发授权，否则请将此仓库设为私有，或将 scripts/ 添加到 .gitignore。

注意事项

• 自动从 /Applications 检测 AE 应用（最新的 “Adobe After Effects *”）。可通过环境变量 AE_APP_NAME 覆盖，例如在桌面配置中设置 "env": {"AE_APP_NAME": "Adobe After Effects 2025"}，或在 claude mcp add 中使用 --env AE_APP_NAME=...。
• AE 必须打开并载入一个项目（空白默认项目也可以）。
• 超时通常意味着 AE 正显示模态对话框——请将其关闭。
• save_frame 需要 AE 2022 或更高版本。

ExtendScript 易踩的坑（都是惨痛教训）

• ExtendScript 是 ES3：不支持箭头函数、模板字面量、let / const、JSON、Array.map。
• 集合（project.items、comp.layers、属性组）使用 从 1 开始的索引。
• 通过 matchName（"ADBE Glo2-0002"）而不是显示名称来访问效果参数——显示名称可能重复。
• .property() 查找失败会抛出一个 原生错误，其自身的字符串化操作也会抛出错误——请将 e.toString() 放入单独的 try/catch 中，否则错误处理器也会崩溃。
• 文本图层会自动重命名为其源文本——如需稳定查找，请重命名图层。
• 摄像机：兴趣点位于 锚点属性槽（ADBE Anchor Point）中。
• 无论维度如何，空间属性在 setTemporalEaseAtKey 中都需要 长度为 1 的缓动数组。
• 将子图层设为旋转图层的父级时，补偿会烘焙到子图层的变换中——如果子图层应继承方向，请在设为父级后将子图层的旋转归零。
• 网格效果：在为锚点制作动画前，先设置 Size From（ADBE Grid-0002 = 3），否则“滚动”会调整单元格大小。

冒烟测试

AE 打开后，询问 Claude：“使用 get_project_state 告诉我 AE 项目里有什么，然后创建一个名为 ‘Test’ 的 1920x1080 合成，其中包含一个标题文本图层，并显示一帧。”

贡献与治理

欢迎提交 PR——请参阅 CONTRIBUTING.md。所有合并到 main 和 dev 的更改都需要维护者批准（分支保护 + CODEOWNERS）。知识库经验是最容易提供的高价值贡献。安装前请阅读 SECURITY.md：此服务会按设计在 Adobe 应用中执行脚本。

许可证

MIT