Photoshop Full MCP v2

Photoshop Full MCP v2 是一个面向 Photoshop 的本地、能力门控的 MCP 服务器。它面向已安装的 Photoshop 2026 (27.9)，同时避免版本和安装路径假设。

Windows 快速开始

先决条件：Windows 10/11、Photoshop 24 或更高版本、Node.js 20 或更高版本，以及 Codex Desktop 或 Codex CLI。Photoshop 2026 (27.9) 是参考主机。

1. 从最新版本下载 photoshop-full-mcp-v2.0.0-windows.zip 及其 .sha256 文件，然后解压 ZIP 文件。

2. 在解压后的 photoshop-full-mcp-2.0.0 文件夹中打开 PowerShell，然后运行：

   powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1

   安装程序会验证捆绑的运行时，将其安装到 %LOCALAPPDATA%\PS_MCP 下，并注册一个独立的 photoshop_full_mcp 服务器。之后不再需要检出/下载文件夹。

3. 双击附带的 photoshop-full-mcp-v2.0.0.ccx 安装 Photoshop 插件。如果 CCX 安装不可用，请使用 Adobe UXP Developer Tools 并选择 Doctor 显示的已安装清单。

4. 重启 Codex，打开 Photoshop，然后选择插件 > Photoshop Full MCP Bridge。

5. 在 Codex 中调用 photoshop_pairing_begin，在 Photoshop 面板中输入六位代码，然后调用 photoshop_host_describe。返回 bridge.connected: true 的响应即为首次成功检查。

随时运行 Doctor：

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Doctor.ps1"

默认审批模式为自动。普通编辑命令无需逐一点击审批。有关更新、卸载和恢复步骤，请参阅带插图的 Windows 安装指南 和故障排除指南。

它不声称 Photoshop 的每个 UI 功能都是可脚本化的。目录分为：

• supported（受支持）：已由目标主机上的实时 Photoshop 夹具实现并验证

• experimental（实验性）：取决于授权、模型、网络或积分

• requires_user（需要用户操作）：创建带有明确原生菜单说明的非阻塞作业，用户必须完成该作业；它不会自动执行操作系统点击

• unverified（未验证）：已编入清单，但在本地夹具通过之前保持阻止状态

• unavailable（不可用）：没有已知的可靠桌面 UXP 合约

Related MCP server: Photoshop MCP Server

架构

• MCP 服务器：基于 stdio 的 Node.js/TypeScript

• Photoshop 桥接：通过经过身份验证的 127.0.0.1 的 UXP Manifest v5 面板

• 发现：端口 38452 至 38462

• 配对：仅在 photoshop_pairing_begin 打开的受信任本地 Windows 对话框中显示的六位代码

• 执行：模式验证、能力/风险策略、FIFO 队列、executeAsModal、单历史记录分组，以及前后状态验证

• 审批：默认自动；作用域绑定的一次性令牌、重放保护、路径限制和高级描述符白名单仍然强制执行

• 默认文件桥接：导出和受限重新打开使用服务器拥有的 %LOCALAPPDATA%\PS_MCP\exports 文件夹，无需选择器；用户选择的持久 UXP 文件夹仍然是可选的

• 高级原始 batchPlay：默认隐藏；设置 PS_MCP_ADVANCED=confirm 以仅公开无参数的 deselect 和 invert 描述符。其他原始描述符和所有原始 JSX 在到达 Photoshop 之前即被拒绝

• 遥测：无

完整的功能清单位于 catalog/features.json 中。可执行合约位于 catalog/commands.json 中。

当前审计状态：101 个命令合约（87 个受支持、1 个实验性、0 个未验证、11 个需要用户操作、2 个不可用）和 52 个功能组（21 个受支持、1 个实验性、0 个未验证、10 个需要用户操作、20 个不可用）。只有在签名的实时 Photoshop 27.9 夹具通过后，命令或功能组才会提升为 supported。无效的继承生成式填充和神经滤镜描述符明确不可用，格式错误或未列入白名单的原始描述符在服务器端被拒绝，因此它们无法打开 Photoshop 的未知命令对话框。

从源代码安装

建议使用上述发布 ZIP 安装。贡献者也可以克隆仓库并运行：

npm ci --no-audit --no-fund
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Local.ps1

兼容性包装器会构建一次，将自包含的生产运行时复制到 %LOCALAPPDATA%\PS_MCP，并注册该已安装副本。之后移动或删除源代码检出不会破坏 MCP 服务器。安装程序将 photoshop_full_mcp 与现有的 photoshop_mcp 一起注册；它不会删除或编辑旧包。

