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

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

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

Let 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.

Every Adobe UI language · checks its work by sight · a large skills library · built for generative features. Photoshop-MCP-IMT works with every UI language Adobe ships, and the agent checks its work by sight: after each step it looks at an image of the document — also while Photoshop is held by a dialog — and places selections, Generative Fill areas and corner pins by coordinates it reads from that image. It comes with a large skills library and is built for Adobe's generative features — Generative Fill, Generative Expand, Generative Upscale, text to image, Firefly and partner models, generative credits.

Two parts, made to work together:

• The MCP server — 135 tools behind a 10-tool facade, a second transport inside Photoshop for the moments a dialog blocks scripting, honest errors, no telemetry.
• The skill (skills/ps, also served by the ps_skill tool, so it works in any client) — how to drive Photoshop safely, where scripting ends, and how to use Photoshop's own AI tools: Generative Fill / Expand / Remove, Generate Image and Background, partner models and their credits, reference images, Prompt to edit, Harmonize, Generative Upscale, the Remove tool, AI Assistant — plus the retouch, colour, selection and batch recipes that combine them, and the gotchas.

Built by Immersive Media Technologies. 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 10 tools instead of 135, and tells it the truth when something cannot be done.

Built for localized Photoshop, not just English. Most Photoshop MCP servers read Photoshop's English messages and names — on a German, Japanese or Russian install their error handling and layer lookups break. Photoshop-MCP-IMT classifies errors by Photoshop's error numbers and finds the Background layer, fonts and actions without localized names, so it behaves the same on every UI language Photoshop ships — verified live.

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).

The skill

skills/ps/SKILL.md is a short router the agent reads first (ps_skill with no arguments); it points to the one reference the task needs (ps_skill {doc}):

Clients with their own skill support can load the folder directly (e.g. copy skills/ps into ~/.claude/skills/).

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.gitcd 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, Photoshop-MCP-IMT Bridge (uxp-plugin/, id llc.imt.ps-mcp-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/ps-mcp-imt-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 → Photoshop-MCP-IMT 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 (always at the default path, ~/.ps-mcp-imt/uxp-bridge.token); a request without it gets 401, /health is open and reveals nothing. Several MCP clients at once (Claude Desktop, Cursor, …) 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.

How the agent sees

The agent checks every step on a picture, not on «the script said OK»: ps_export_frame writes a PNG of the current state and keeps working through the UXP bridge while Photoshop is held by a dialog; photoshop_get_preview returns a smaller image straight to the model. From that picture the model reads coordinates — where a selection, a Generative Fill area or the four corners of a corner pin belong — and the skill tells it to look again after every change: values first (ps_get_layers, selection bounds, document size), then the picture.

Tools

With PS_MCP_FACADE=1 the agent sees ten 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: 135 tools — the 10 ps_* 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:

• v1.1.4 · 2026-11-06 — the UXP bridge names an older copy that holds its port instead of «the plugin is not running»; «checks its work by sight» in the descriptions.
• v1.1.3 · 2026-11-06 — the Photoshop skill in the skill-creator form (a map of abilities with «Read when …»); README in plain Markdown for the catalogs.
• v1.1.2 · 2026-10-28 — descriptions everywhere: every Adobe UI language, a large skills library, built for Adobe's generative features.
• v1.1.1 · 2026-10-28 — product name Photoshop-MCP-IMT (was PS-MCP-IMT); server name photoshop-mcp-imt like the npm package; tool counts corrected (10-tool facade with ps_skill); the MCP Registry entry also lists the npm package.
• v1.1.0 · 2026-10-28 — the Photoshop agent skill (skills/ps, ps_skill): generative tools, partner models and credits, retouch, selection, batch, gotchas; the product becomes Photoshop-MCP-IMT + SKILLS.
• v1.0.0 · 2026-10-28 — every Photoshop UI language (errors by number, fonts by PostScript name, actions without localized names), the Photoshop-MCP-IMT Bridge plugin, Apache-2.0.
• 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

Apache License 2.0 — © Immersive Media Technologies.

• Free to use, modify and distribute, commercial use included.
• Attribution is required. Every redistribution of this software or of a work derived from it must carry the notice from NOTICE: Photoshop-MCP-IMT by Immersive Media Technologies — https://github.com/Immersive-Media-Technologies.
• No warranty.

Third-party notices (upstream MIT code): THIRD-PARTY-NOTICES.md.