PS-MCP-IMT — Photoshop for AI agents

PS-MCP-IMT — Photoshop for AI agents, with two ways in

An MCP server that lets an AI agent (Claude Desktop, Cursor, ChatGPT or any MCP-compatible client) drive a running Adobe Photoshop: documents, layers, text, masks, selections, filters, adjustments, Smart Objects, artboards, generative tools, export — from natural language.

Built by Immersive Media Technologies as the Photoshop backbone of the Deep Artisan agent pipeline, and released so that other agent builders can use the same layer. A fork of alisaitteke/photoshop-mcp (merged through 1.7.27) with a second transport, a small tool surface, honest errors and no telemetry.

macOS and Windows · Photoshop 2024–2026 · Node.js 18+ (we run 26). macOS is what we run every day (Photoshop 2026, 27.9–27.10); the Windows transport (ExtendScript through COM, with the UTF-16 result fix and a retry on the COM «busy» error) passes the same live sweep on Windows 11 with Photoshop 2026 — reports from Windows users are still welcome.

[!CAUTION] This tool edits real Photoshop documents and sends document contents (names, layer structure, text, rendered previews) to the AI service you use. Start with a copy, check your AI provider's data policy for NDA work, and keep ps_execute_script and ps_uxp script (arbitrary code inside Photoshop) behind your agent's permission policy.

Why this one

Most Photoshop MCP servers stop at «the AI can run a script». Two things break that in daily use: Photoshop goes modal (a dialog, a progress bar, a tool in search mode) and every script call hangs until a timeout; and the agent drowns in a hundred tool definitions. This fork keeps a second transport inside Photoshop (UXP) for exactly those moments, shows the agent 9 tools instead of 134, and tells it the truth when something cannot be done.

Facts about other projects are from their READMEs and repository metadata on GitHub on 2026-10-01 (adb-mcp: 716 stars, last push 2026-07-08, «proof of concept»; dcc-mcp-photoshop: v0.2.0; alisaitteke/photoshop-mcp: 1.7.27 of 2026-09-30); corrections welcome.

What you can ask for

• "Open poster.psd, put the client's logo on the billboard in perspective — corners at (412,88), (1388,140), (1370,690), (430,655) — and keep it editable."
• "Replace the sky with this dusk one (sky.jpg), then export a 2000-px JPEG for review."
• "Split this layout into Instagram, X and Story artboards and export each as PNG."
• "Set the headline to Inter Bold 96 pt, tracking −20, only the word SALE in red."
• "Build a frequency-separation stack at 6 px — I'll paint the Low / High layers myself."
• "Photoshop is showing a dialog — tell me what is open and save the document anyway." (the save goes through the UXP bridge)

The agent combines the operations itself through ps_do, checking ps_get_state / ps_get_layers between steps and verifying with ps_export_frame (a PNG of the current state).

Install

Requirements: Adobe Photoshop 2024+ running on this computer (2026 verified), macOS or Windows — platform specifics are in the two sub-sections below the table. Pick the route for your client:

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

macOS

Verified daily (Photoshop 2026, 27.9–27.10). The server drives Photoshop through AppleScript; the first call asks for the Automation permission (System Settings → Privacy & Security → Automation; AppleScript error −1743 means it was denied). From source, with a live self-test — the route we run ourselves:

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

The script checks Photoshop and Node, builds the server and the UXP plugin, pings the running Photoshop through the real transport, and — after asking — writes the entry into Claude Desktop's, Cursor's and Google Antigravity's config files (backing them up first). --no-config only prints the snippet; --yes skips the questions.

Windows

Verified on Windows 11 with Photoshop 2026 (same live sweep as macOS: 193 / 0 / 11). The server talks to Photoshop through COM (cscript + a VBScript shim, results decoded as UTF-16); the bridge retries the transient COM «busy» error (PSMCP_BUSY_RETRY_MS, default 2000 ms). Set PHOTOSHOP_PATH when Photoshop is not under C:\Program Files\Adobe.

• Claude Desktop: the .mcpb has no file association on Windows — if a double-click shows an app picker, drag the file onto Settings → Extensions instead.
• From source: .\install.ps1 (same steps as install.sh; if scripts are blocked: powershell -ExecutionPolicy Bypass -File .\install.ps1). Node.js 18+ from nodejs.org; Git for Windows or MinGit.
• UXP bridge: on Windows x64 install the .ccx as on macOS. On Windows on ARM Photoshop has no Plugins menu and loads no third-party UXP plugins at all (Adobe has not enabled the plugin infrastructure there yet) — the server works without the bridge.

The UXP bridge (second transport)

A 10-KB panel plugin, Deep Artisan Bridge (uxp-plugin/, id com.deepartisan.ps-bridge), lives inside Photoshop and polls the server. It runs state, layers, batchplay, eval_js, export_png, save and neural_filter inside core.executeAsModal, so it answers while ExtendScript is blocked. Install one of three ways, in this order of convenience:

