Photoshop-MCP-IMT + SKILLS — Photoshop for AI agents

Photoshop-MCP-IMT + SKILLS — 面向 AI Agent 的 Photoshop，两种接入方式

让 AI Agent（Claude Desktop、Cursor、ChatGPT 或任何兼容 MCP 的客户端）操控正在运行的 Adobe Photoshop：文档、图层、文本、蒙版、选区、滤镜、调整、智能对象、 画板、生成式工具、导出——只需使用自然语言。

支持 Adobe 的所有 UI 语言 · 丰富的技能库 · 专为生成式功能打造。 Photoshop-MCP-IMT 支持 Adobe 提供的所有 UI 语言，附带丰富的技能库，专为 Adobe 的生成式功能打造——生成式填充、生成式扩展、生成式放大、文生图、Firefly 和合作伙伴模型、生成式积分。

两个部分，协同工作：

• MCP 服务 — 135 个工具，精简为 10 个工具；在 Photoshop 内提供第二种传输方式， 应对对话框阻断脚本的情况；如实报告错误；不收集遥测数据。
• 技能（skills/ps，也通过 ps_skill 工具提供，因此适用于任何客户端）——如何安全地操控 Photoshop、脚本的能力边界，以及如何使用 Photoshop 自带的 AI 工具： 生成式填充 / 扩展 / 移除、生成图像和背景、合作伙伴模型及其积分、 参考图像、提示词编辑、和谐化、生成式放大、移除工具、AI 助手—— 还包括结合使用这些功能的修图、色彩、选区和批处理配方，以及各种注意事项。

由 Immersive Media Technologies 构建。基于 alisaitteke/photoshop-mcp 的分支（合并至 1.7.27）， 新增第二种传输方式、精简的工具集、如实报告错误，并且不收集遥测数据。

macOS 和 Windows · Photoshop 2024–2026 · Node.js 18+（我们使用 26）。 我们日常使用 macOS （Photoshop 2026，27.9–27.10）；Windows 传输方式（通过 COM 使用 ExtendScript，并修复 UTF-16 结果问题，且在 COM 报告“忙碌”错误时重试）已在 Windows 11 和 Photoshop 2026 上通过相同的实时测试——仍欢迎 Windows 用户反馈。

注意

此工具会编辑真实的 Photoshop 文档，并将文档内容（名称、图层结构、 文本、渲染预览）发送到你使用的 AI 服务。请从副本开始处理；涉及 NDA 的工作时，请查看 AI 服务提供商的 数据政策；并确保将 ps_execute_script 和 ps_uxp script（在 Photoshop 内执行任意代码）置于 Agent 的权限策略保护之下。

为什么选择它

大多数 Photoshop MCP 服务止步于“AI 可以运行脚本”。日常使用中有两个问题会让这一点行不通： Photoshop 进入模态状态（弹出对话框、显示进度条、工具处于搜索模式），每次脚本调用都会一直挂起 直到超时；而 Agent 又被上百个工具定义淹没。这个分支为此在 Photoshop 内新增第二种传输方式（UXP）， 将 Agent 看到的工具数量精简为 10 个，并在无法完成任务时如实告知。

专为本地化版 Photoshop 打造，而不只是支持英语。 大多数 Photoshop MCP 服务会读取 Photoshop 的 英文消息和名称——在德语、日语或俄语版安装中，错误处理和图层查找都会出错。Photoshop-MCP-IMT 根据 Photoshop 的错误编号对错误分类，并且无需依赖本地化名称即可查找背景图层、 字体和动作，因此在 Photoshop 提供的所有 UI 语言中表现一致 ——已通过实时验证。

	Photoshop-MCP-IMT（本仓库）	alisaitteke/photoshop-mcp	mikechambers/adb-mcp	dcc-mcp/dcc-mcp-photoshop