对于 UXP 插件，运行 npm run uxp:package 并安装生成的 CCX，或在 Adobe UXP Developer Tools 中加载 Doctor 报告的已安装清单。也可以选择在面板中选择一个导出文件夹。如果没有选择，document.export 将使用经过身份验证的服务器拥有的默认导出文件夹。

更新和卸载

# Download, verify, and install the newest GitHub release
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Update.ps1"

# Remove the installed runtime and Codex registration; preserve pairing and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1"

# Also remove pairing state and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1" -RemoveUserData

安全使用顺序

1. photoshop_host_describe

2. photoshop_capability_list

3. photoshop_state_get

4. photoshop_command_search / photoshop_command_describe

5. photoshop_command_execute

6. 视觉更改后使用 photoshop_preview_get

破坏性、验证性、消耗积分和白名单高级命令由本地服务器自动批准，因此无需在 Photoshop 面板中点击审批。photoshop_approval_request 仍作为兼容性 API 保留，并立即返回已完成的作用域绑定作业。仅当您有意希望使用以前的点击审批工作流时，才设置 PS_MCP_APPROVAL_MODE=panel。路径沙箱、能力状态门控、重放保护和原始描述符白名单不会被绕过。

对于本地主机验证，使用 PS_MCP_VALIDATION=confirm 启动临时服务器。这会公开 photoshop_validation_request 和 photoshop_command_validate。它们仅接受已编入目录的未验证 UXP DOM 命令，默认自动批准，并且仅对名为 PS_MCP_VALIDATION_* 的文档进行操作。验证执行永远不会自动提升能力。

清单和实时证据审计

npm run check 包含对每个命令和功能条目的机器审计。审计报告处理程序存在性、实时夹具来源、目录合约摘要漂移以及状态/引擎/路由一致性。除非 evidence/live 下存在匹配的事务绑定夹具，否则 supported 命令或功能将无法通过检查，因此仅凭实现或文档字符串无法提升支持状态。

使用以下命令生成完整的只读报告：

npm run audit:inventory:json

提升审查还要求新捕获的 photoshop_host_describe 结果当前已连接桥接。实时夹具本身还必须带有有效的本地证据签名：

npm run audit:promotion -- --promotion-command selection.ellipse --host-report .\host-describe.json

当 UXP 桥接未实时连接时，即使存在较旧的夹具，该命令也会以 LIVE_HOST_DISCONNECTED 失败。不再接受来自调用方编写的主机、结果或断言 JSON 的证据。记录器自行启动验证配置文件的 MCP 会话，验证已连接的 Photoshop 身份，接收自动作用域绑定审批，在 PS_MCP_VALIDATION_* 文档中执行命令，检查状态和像素预览哈希，在需要时执行撤销往返，关闭临时文档，并签署事务收据：

Set-Content .\validation-args.json '{"left":0,"top":0,"right":64,"bottom":64}'
npm run evidence:record -- --command selection.ellipse --args .\validation-args.json

私有证据签名密钥存储在 %LOCALAPPDATA%\PS_MCP 下，并带有仅限用户的 ACL；仓库中仅存储公共验证密钥。记录器仅写入哈希和白名单主机/验证元数据。它不会复制像素、文档内容或名称、提示、桥接令牌、请求参数或原始 Photoshop 结果。记录证据不会编辑 catalog/commands.json；状态提升仍然是单独的已审查更改。

验证

npm run check
npm test
npm --prefix apps\uxp-plugin run check
npm run build
npm run test:contract

实时生成测试被有意排除在外。必须明确批准，因为它们可能消耗积分并依赖于已登录的 Adobe 帐户。

如果验证运行被中断，请在清理前检查活动文档。维护命令默认为试运行，一旦活动标题不是拥有的 PS_MCP_* 验证标题，立即停止：

npm run cleanup:owned-documents
npm run cleanup:owned-documents -- --apply

添加录制的 ActionJSON

使用 Photoshop 开发人员操作记录器捕获命令，然后生成未验证的目录条目：

node .\scripts\import-action-recording.mjs --id filters.example --category filter --en "Example Filter" --ko "예제 필터" --file .\recording.json

导入器会打印目录定义和 SHA-256 证据摘要。它永远不会将命令提升为 supported；提升需要隔离文档集成夹具。

数据位置

• 配对密钥和端点元数据：%LOCALAPPDATA%\PS_MCP

• 默认导出：%LOCALAPPDATA%\PS_MCP\exports

• UXP 令牌：Photoshop UXP 安全存储

密钥和预览图像数据永远不会写入日志。