Photoshop Full MCP v2

<p align="center"> <strong>If Photoshop Full MCP saves you time, consider supporting its continued development, testing, and maintenance.</strong> </p>

<p align="center"> <a href="https://ko-fi.com/muhwagwa0112"> <img src="docs/assets/kofi-support-red.png" alt="Support Muhwagwa0112 on Ko-fi" width="420"> </a> </p>

Photoshop Full MCP v2 is a local, capability-gated MCP server for Photoshop. It targets the installed Photoshop 2026 (27.9) while avoiding version and install-path assumptions.

Quick Start for Windows

Prerequisites: Windows 10/11, Photoshop 24 or later, Node.js 20 or later, and Codex Desktop or the Codex CLI. Photoshop 2026 (27.9) is the reference host.

1. Download photoshop-full-mcp-v2.0.1-windows.zip from the latest release, then extract it. The adjacent signed manifest and signature authenticate future in-app updates; the .sha256 file is an optional corruption check.

2. Open PowerShell in the extracted photoshop-full-mcp-2.0.1 folder and run:

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

   The installer verifies the bundled runtime, installs it under %LOCALAPPDATA%\PS_MCP, and registers a separate photoshop_full_mcp server. The checkout/download folder is no longer needed afterward.

3. Double-click the included photoshop-full-mcp-v2.0.1.ccx to install the Photoshop plugin. If CCX installation is unavailable, use Adobe UXP Developer Tools and select the installed manifest shown by Doctor.

4. Restart Codex, open Photoshop, then choose Plugins > Photoshop Full MCP Bridge.

5. In Codex, call photoshop_pairing_begin, enter the complete port-code value shown by the trusted Windows dialog in the Photoshop panel, and call photoshop_host_describe. A response with bridge.connected: true is the first-success check.

Run Doctor at any time:

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

The default approval mode is automatic. Normal editing commands do not require one-by-one approval clicks. See the illustrated Windows installation guide and troubleshooting guide for update, removal, and recovery steps.

It does not claim that every Photoshop UI feature is scriptable. The catalog separates:

• supported: implemented and proven by a live Photoshop fixture on the target host
• experimental: entitlement, model, network, or credit dependent
• requires_user: creates a non-blocking job with explicit native-menu instructions that the user must complete; it does not automate OS clicks
• unverified: inventoried but blocked until a local fixture passes
• unavailable: no reliable desktop UXP contract is known

Architecture

• MCP server: Node.js/TypeScript over stdio
• Photoshop bridge: UXP Manifest v5 panel over authenticated 127.0.0.1
• Discovery: ports 38452 through 38462
• Pairing: short-lived 128-bit port-code capability shown only in a trusted local Windows dialog opened by photoshop_pairing_begin
• Execution: schema validation, capability/risk policy, FIFO queue, executeAsModal, one-history grouping, and before/after state verification
• Approvals: automatic by default; scope-bound one-time tokens, replay protection, path limits, and advanced descriptor allowlists remain enforced
• Default file bridge: export and confined re-open use the server-owned %LOCALAPPDATA%\PS_MCP\exports folder without a picker; a user-selected persistent UXP folder remains optional
• Advanced raw batchPlay: hidden by default; set PS_MCP_ADVANCED=confirm to expose only the parameter-free deselect and invert descriptors. Other raw descriptors and all raw JSX are rejected before they reach Photoshop
• Telemetry: none

The broad feature inventory is in catalog/features.json. Executable contracts are in catalog/commands.json.

Current audited state: 101 command contracts (87 supported, 1 experimental, 0 unverified, 11 requires_user, 2 unavailable) and 52 feature groups (21 supported, 1 experimental, 0 unverified, 10 requires_user, 20 unavailable). A command or feature group is promoted to supported only after its signed live Photoshop 27.9 fixture passes. Invalid inherited Generative Fill and Neural Filter descriptors are explicitly unavailable, and malformed or unallowlisted raw descriptors are rejected server-side so they cannot open Photoshop's unknown-command dialog.

Install from source

Release ZIP installation above is recommended. Contributors can instead clone the repository and run:

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

The compatibility wrapper builds once, copies a self-contained production runtime to %LOCALAPPDATA%\PS_MCP, and registers that installed copy. Moving or deleting the source checkout afterward does not break the MCP server. The installer registers photoshop_full_mcp alongside an existing photoshop_mcp; it does not remove or edit the old package.

For the UXP plugin, run npm run uxp:package and install the generated CCX, or load the installed manifest reported by Doctor in Adobe UXP Developer Tools. Optionally choose an export folder in the panel. Without one, document.export uses the authenticated server-owned default export folder.

Update and uninstall

# 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

Safe usage sequence

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 after visual changes

Destructive, validation, credit-consuming, and allowlisted advanced commands are approved automatically by the local server, so no Photoshop-panel approval click is needed. photoshop_approval_request remains as a compatibility API and immediately returns a completed scope-bound job. Set PS_MCP_APPROVAL_MODE=panel only if you intentionally want the former click-to-approve workflow. Path sandboxing, capability status gates, replay protection, and raw descriptor allowlists are not bypassed.

For local host validation, launch a temporary server with PS_MCP_VALIDATION=confirm. This exposes photoshop_validation_request and photoshop_command_validate. They accept only catalogued unverified UXP DOM commands, are automatically approved by default, and operate only on documents named PS_MCP_VALIDATION_*. Validation execution never promotes a capability automatically.

Inventory and live evidence audit

npm run check includes a machine audit of every command and feature entry. The audit reports handler presence, live-fixture provenance, catalog-contract digest drift, and status/engine/route consistency. A supported command or feature fails the check unless a matching transaction-bound fixture exists under evidence/live, so an implementation or documentation string alone cannot promote support.

Generate the full read-only report with:

npm run audit:inventory:json

Promotion review additionally requires a freshly captured photoshop_host_describe result whose bridge is currently connected. The live fixture itself must also carry a valid local evidence signature:

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

The command fails with LIVE_HOST_DISCONNECTED when the UXP bridge is not live, even if an older fixture exists. Evidence is no longer accepted from caller-authored host, result, or assertion JSON. The recorder starts a validation-profile MCP session itself, verifies the connected Photoshop identity, receives automatic scope-bound approval, executes the command in a PS_MCP_VALIDATION_* document, checks state and pixel-preview hashes, performs the undo round trip when required, closes the temporary document, and signs the transaction receipt:

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

The private evidence-signing key is stored under %LOCALAPPDATA%\PS_MCP with a user-only ACL; only the public verification key is stored in the repository. The recorder writes hashes and whitelisted host/verification metadata only. It does not copy pixels, document contents or names, prompts, bridge tokens, request arguments, or raw Photoshop results. Recording evidence does not edit catalog/commands.json; status promotion remains a separate reviewed change.

Verification

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

Live generative tests are intentionally excluded. They must be explicitly approved because they may consume credits and depend on the signed-in Adobe account.

If a validation run is interrupted, inspect the active document before cleanup. The maintenance command is dry-run by default and stops as soon as the active title is not an owned PS_MCP_* validation title:

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

Adding recorded ActionJSON

Capture a command with Photoshop's developer Action Recorder, then generate an unverified catalog entry:

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

The importer prints a catalog definition and a SHA-256 evidence digest. It never promotes the command to supported; promotion requires an isolated-document integration fixture.

Data locations

• Pairing secret and endpoint metadata: %LOCALAPPDATA%\PS_MCP
• Default exports: %LOCALAPPDATA%\PS_MCP\exports
• UXP token: Photoshop UXP secure storage

Secrets and preview image data are never written to logs.