通过何种方式与 Photoshop 通信	ExtendScript（osascript / COM）以及 UXP 面板插件——每次调用时选择，UXP 可作为备用方式或优先方式（PS_MCP_UXP_PREFER=1）	通过 AppleScript / COM 使用 ExtendScript（本项目是其分支）	UXP 插件 → 独立 WebSocket 代理（Python）→ MCP 服务	UXP 插件 → Rust 中间件（adobepy）→ Python MCP 服务
Photoshop 处于模态状态时	4 秒后返回 photoshop_busy，并向用户显示操作说明，等待 8 秒；读取 / 保存 / 导出仍通过 UXP 继续执行（via: uxp）	超时 30 秒 → extendscript_timeout，重试 ping	—	仅使用 UXP，因此不受影响——但完全没有 ExtendScript DOM
工具范围	已注册 135 个工具，显示 10 个（ps_catalog / ps_do / ps_batch …）——每轮约需 900 个 token 的定义，而非约 25 K；所有工具都可通过 ps_do 调用	118–122 个工具，全部显示（photoshop_* + 16 个配方）	每个应用提供“部分功能”，包含低级工具（概念验证）	8 个技能包中的 40 多个类型化工具
无界面四角变形	photoshop_distort_layer：根据四个角求解单应性的自定义扭曲；已验证 Photoshop 2026 会静默忽略 Trnf + quadrilateral（测试了 12 种组合）	—	—	—
遥测	无——分析模块为空操作，已移除反馈提示，服务端不会发送任何内容	默认启用匿名分析**（可选择退出）**，通过 photoshop_ping 显示产品反馈提示	—	—
撤销	配方 = 一个历史状态（上游）；photoshop_busy / command_unavailable / extendscript_timeout / scratch_disk_full 会告知 Agent 具体原因，而不是返回通用超时	配方 = 一个历史状态；extendscript_timeout、scratch_disk_full	—	分阶段安装，支持 --dry-run / 回执
安装	一键安装：Claude Desktop 使用 .mcpb（无需 Node），「Add to Cursor」按钮，其他客户端可使用 npx；通过 install.sh / install.ps1 安装，附带实时自检并写入客户端配置；UXP 插件可通过 .ccx、UXP Developer Tools 或手动布局安装——文档说明了每种方式及其故障模式	npx -y @alisaitteke/photoshop-mcp；仅为 Neural Filters 提供 UXP 插件	Python 3 + Node + UXP Developer Tools + 代理进程	pip install 或二进制文件；Rust 中间件
已验证环境	Photoshop 2026（27.9–27.10）、macOS、UXP 9.4.1——对每个工具进行了实时全面测试：193 项通过 / 0 项失败 / 11 项因环境跳过（2026-10-01）；Windows 11（ARM）+ Photoshop 2026——同样的测试，193 / 0 / 11（2026-10-04）	Windows + macOS	Photoshop 26+、macOS + Windows	Windows、Linux、macOS
UI 语言	Photoshop 支持的所有 UI 语言——按错误编号分类错误，而非使用本地化消息；无需本地化名称即可找到背景图层、字体（PostScript 名称）和动作；已进行实时验证
许可证	我们的作品采用 Apache-2.0 许可证（通过 NOTICE 署名）；上游代码仍采用 MIT 许可证	MIT	MIT	MIT
有关其他项目的信息来自它们截至 2026-10-01 在 GitHub 上的 README 和仓库元数据
（adb-mcp：716 个 stars，上次推送于 2026-07-08，“概念验证”；dcc-mcp-photoshop：v0.2.0；
alisaitteke/photoshop-mcp：2026-09-30 的 1.7.27）；欢迎指正。

你可以提出的需求

• “打开 poster.psd，将客户的徽标透视贴到广告牌上——角点为 (412,88)、 (1388,140)、(1370,690)、(430,655)——并保持可编辑。”
• “用这张黄昏天空图（sky.jpg）替换天空，然后导出一张 2000-px JPEG 供审核。”
• “将此版式拆分为 Instagram、X 和 Story 画板，并分别导出为 PNG。”
• “将标题设为 Inter Bold 96 pt，字距 −20，只把 SALE 一词设为红色。”
• “创建一个 6 px 的频率分离图层组——Low / High 图层我自己来绘制。”
• “Photoshop 正显示一个对话框——告诉我当前打开的内容，并照常保存文档。”（保存操作 通过 UXP 桥接完成）