1. Double-click dist/uxp/deepartisan-ps-bridge.ccx (Creative Cloud). If Creative Cloud says «Plugin Not Compatible» — it does when Photoshop is missing from its installed-apps list — use 2 or 3.
2. UXP Developer Tools → Add Plugin → uxp-plugin/manifest.json → Load.
3. Manual layout into Adobe's UXP plugin folder plus one entry in PluginsInfo/v1/PS.json — exact paths and the JSON line in docs/development.md.

Then Photoshop → Plugins → Deep Artisan Bridge; leave the panel in your workspace so the plugin loads with Photoshop. The port is protected by a shared-secret file the server creates on first start and the plugin reads; a request without it gets 401, /health is open and reveals nothing. Several MCP clients at once (Claude Desktop, Cursor, Deep Artisan …) share one bridge: the first server owns the port, the others relay to it. Honest about the boundary: the file is readable by any process of your user account (like an .env) — it protects against other users, sandboxes and a stray client on the port, not against malware running as you.

Tools

With PS_MCP_FACADE=1 the agent sees nine tools:

ps_uxp(action: ping | batchplay | script) appears when the bridge is on: batchPlay descriptors and JavaScript in the UXP context (photoshop, uxp, params, await allowed).

Behind the facade: 134 tools — 109 atomic photoshop_* in 21 categories (document, layer, image, smart_object, transform, filter, adjust, text, selection, mask, action, history, state, generative, neural, style, color, data, stack, export, artboard) and 16 recipes, each recipe one history state. Without the facade flag all of them are exposed directly, as in upstream. Reference: docs/available-tools.md; the fork-specific photoshop_distort_layer takes corners (four [x, y] in document pixels), mode (perspective | bilinear) and rasterize for Smart Objects.

Safety model for agents

• One envelope for every failure: { ok: false, code, message, suggested_next_tool }. The codes that matter for an autonomous loop: photoshop_busy (Photoshop is modal — tell the user, do not retry blindly), extendscript_timeout (a script is still running — ping until it answers), scratch_disk_full, command_unavailable (the document state forbids the command — not a version problem), no_active_document, generative_credits_exhausted.
• photoshop_ping never launches Photoshop and fails while a previous script is still running instead of reporting a healthy connection; other tools launch Photoshop when it is closed, as upstream does.
• Gate what Cmd+Z cannot revert: ps_execute_script, ps_uxp script, close_document, save_document over the original, batch exports. Everything else is one history state.
• Nothing leaves the machine except what your MCP client sends to its model: there is no analytics, no feedback prompt, no update check. The UXP bridge listens on 127.0.0.1 only and requires the shared-secret header.
• Upstream's live test suite (npm run test:mcp-all) edits a scratch document in the running Photoshop; run it with no client work open.

Changes against upstream

See CHANGELOG.md (section 0.4.1) and THIRD-PARTY-NOTICES.md. In short: the UXP bridge as a second transport with a shared-secret token; the 9-tool facade; photoshop_distort_layer; photoshop_busy / command_unavailable and the 8-second read timeout; telemetry, feedback nudge, web UI, website and packaging removed. Upstream fixes are merged from alisaitteke/photoshop-mcp by topic, one at a time (currently through 1.7.27).

Release history

Each version is described on the **Releases** page — what the server does at that version and what the release added:

• v0.4.5 · 2026-10-03 — fix: Photoshop is detected automatically on the first call (no more «detect Photoshop first»).
• v0.4.4 · 2026-10-01 — fix: the ChatGPT gateway command under npx -p.
• v0.4.3 · 2026-10-01 — ChatGPT in one command (gateway + tunnel), client icons in Install.
• v0.4.2 · 2026-10-01 — one-click installs: Claude Desktop extension (.mcpb), «Add to Cursor», npm package, install.sh / install.ps1 that write the client configs.
• v0.4.1 · 2026-10-01 — first public release of the IMT fork: the full server (134 tools) on upstream 1.7.27, plus the UXP bridge, the facade, headless corner-pin and the modal-Photoshop error model.

Every change, including the upstream history 1.0.0 – 1.7.27, is in CHANGELOG.md.

License

IMT Non-Commercial License — © Immersive Media Technologies.

• Non-commercial use only. Selling this software, offering it as or inside a paid product or service, or using it in commercial client work requires a separate written license from Immersive Media Technologies.
• Attribution is mandatory. Every use, copy, fork or derived product must credit the creator, visibly to its users: PS-MCP-IMT by Immersive Media Technologies — https://github.com/Immersive-Media-Technologies.
• No warranty.

Full terms: LICENSE. Third-party notices: THIRD-PARTY-NOTICES.md.