Agent 会通过 ps_do 自行组合操作，在每个步骤之间检查 ps_get_state / ps_get_layers，并通过 ps_export_frame（当前状态的 PNG）进行验证。

技能

skills/ps/SKILL.md 是 Agent 首先读取的简短路由指南（不带参数调用 ps_skill）；它会 指向任务所需的参考文档（ps_skill {doc}）：

SKILL.md	工具、工作顺序（状态 → 备份 → 操作 → 先按数值、再按画面验证）、寻址方式（活动文档和图层、通过标志识别 Background 图层、坐标、作为状态的选区、本地化 Photoshop、模态 Photoshop），以及一张列出脚本在 Photoshop 中无法执行的操作及各自参考文档的表格。
references/generative.md	Generative Fill / Expand / Remove、Generate Image 和 Background、合作模型（Gemini、FLUX、GPT Image）及其费用、参考图像、Prompt to edit、Markup、Enhance Detail——哪些操作通过脚本执行，哪些仍需在 UI 中完成。
references/retouch.md	Remove 工具（无需积分）和 Find distractions、Harmonize、Generative Upscale（Firefly、Topaz）、AI Sharpen / Denoise，以及通过 UXP 桥接使用 Neural Filters。
references/selection-masking.md	选区和蒙版操作、Select Subject、移除背景的操作指南、将选区形状用作提示词、Quick Mask 强度、Sky Replacement。
references/color-retouch.md	频率分离、加深和减淡、人像增强、曲线、LUT 和调色、图层样式、文字——各操作指南的用途，以及如何将画笔操作交由用户完成。
references/batch-export.md	CSV → 卡片、水印、样机、社交媒体变体、轮播图、画板、网页导出——输入、输出及文件保存位置。
references/ai-assistant.md	AI Assistant（Photoshop Beta）、Firefly Boards、Actions，以及仅通过 UI 操作步骤的交接模式。
references/combos.md	十一种组合使用工具的任务：将产品置于新背景中、透视制作广告牌样机、人像修饰、从一个版式生成一组社交媒体素材、修复照片、制作光线匹配的合成图。
references/gotchas.md	模态 Photoshop 和 photoshop_busy、UXP 桥接、历史记录及撤销无法还原的操作、积分和输出尺寸上限、本地化名称、Windows。

支持自行加载技能的客户端可以直接加载此文件夹（例如，将 skills/ps 复制到 ~/.claude/skills/）。

安装

要求：此电脑上运行 Adobe Photoshop 2024+（已于 2026 年验证），macOS 或 Windows——平台 相关说明见下方表格的两个子章节。请选择适合你客户端的安装方式：

客户端	配置方式	所需条件
Claude Desktop	下载 photoshop-mcp-imt.mcpb，双击它，点击 安装（Windows：如果文件打开时显示应用选择器，请将 .mcpb 拖到设置 → 扩展程序）——设置对话框中有相关开关（精简工具界面、UXP bridge）	无需其他条件：Claude Desktop 自带 Node.js
Cursor	添加到 Cursor — 一键操作：Cursor 会打开并写入配置（也可以将下面的代码片段放入 ~/.cursor/mcp.json）。	Node.js 18+（npx 会获取此软件包）
Google Antigravity	设置 → 自定义 → 已安装的 MCP 服务 → 查看原始配置（或在提示词面板中输入 /mcp），然后将下面代码片段中的 photoshop 条目添加到 ~/.gemini/config/mcp_config.json；install.sh / install.ps1 会为你写入配置	Node.js 18+
ChatGPT 和其他仅接受远程服务的客户端	在 Photoshop 所在的计算机上运行一条命令——npx -p @immersive-media-technologies/photoshop-mcp-imt photoshop-mcp-imt-chatgpt——即可通过 Streamable-HTTP 网关和隧道启动服务，并输出可粘贴到 ChatGPT → 设置 → 连接器 → 创建中的公开 URL（开发者模式，身份验证：无）。Photoshop 始终在你的计算机上运行；隧道就是入口——任何知道该 URL 的人都可以在 Photoshop 运行时操控它，因此会话结束后请停止隧道（Ctrl+C）	Node.js 18+ 和隧道工具：cloudflared（无需账户；brew install cloudflared / winget install Cloudflare.cloudflared）或 ngrok（免费账户）
任何使用 JSON 配置的 MCP 客户端	将下面的代码片段放入其 mcpServers 中	Node.js 18+

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@immersive-media-technologies/photoshop-mcp-imt"],
      "env": { "PS_MCP_FACADE": "1", "PS_MCP_UXP": "1" }
    }
  }
}

macOS

每日验证（Photoshop 2026，27.9–27.10）。该服务通过 AppleScript 驱动 Photoshop；首次调用时会请求自动化权限（系统设置 → 隐私与安全性 → 自动化；AppleScript 错误 −1743 表示权限被拒绝）。从源代码运行，并进行实时自测——这是我们自己采用的方式：

git clone https://github.com/Immersive-Media-Technologies/photoshop-mcp-imt.git
cd photoshop-mcp-imt && ./install.sh

该脚本会检查 Photoshop 和 Node，构建服务和 UXP 插件，通过实际传输方式对正在运行的 Photoshop 进行 ping，并在征得同意后，将配置项写入 Claude Desktop、Cursor 和 Google Antigravity 的配置文件（先备份）。--no-config 仅打印代码片段；--yes 跳过提问。

Windows

已在 Windows 11 和 Photoshop 2026 上验证（与 macOS 相同的实时测试：193 / 0 / 11）。该服务通过 COM 与 Photoshop 通信（cscript + VBScript shim，结果按 UTF-16 解码）；桥接器会重试暂时性的 COM「忙碌」错误（PSMCP_BUSY_RETRY_MS，默认值为 2000 ms）。如果 Photoshop 不在 C:\Program Files\Adobe 下，请设置 PHOTOSHOP_PATH。

• Claude Desktop： Windows 上的 .mcpb 没有关联文件类型——如果双击后显示应用选择器，请将文件拖到“设置”→“扩展”中。
• 从源代码运行： .\install.ps1（步骤与 install.sh 相同；如果脚本被阻止： powershell -ExecutionPolicy Bypass -File .\install.ps1）。从 nodejs.org 获取 Node.js 18+；Git for Windows 或 MinGit。
• UXP 桥接： 在 Windows x64 上，按 macOS 的方式安装 .ccx。在 Windows on ARM 上，Photoshop 没有“插件”菜单，也不会加载任何第三方 UXP 插件（Adobe 尚未在该平台启用插件基础设施）——该服务无需桥接器也能运行。

变量	默认值	含义
PS_MCP_FACADE	关闭	1 / true → 客户端仅看到 10 个 ps_* 工具；其他所有操作都通过 ps_do 执行
PS_MCP_UXP	关闭	1 / true → 启动 UXP 插件的桥接服务（127.0.0.1:38452）并注册 ps_uxp
PS_MCP_UXP_PREFER	关闭	1 / true → 状态 / 图层 / 保存 / 导出优先使用 UXP，其次使用 ExtendScript
PS_MCP_UXP_TOKEN_FILE	~/.ps-mcp-imt/uxp-bridge.token	插件必须发送的共享密钥（X-PS-MCP-Bridge-Token）；首次启动时以 0600 权限创建
PHOTOSHOP_UXP_BRIDGE_PORT	38452	桥接端口
PS_MCP_READ_TIMEOUT_MS	8000	只读工具的 ExtendScript 超时时间（Photoshop 处于模态状态时可快速回退到 UXP）
PHOTOSHOP_SCRIPT_TIMEOUT	30000	其他所有操作的 ExtendScript 超时时间；ps_execute_script 中的 timeout_ms 可按调用覆盖此设置
PHOTOSHOP_PATH	自动检测	Photoshop 应用 / 可执行文件的路径
LOG_LEVEL	1	0 调试 · 1 信息 · 2 警告 · 3 错误（stderr）

UXP 桥接（第二种传输方式）

一个 10-KB 的面板插件 Photoshop-MCP-IMT Bridge（uxp-plugin/，ID 为 llc.imt.ps-mcp-bridge） 运行在 Photoshop 内部，并轮询服务。它会在 core.executeAsModal 中运行 state、layers、batchplay、eval_js、 export_png、save 和 neural_filter，因此即使 ExtendScript 被阻塞，也能响应。安装方式有三种，按便捷程度排序：

1. 双击 dist/uxp/ps-mcp-imt-bridge.ccx（Creative Cloud）。如果 Creative Cloud 提示 «Plugin Not Compatible»（当 Photoshop 不在其已安装应用列表中时就会出现此提示），请使用第 2 或第 3 种方式。
2. UXP Developer Tools → Add Plugin → uxp-plugin/manifest.json → Load。
3. 手动将文件布局到 Adobe 的 UXP 插件文件夹，并在 PluginsInfo/v1/PS.json 中添加一项 — 具体路径和 JSON 行见 docs/development.md。

然后选择 Photoshop → Plugins → Photoshop-MCP-IMT Bridge；将面板留在工作区中，以便插件随 Photoshop 一起加载。端口由服务器首次 启动时创建、插件读取的共享密钥文件保护（始终使用默认路径 ~/.ps-mcp-imt/uxp-bridge.token）；不携带该密钥的请求会收到 401，/health 无需验证且不会泄露任何信息。 多个 MCP 客户端可同时使用（Claude Desktop、Cursor 等），并共享一个桥接：第一个 服务器占用端口，其他服务器会将请求转发给它。 坦诚说明安全边界：你用户账户下的任何进程都能读取该文件（类似 .env）——它可以防范其他用户、沙箱和端口上意外连接的客户端，但无法防范以你的身份运行的恶意软件。

工具

设置 PS_MCP_FACADE=1 后，Agent 会看到十个工具：

工具	功能
ps_catalog(category?)	列出类别、数量和操作名称；指定类别时，列出该类别的所有操作及其参数
ps_do(operation, args)	按名称运行任意已注册操作（create_text_layer、distort_layer、recipe_remove_background 等）
ps_batch(ops[])	按顺序运行多个操作，每个操作返回一个结果；遇到第一个错误时停止（stopOnError）
ps_get_state / ps_get_layers	获取文档和图层状态（ExtendScript，超时 8 s，回退到 UXP）
ps_save_document / ps_export_frame(path)	保存（PSD / 原位保存），并导出当前状态的 PNG 供 Agent 查看——两者均支持回退到 UXP
ps_execute_script	执行任意 ExtendScript（每次调用均可设置 timeout_ms）——请在 Agent 策略中对其进行限制
ps_recipe(name, args)	16 种配方（移除背景、增强人像、频率分离、社交媒体变体、CSV → 卡片、水印、样机等）
ps_skill(doc?)	Photoshop Agent 技能：路由器，或按名称获取某个参考文档（generative、retouch、gotchas 等）

桥接开启时会显示 ps_uxp(action: ping | batchplay | script)：可在 UXP 上下文中使用 batchPlay 描述符 和 JavaScript（允许使用 photoshop、uxp、params、await）。

外观之后：135 个工具——10 个 ps_* 工具、21 个类别中的 109 个原子 photoshop_* 工具（document、layer、 image、smart_object、transform、filter、adjust、text、selection、mask、action、history、state、 generative、neural、style、color、data、stack、export、artboard）以及 16 种配方， 每种配方对应一个历史状态。不设置 facade 标志时，所有工具都会像上游版本一样直接公开。 参考文档：docs/available-tools.md；此分支专属的 photoshop_distort_layer 接受 corners（文档像素中的四个 [x, y]）、mode （perspective | bilinear）和用于智能对象的 rasterize。

Agent 安全模型

• 每种失败都使用同一种格式：{ ok: false, code, message, suggested_next_tool }。自主循环中需要关注的 代码包括：photoshop_busy（Photoshop 处于模态状态——告知用户， 不要盲目重试）、extendscript_timeout（脚本仍在运行——持续 ping，直到收到响应）、 scratch_disk_full、command_unavailable（文档状态不允许执行该命令——不是版本问题）、no_active_document、 generative_credits_exhausted。
• photoshop_ping 不会启动 Photoshop，并且在之前的脚本仍在运行时会失败，而不是报告连接正常； 其他工具会像上游版本一样，在 Photoshop 已关闭时启动它。
• 限制无法通过 Cmd+Z 撤销的操作：ps_execute_script、ps_uxp script、close_document、 覆盖原文件的 save_document、批量导出。其他所有操作都对应一个历史状态。
• 除了 MCP 客户端发送给其模型的内容外，任何数据都不会离开本机：没有分析数据、反馈提示词或更新检查。UXP 桥接 仅监听 127.0.0.1，并要求提供共享密钥标头。
• 上游的实时测试套件（npm run test:mcp-all）会编辑正在运行的 Photoshop 中的暂存文档；请在没有打开客户端工作时运行。

相较于上游的变更

请参阅 CHANGELOG.md（0.4.1 节）和 THIRD-PARTY-NOTICES.md。简而言之：新增 UXP 桥接作为第二种传输方式，并使用共享密钥令牌；9 工具外观层；photoshop_distort_layer；photoshop_busy / command_unavailable 和 8 秒读取超时；移除了遥测、反馈提示、Web UI、网站和打包内容。上游修复按主题逐项合并自 alisaitteke/photoshop-mcp（目前已合并至 1.7.27）。

发布历史

每个版本的说明见 Releases 页面——介绍该版本的服务功能及新增内容：

• v1.1.2 · 2026-10-28 — 全面完善描述：支持所有 Adobe UI 语言，提供大型技能库，并针对 Adobe 的生成式功能构建。
• v1.1.1 · 2026-10-28 — 产品名称改为 Photoshop-MCP-IMT（原为 PS-MCP-IMT）；服务名称改为 photoshop-mcp-imt，与 npm 包一致；修正工具数量（包含 ps_skill 的 10 工具外观层）；MCP Registry 条目也列出了 npm 包。
• v1.1.0 · 2026-10-28 — 新增 Photoshop Agent 技能（skills/ps、ps_skill）：生成式工具、合作伙伴模型和额度、修饰、选区、批处理及注意事项；产品升级为 Photoshop-MCP-IMT + SKILLS。
• v1.0.0 · 2026-10-28 — 支持所有 Photoshop UI 语言（错误按编号识别、字体按 PostScript 名称识别、操作不依赖本地化名称），新增 Photoshop-MCP-IMT Bridge 插件，采用 Apache-2.0。
• v0.4.5 · 2026-10-03 — 修复：首次调用时自动检测 Photoshop（不再需要“先检测 Photoshop”）。
• v0.4.4 · 2026-10-01 — 修复：npx -p 下的 ChatGPT 网关命令。
• v0.4.3 · 2026-10-01 — 一条命令即可运行 ChatGPT（网关 + 隧道），并在 Install 中添加客户端图标。
• v0.4.2 · 2026-10-01 — 一键安装：Claude Desktop 扩展（.mcpb）、“Add to Cursor”、npm 包，以及用于写入客户端配置的 install.sh / install.ps1。
• v0.4.1 · 2026-10-01 — IMT 分支的首次公开发布：基于上游 1.7.27 的完整服务（134 个工具），以及 UXP 桥接、外观层、无头角点定位和模态 Photoshop 错误模型。

所有变更，包括上游 1.0.0 – 1.7.27 的历史记录，均见 CHANGELOG.md。

许可证

Apache License 2.0 — © Immersive Media Technologies。

• 可免费使用、修改和分发，包括商业用途。
• 必须注明出处。 每次重新分发本软件或其衍生作品时，都必须附上 NOTICE 中的声明： Photoshop-MCP-IMT by Immersive Media Technologies — https://github.com/Immersive-Media-Technologies。
• 不提供任何保证。

第三方声明（上游 MIT 代码）：THIRD-PARTY-NOTICES.md。