Photoshop-MCP-IMT
Provides Automation transport via AppleScript/osascript on macOS, enabling AI agents to control a running Adobe Photoshop application (documents, layers, text masks, selections, filters, export) on Apple's operating system.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Photoshop-MCP-IMT Select subject on the current layer, add a mask, and export a transparent PNG."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

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 theps_skilltool, 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.
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 keepps_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.
Photoshop-MCP-IMT (this repo) | alisaitteke/photoshop-mcp | mikechambers/adb-mcp | dcc-mcp/dcc-mcp-photoshop | |
Talks to Photoshop via | ExtendScript (osascript / COM) and a UXP panel plugin — chosen per call, UXP as fallback or first ( | ExtendScript via AppleScript / COM (we are a fork) | UXP plugin → separate WebSocket proxy (Python) → MCP server | UXP plugin → Rust broker ( |
When Photoshop is modal |
| 30 s timeout → | — | UXP only, so unaffected — but no ExtendScript DOM at all |
Vision: acting on what the agent sees | an image of the document after every step ( | preview image ( | document image; polygon / rectangle / ellipse selections by coordinates, Select Subject, mask from selection | export to a file; rectangle / ellipse selections by coordinates |
Tool surface | 135 tools registered, 10 visible ( | 118–122 tools, all visible ( | «a subset of functionality» per app, low-level tools (proof of concept) | 40+ typed tools in 8 skill packages |
Headless corner-pin |
| — | — | — |
Telemetry | none — analytics module is a no-op, feedback nudge removed, server sends nothing | anonymous analytics on by default (opt-out), product-feedback nudge via | — | — |
Undo | recipes = one history state (upstream); | recipes = one history state; | — | staged install with |
Install | one click: |
| Python 3 + Node + UXP Developer Tools + proxy process |
|
Verified on | Photoshop 2026 (27.9–27.10), macOS, UXP 9.4.1 — live sweep of every tool: 193 pass / 0 fail / 11 environment skips (2026-10-01); Windows 11 (ARM) + Photoshop 2026 — same sweep, 193 / 0 / 11 (2026-10-04) | Windows + macOS | Photoshop 26+, macOS + Windows | Windows, Linux, macOS |
UI language | every UI language Photoshop ships — errors classified by error numbers, not localized messages; the Background layer, fonts (PostScript name) and actions found without localized names; verified live | |||
License | Apache-2.0 for our work (attribution through | MIT | MIT | MIT |
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.
Related MCP server: Illustrator AI MCP Server
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}):
| the tools, the order of work (state → backup → operate → verify by values, then by frame), addressing (active document and layer, the Background layer by flag, coordinates, selections as state, localized Photoshop, modal Photoshop) and a table of what scripts cannot do in Photoshop with the reference for each. |
| Generative Fill / Expand / Remove, Generate Image and Background, the partner models (Gemini, FLUX, GPT Image) and what each costs, reference images, Prompt to edit, Markup, Enhance Detail — what is scripted and what stays in the UI. |
| the Remove tool (credit-free) and Find distractions, Harmonize, Generative Upscale (Firefly, Topaz), AI Sharpen / Denoise, Neural Filters through the UXP bridge. |
| selection and mask operations, Select Subject, the remove-background recipe, selection shape as a prompt, Quick Mask strength, Sky Replacement. |
| frequency separation, dodge & burn, portrait enhancement, curves, LUTs and grades, layer styles, type — which recipe does what and how to hand the brush work to the user. |
| CSV → cards, watermarks, mockups, social variants, carousels, artboards, web export — inputs, outputs and where the files land. |
| the AI Assistant (Photoshop Beta), Firefly Boards, Actions, and the hand-over pattern for UI-only steps. |
| eleven jobs that combine tools: product on a new background, a billboard mockup in perspective, portrait retouch, a social set from one layout, restoring a photo, a composite that matches light. |
| modal Photoshop and |
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:
Client | Route | What you need |
| download | nothing else: Claude Desktop brings its own Node.js |
| Add to Cursor — one click: Cursor opens and writes the config (or put the snippet below into | Node.js 18+ ( |
| Settings → Customizations → Installed MCP Servers → View raw config (or type | Node.js 18+ |
| one command on the Photoshop machine — | Node.js 18+ and a tunnel tool: |
Any MCP client with a JSON config | the snippet below in its | 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
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.shThe 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
.mcpbhas 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 asinstall.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
.ccxas 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.
Variable | Default | Meaning |
| off |
|
| off |
|
| off |
|
|
| shared secret the plugin must send ( |
|
| bridge port |
|
| ExtendScript timeout for read-only tools (fast fallback to UXP when Photoshop is modal) |
|
| ExtendScript timeout for everything else; |
| auto-detect | path to the Photoshop app / executable |
|
| 0 debug · 1 info · 2 warn · 3 error (stderr) |
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:
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.UXP Developer Tools → Add Plugin →
uxp-plugin/manifest.json→ Load.Manual layout into Adobe's UXP plugin folder plus one entry in
PluginsInfo/v1/PS.json— exact paths and the JSON line indocs/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:
Tool | What it does |
| categories with counts and operation names; with a category — every operation and its parameters |
| run any registered operation by name ( |
| several operations in order, one result per op, stops at the first error ( |
| document and layer state (ExtendScript, 8 s timeout, UXP fallback) |
| save (PSD / in place) and a PNG of the current state for the agent to look at — both with UXP fallback |
| arbitrary ExtendScript ( |
| the 16 recipes (remove background, enhance portrait, frequency separation, social variants, CSV → cards, watermark, mockup …) |
| the Photoshop agent skill: the router, or one reference by name ( |
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_pingnever 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_documentover 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.1only 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-imtlike the npm package; tool counts corrected (10-tool facade withps_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.ps1that 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.
Available Tools
135 toolsphotoshop_adjust_brightness_contrastB
Adjust brightness and contrast of the active layer.
Users often say: fix exposure, add contrast, brighten, darken.
Inputs: contrast (required), brightness (required), document_id.
photoshop_adjust_curvesA
Create a Curves adjustment layer on the active document.
Users often say: make it pop, S-curve, fix flat image, auto tone, improve contrast.
Use when: global tonal correction via a non-destructive Curves adjustment layer. Do NOT use when: stylistic cinematic grade — use photoshop_recipe_apply_color_grade.
Returns: JSON { ok, summary, details: { layer_name, preset } }. Preconditions: active document. Side effects: adds Curves adjustment layer.
Inputs: preset, document_id.
photoshop_adjust_exposureA
Create an Exposure adjustment layer (stops, offset, gamma correction).
Users often say: fix underexposed photo, brighten by a stop, gamma fix.
Returns: JSON { ok, summary, details: { layer_name, exposure, offset, gamma } }. Preconditions: active document. Side effects: adds an Exposure adjustment layer.
Inputs: gamma, offset, exposure, document_id.
photoshop_adjust_hue_saturationC
Adjust hue, saturation, and lightness of the active layer
Inputs: hue (required), lightness (required), saturation (required), document_id.
photoshop_adjust_vibranceA
Create a Vibrance adjustment layer. Vibrance boosts muted colors while protecting skin tones.
Users often say: make colors pop (safely), boost saturation without clown look.
Returns: JSON { ok, summary, details: { layer_name, vibrance, saturation } }. Preconditions: active document. Side effects: adds a Vibrance adjustment layer.
Inputs: vibrance, saturation, document_id.
photoshop_apply_gaussian_blurA
Apply Gaussian Blur filter to the active layer
Inputs: radius (required), document_id.
photoshop_apply_gradient_mapA
Create a Gradient Map adjustment layer (black→white by default) for duotone/B&W tonal remapping.
Users often say: duotone look, gradient map B&W, remap tones.
Returns: JSON { ok, summary, details: { layer_name, reverse } }. Preconditions: active document. Side effects: adds a Gradient Map adjustment layer.
Inputs: reverse, document_id.
photoshop_apply_gradient_maskA
Apply a linear black-to-white gradient on the active layer mask channel (fade/blend).
Users often say: fade into background, gradient mask, blend subject, soft edge fade.
This paints on an existing layer mask — not a Gradient Fill layer. Use when: softening edges or fading a layer into the background through its mask. Do NOT use when: subject is not isolated — use photoshop_recipe_remove_background or photoshop_create_layer_mask first.
Returns: JSON { ok, summary, details: { applied, direction, angle, mask_auto_created? } }. Preconditions: active document and active layer. Creates a reveal-all mask if none exists. Side effects: modifies layer mask pixels; two history steps when mask is auto-created.
Inputs: end_pct, angle_deg, direction, start_pct, +1 more.
photoshop_apply_high_passA
Apply the High Pass filter to the active raster layer — edge/detail extraction for sharpening workflows or frequency separation prep.
Users often say: high pass filter, sharpen edges, extract details, frequency separation high layer.
Use when: sharpening via overlay blend, detail extraction, or prepping a high-frequency layer. Do NOT use on text, Smart Objects, or the Background layer — rasterize or convert first (photoshop_rasterize_layer).
Returns: JSON { ok, summary, details: { filter, radius, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.
Inputs: radius (required), document_id.
photoshop_apply_layer_maskB
Apply (merge) the layer mask to the layer
Inputs: document_id.
photoshop_apply_layer_styleA
Apply a layer style (drop shadow, outer glow, stroke, bevel & emboss) to the active layer via Action Manager layer effects.
Users often say: add shadow, glow effect, outline this layer, stroke, bevel, 3D button look, katmana gölge ver.
Use when: quick presentational effects on the active layer (cards, buttons, mockups, text pop). Do NOT use when: you need full custom layer-effects control — use photoshop_execute_script with a custom layerEffects descriptor.
Returns: JSON { ok, summary, details: { style, layer_name } }.
Preconditions: active document with an active pixel/text layer. Side effects: sets the chosen effect on the active layer. Drop shadow uses the given angle (Use Global Light is off).
Inputs: red, blue, size, angle, +5 more.
photoshop_apply_lutA
Apply a Color Lookup (3D LUT) adjustment layer for cinematic color grading. Accepts a built-in LUT name (e.g. "Crisp_Warm.3dl", "Kodak 5218 Fuji 3510.3dl", "Moonlight.3dl") or an absolute path to a .cube/.3dl/.look file.
Users often say: cinematic grade, film look, teal and orange, apply LUT, sinematik renk.
Use when: stylistic non-destructive color grade in one step. Do NOT use when: basic tonal fixes — use photoshop_adjust_curves or photoshop_auto_levels.
Returns: JSON { ok, summary, details: { layer_name, lut, lut_source } }. Preconditions: active document. Side effects: adds a Color Lookup adjustment layer.
Inputs: lut (required), document_id.
photoshop_apply_motion_blurB
Apply Motion Blur filter to the active layer
Inputs: angle (required), radius (required), document_id.
photoshop_apply_noiseB
Apply Add Noise filter to the active layer
Inputs: amount (required), document_id, distribution, monochromatic.
photoshop_apply_photo_filterA
Create a Photo Filter adjustment layer (warming/cooling/custom tint with density control).
Users often say: warm it up, cool it down, add a tint, golden hour look.
Returns: JSON { ok, summary, details: { layer_name, color, density } }. Preconditions: active document. Side effects: adds a Photo Filter adjustment layer.
Inputs: red, blue, green, density, +2 more.
photoshop_apply_sharpenC
Apply Unsharp Mask (sharpen) filter to the active layer
Inputs: amount (required), radius (required), threshold, document_id.
photoshop_apply_smart_blurA
Apply the Smart Blur filter to the active raster layer — edge-preserving blur for smoothing skin or simplifying backgrounds.
Users often say: smart blur, edge-preserving blur, smooth skin blur, blur but keep edges.
Use when: subtle smoothing that respects edges (portraits, product cleanup). Do NOT use on text, Smart Objects, or the Background layer — rasterize first (photoshop_rasterize_layer). Do NOT use when: uniform blur is enough — use photoshop_apply_gaussian_blur.
Returns: JSON { ok, summary, details: { filter, radius, threshold, mode, quality, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.
Inputs: radius (required), threshold (required), mode, quality, +1 more.
photoshop_auto_contrastB
Apply auto contrast adjustment to the active layer
Inputs: document_id.
photoshop_auto_levelsB
Apply auto levels adjustment to the active layer.
Users often say: fix flat image, auto tone, make it pop (mild).
Inputs: document_id.
photoshop_close_documentA
Close a Photoshop document tab. Defaults to the active document; pass document_id to close a specific open file.
Use when: the user is done with a file, or when cleaning up extra open tabs after photoshop_list_documents. Do NOT use when: you only need to switch tabs — use photoshop_set_active_document.
Returns: confirmation that the document closed. Preconditions: target document is open. Side effects: closes that tab; save=true writes unsaved changes first.
Inputs: save, document_id.
photoshop_content_aware_fillA
Fill the current pixel selection using Content-Aware Fill.
Users often say: remove distraction, erase object, content aware fill, inpaint selection.
Use when: a rectangular or other selection covers the area to remove/replace. Do NOT use when: no selection exists — use photoshop_select_rectangle first. Do NOT use when: generative remove is requested — not scriptable; use this fill or manual touch-up.
Returns: JSON { ok, summary, details: { filled } }. Preconditions: active document and active pixel selection. Side effects: modifies pixels inside selection; deselects afterward.
Inputs: document_id.
photoshop_contract_selectionA
Contract (shrink) the active pixel selection inward by a pixel amount.
Use when: tightening a loose selection or trimming halo after expand. Do NOT use when: no selection exists — create one first.
Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.
Inputs: pixels (required), document_id.
photoshop_convert_to_smart_objectA
Convert the active layer (or a named layer) to an embedded Smart Object.
Users often say: convert to smart object, make smart layer, embed layer.
Use when: non-destructive transforms/filters are needed on a raster or shape layer. Do NOT use when: the layer is already a Smart Object — returns success with already_smart_object. Do NOT use on background layers — unlock or duplicate first.
Returns: JSON { ok, summary, details: { layer_name, kind, already_smart_object? } }. Preconditions: active document; target layer must be selected or named. Side effects: one history step.
Inputs: layer_name, document_id.
photoshop_create_artboardA
Create a Photoshop artboard (AM artboardSection) at an explicit origin or placed to the right of existing artboards.
Users often say: add iPhone frame, new artboard, multi-screen layout, 画板 ekle.
Use when: building a multi-device / multi-screen document. First artboard converts a regular canvas into an artboard document. Do NOT use when: you only need a new document tab — use photoshop_create_document.
Returns: JSON { ok, summary, details: { artboard, count } }. Preconditions: active document. Side effects: adds an artboard layer group.
Inputs: width (required), height (required), top, left, +2 more.
photoshop_create_clipping_maskA
Create a clipping mask on the active layer (or a named layer).
Users often say: clip to layer below, clipping mask, clip this layer, mask to shape below.
Use when: the active layer should be visible only where the layer directly below it has opaque pixels. Do NOT use when: the layer is already clipped — returns success with already_clipping. Do NOT use when: the layer is the bottom-most layer — there is no base layer to clip into.
Returns: JSON { ok, summary, details: { layer_name, is_clipping, already_clipping? } }. Preconditions: active document; target layer must sit directly above the base layer below it in the same group/stack. Side effects: one history step (groupEvent).
Inputs: layer_name, document_id.
photoshop_create_documentA
Create a new empty Photoshop document with specified dimensions and color mode.
Use when: starting a design from scratch or no document is open. Do NOT use when: opening an existing file — use photoshop_open_image.
Returns: created document id and name. Preconditions: none. Side effects: creates a new document and makes it active.
Inputs: width (required), height (required), colorMode, resolution, +1 more.
photoshop_create_layerA
Create a new empty layer above the active layer.
Use when: user needs a blank layer for painting, fills, or stacking content. Do NOT use when: adding text — use photoshop_create_text_layer.
Returns: created layer name and context. Preconditions: active document. Side effects: adds layer to history.
Inputs: name, document_id.
photoshop_create_layer_maskA
Create a layer mask on the active layer from the current selection (reveal selection).
Users often say: mask this, hide the background, non-destructive cutout (after selection).
Use when: non-destructive hide/show after a selection exists. Do NOT use when: no selection exists — create selection first or use remove_background recipe.
Returns: maskCreated confirmation. Preconditions: active document and active selection. Side effects: adds mask to active layer.
Inputs: document_id.
photoshop_create_smart_object_via_copyA
Create an independent Smart Object via Copy — unlinked duplicate with its own embedded contents.
Users often say: new smart object via copy, independent smart copy, duplicate smart object separately.
Use when: you need a second Smart Object that does not share embedded data with the original. Do NOT use when: you want linked instances — use photoshop_duplicate_layer (Layer via Copy).
Returns: JSON { ok, summary, details: { source_layer_name, new_layer_name, kind } }. Preconditions: Smart Object layer active or named. Side effects: adds a new Smart Object layer.
Inputs: layer_name, document_id.
photoshop_create_text_layerA
Create a text layer with content, position, font, and optional typography (tracking, leading, paragraph box, alignment, color).
Users often say: add title, letter spacing, line height, text box, 字间距, 行高, 排版.
Use when: adding labels, titles, or typography to the design. Do NOT use when: editing existing text — use photoshop_update_text_content / photoshop_set_text_style. Do NOT use execute_script for tracking/leading/box — pass those fields here.
Returns: JSON { ok, summary, details: { layerName, text, style, context } }. Use photoshop_list_fonts to discover font names; photoshop_set_text_font / photoshop_set_text_style to change later. Preconditions: active document. Side effects: adds text layer.
Inputs: text (required), x, y, red, +12 more.
photoshop_crop_documentB
Crop the document to specified bounds
Inputs: top (required), left (required), right (required), bottom (required), +1 more.
photoshop_delete_layerB
Delete the active layer
Inputs: document_id.
photoshop_delete_layer_maskA
Delete the layer mask from active layer
Inputs: document_id.
photoshop_desaturateA
Desaturate the active layer (convert to grayscale)
Inputs: document_id.
photoshop_deselectB
Deselect all selections
Inputs: document_id.
photoshop_distort_layerA
Corner-pin / perspective distort of a layer: map its bounding box to four target corners (absolute document pixels, clockwise from top-left). Headless replacement for Free Transform → Distort / Perspective Warp (which are modal and cannot be scripted). Implemented as a custom warp mesh fitted to the homography — exact on pixel layers; a Smart Object must be rasterized first (rasterize:true, destructive — duplicate it before if the original matters). Read the current bounds with get_layers / get_state, then compute the target corners. Save a copy of the document before (save_document).
Inputs: corners (required), mode, layer, rasterize, +2 more.
photoshop_duplicate_layerA
Duplicate the active layer. The duplicate becomes the active layer; returns its name and, when available, its layer id.
Inputs: newName, document_id.
photoshop_edit_smart_object_contentsA
Open a Smart Object for editing (double-click / Edit Contents). The embedded .psb becomes the active document until you save and close it.
Users often say: edit smart object, open embedded file, double-click smart layer.
Use when: modifying pixels inside an embedded Smart Object non-destructively. Do NOT use when: replacing the whole asset — use photoshop_replace_smart_object_contents.
Returns: JSON { ok, summary, details: { parent_document, embedded_document, layer_name } }. Preconditions: Smart Object layer active or named. Side effects: active document switches to the embedded .psb — save/close it to return to the parent document.
Inputs: layer_name, document_id.
photoshop_execute_scriptA
Execute custom ExtendScript (JSX) code inside Photoshop (advanced escape hatch).
Use when: no existing tool covers the operation and you can write safe JSX. Do NOT use when: a recipe or atomic tool exists — prefer photoshop_recipe_* or photoshop_* tools.
Returns: script return value serialized as text/JSON.
IMPORTANT: Your code runs inside a wrapping IIFE. Use an explicit return to pass data back — a bare trailing expression returns undefined. Example: return { ok: true }; Objects are serialized with toSource() and parsed automatically on macOS and Windows.
Long scripts: pass timeout_ms (up to 600000) so the default 30s budget does not kill the job.
Preconditions: valid ExtendScript; active document if script expects one. Side effects: depends on code.
Inputs: code (required), timeout_ms, document_id.
photoshop_expand_selectionA
Expand the active pixel selection outward by a pixel amount.
Use when: growing a tight subject selection or adding padding before feather/fill. Do NOT use when: no selection exists — create one first.
Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.
Inputs: pixels (required), document_id.
photoshop_export_artboardsA
Export every artboard in the active document to a folder (duplicate + crop to artboardRect, then PNG/JPEG/WebP/AVIF).
Users often say: export all artboards, multi-screen PNG, 画板 çıktısı.
Use when: delivering one file per artboard. Long jobs use a 600s script timeout. Do NOT use when: exporting the whole canvas once — use photoshop_export_as.
Returns: JSON { ok, summary, details: { exported[], failed[], folder } }. Preconditions: document with at least one artboard. Side effects: writes files; does not modify the original.
Inputs: folder (required), format, quality, document_id.
photoshop_export_asA
Export a copy of the active document as PNG, JPEG, WebP or AVIF without changing the open document. WebP/AVIF require Photoshop 23.2+/recent builds and return a clear error when unsupported.
Users often say: export for web, save as webp, quick export png.
Use when: web-ready delivery formats are needed (WebP/AVIF/modern pipelines), or one artboard from a multi-screen file. Do NOT use when: saving the working document itself — use photoshop_save_document. For every artboard at once use photoshop_export_artboards.
Returns: JSON { ok, summary, details: { path, format, method, artboard_id? } }. Preconditions: active document. Side effects: writes one file to path. Optional artboard_id exports only that board (duplicate + crop).
Inputs: path (required), format, quality, artboard_id, +1 more.
photoshop_feather_selectionA
Feather (soften) the edges of the active pixel selection.
Use when: soft transitions before fill, mask, or delete operations. Do NOT use when: a hard edge is required or no selection exists.
Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection edges.
Inputs: pixels (required), document_id.
photoshop_fill_layerB
Fill the active layer with a color
Inputs: red (required), blue (required), green (required), document_id.
photoshop_fit_layer_to_documentB
Scale the active layer to fit the document canvas while maintaining aspect ratio
Inputs: document_id, fillDocument.
photoshop_flatten_imageC
Flatten all layers into a single background layer
Inputs: document_id.
photoshop_generate_from_datasetsA
Batch-export the active document once per data set: applies each data set, saves a copy, moves on. "Mail merge for images".
Users often say: generate all variants, batch personalize, render every row.
Use when: data sets are already imported (photoshop_import_datasets) and you want one file per row.
Returns: JSON { ok, summary, details: { exported, skipped, output_paths } }. Preconditions: active document with data sets. Side effects: writes files to output_dir.
Inputs: output_dir (required), format, document_id, dataset_names.
photoshop_generate_imageA
Photoshop Generate Image (Firefly ImageGen): create an image from a text prompt.
Use when: the user asks for ImageGen, text-to-image, or a new picture from a description.
Returns: { ok, summary, details }. Preconditions: generative_fill capability; Adobe generative credits.
Inputs: prompt (required), width, height, document_id.
photoshop_generative_expandA
Extend the canvas beyond its edges using Generative Expand (Firefly): enlarges the canvas by amount_px on the chosen side(s) and fills the new area with Generative Fill (outpainting).
Use when: outpainting, extending background, or expanding composition.
Returns: { ok, summary, details: { direction, prompt, wait } }. Preconditions: active document; generative_fill capability. Side effects: enlarges canvas with generated content.
Inputs: prompt, amount_px, direction, document_id.
photoshop_generative_fillA
Fill the current selection using Adobe Generative Fill (Firefly) with a text prompt.
Use when: adding or replacing content inside a selection with generative AI. Do NOT use when: no selection exists — create one first or use photoshop_select_subject. Do NOT use when: Photoshop version lacks generative_fill — check photoshop_get_capabilities.
Returns: { ok, summary, details: { action_id, prompt, wait } }. Preconditions: PS 24+ with generative credits; active pixel selection. Side effects: modifies pixels in selection; may consume Adobe generative credits.
Inputs: prompt (required), document_id.
photoshop_generative_removeA
Remove content using the AI Remove tool (or generative fill fallback) on the current selection.
Use when: erasing distractions, people, or objects with generative AI. Do NOT use when: generative unavailable — fallback to photoshop_recipe_remove_distraction.
Returns: { ok, summary, details }. Preconditions: selection or auto_select_subject; generative_fill capability. Side effects: inpaints selected region; consumes generative credits when cloud-backed.
Inputs: feather_px, document_id, auto_select_subject.
photoshop_generative_upscaleA
Upscale the active document using Generative Upscale (PS 27+).
Use when: increasing resolution with AI detail recovery. Do NOT use when: generative_upscale flag is false — use photoshop_resize_image.
Returns: { ok, summary, details } — or generative_timeout while Photoshop renders behind its progress dialog (1–3 min): poll photoshop_get_state; the result opens as a NEW active document named "… Firefly Upscaler Nx". Preconditions: generative_upscale capability; signed-in Adobe account.
Inputs: document_id, target_scale.
photoshop_get_capabilitiesA
Return version-aware feature flags for the installed Photoshop (Select Subject v2, Generative Fill, etc.).
Use when: once per session before suggesting AI-powered features or gated recipes. Do NOT use when: Photoshop version is already known from photoshop_get_version.
Returns: JSON { version, features: { select_subject_v2, generative_fill, ... } }. Preconditions: none. Side effects: none.
Inputs: no named parameters.
photoshop_get_document_infoC
Get information about the active Photoshop document
Inputs: document_id.
photoshop_get_historyC
Get the history states of the active document
Inputs: document_id.
photoshop_get_layersA
List all layers in the active document with kind, visibility, and opacity.
Use when: choosing a layer to edit, debugging structure, or after organize_layers. Do NOT use when: only session summary is needed — use photoshop_get_state (lighter).
Returns: layerCount, layers array (LayerSets include is_artboard), context. Preconditions: active document. Side effects: none.
Inputs: document_id.
photoshop_get_previewA
Export the active document as a base64 JPEG preview for visual verification.
Use when: after visual edits to confirm result before reporting success to the user. Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper).
Returns: MCP image content block (JPEG) plus metadata text. Preconditions: active document required. Side effects: creates and deletes a temp file; does not modify the document.
Inputs: quality, document_id, max_dimension_px.
photoshop_get_selection_boundsA
Read the active pixel selection bounds in document pixels (read-only).
Use when: verifying selection exists and its size/position before mask, fill, or recipe steps. Do NOT use when: creating or modifying a selection — use photoshop_select_rectangle or photoshop_select_subject.
Returns: JSON { ok, summary, details: { has_selection, bounds?, context } }. Preconditions: active document. Side effects: none.
Inputs: document_id.
photoshop_get_stateA
Return a cheap read-only snapshot of Photoshop session state (active document, layer, selection).
Use when: before any tool that needs an active document/layer, or after an error to recover context. Do NOT use when: you only need a visual preview — use photoshop_get_preview instead.
Returns: JSON with hasDocument, openDocumentCount, document.id/name/dimensions/colorMode/artboards, activeLayer, activeArtboard, hasSelection. Capture document.id and pass it as document_id on later mutating calls. Artboard ids come from document.artboards[].id. When openDocumentCount > 1, call photoshop_list_documents before acting across tabs. Preconditions: none (safe on empty session). Side effects: none.
Inputs: document_id.
photoshop_get_versionA
Return the detected Photoshop version string.
Use when: user asks about compatibility or before version-gated features. Do NOT use when: you need feature flags — prefer photoshop_get_capabilities.
Returns: version string. Preconditions: none. Side effects: none.
Inputs: no named parameters.
photoshop_image_stackA
Load 2+ image files into one document, convert to a smart object and apply a stack mode (mean/median/max/min/...). Classic "remove tourists from N shots" or noise reduction — no generative AI involved.
Users often say: remove tourists, median stack, average these photos, noise stack, turistleri sil.
Use when: the user has multiple aligned shots of the same scene and wants a statistical blend. Do NOT use when: removing a single object from one photo — use photoshop_generative_remove or photoshop_content_aware_fill.
Returns: JSON { ok, summary, details: { file_count, mode, layer_name } }. Preconditions: 2+ existing image files. Side effects: opens the files; the stacked result becomes the active document.
Inputs: files (required), mode, document_id.
photoshop_import_datasetsA
Import a Photoshop variables/data-sets XML file into the active document (the same file Image > Variables > Data Sets > Import accepts).
Users often say: load data sets, import variables XML, data-driven graphics.
Use when: the template PSD already has variable-bound layers and you want to load rows from an XML file. Do NOT use when: generating a batch from a CSV directly — use photoshop_recipe_csv_to_cards.
Returns: JSON { ok, summary, details: { count, datasets } }. Preconditions: active document with variables defined (Image > Variables > Define).
Inputs: xml_path (required), document_id.
photoshop_invertA
Invert colors of the active layer
Inputs: document_id.
photoshop_invert_selectionB
Invert the current selection
Inputs: document_id.
photoshop_list_artboardsA
List artboards in the active document with id, name, pixel bounds, and which one contains the active layer.
Users often say: artboards, 画板, multi-screen, iPhone and iPad frames, device layouts.
Use when: the document is an artboard file (UI/multi-screen) and you need artboard_id before export or edits. Do NOT use when: listing open document tabs — use photoshop_list_documents.
Returns: JSON { ok, summary, details: { count, artboards[] } }. Empty list if the document has no artboards. Preconditions: active document. Side effects: none.
Inputs: document_id.
photoshop_list_datasetsA
List the data sets defined on the active document (Image > Variables > Data Sets).
Use when: before applying data sets or debugging a data-driven template.
Returns: JSON { ok, summary, details: { datasets, active, count } }. Preconditions: active document with variables/data sets defined.
Inputs: document_id.
photoshop_list_documentsA
List every open Photoshop document with id, dimensions, saved flag, artboard_count, and which tab is active.
Use when: multiple documents are open and you need document_id before switching tabs, previewing, or closing a specific file. Do NOT use when: you only need the active document — use photoshop_get_document_info or photoshop_get_state.
Returns: JSON { ok, summary, details: { count, documents[] (id, name, width, height, saved, artboard_count, is_active), active_document_id, context } }. Preconditions: none (safe when zero documents open). Side effects: briefly activates each tab to read artboard_count, then restores the original active document.
Inputs: no named parameters.
photoshop_list_fontsA
List installed fonts available to Photoshop.
Use when: choosing a font for photoshop_create_text_layer or photoshop_set_text_font. TextItem.font requires the PostScript name — use postScriptName from results. It is the same in every Photoshop UI language, while name/family can be localized (e.g. CJK fonts in a Japanese UI); set/create tools also accept a display name as a fallback.
Returns: fonts array ({ name, postScriptName, family, style }), total count, truncated flag. First call may be slow (app.fonts.length can exceed 1000). Side effects: none.
Inputs: limit, query, document_id.
photoshop_merge_visible_layersB
Merge all visible layers into one
Inputs: document_id.
photoshop_move_layerA
Move the active layer by specified offset
Inputs: deltaX (required), deltaY (required), document_id.
photoshop_move_layer_downA
Move the active layer down one position in the layer stack
Inputs: document_id.
photoshop_move_layer_to_bottomA
Move the active layer to the bottom of the layer stack
Inputs: document_id.
photoshop_move_layer_to_positionC
Move the active layer relative to another layer
Inputs: position (required), targetLayerName (required), document_id.
photoshop_move_layer_to_topA
Move the active layer to the top of the layer stack
Inputs: document_id.
photoshop_move_layer_upA
Move the active layer up one position in the layer stack
Inputs: document_id.
photoshop_neural_filterA
Apply a Photoshop Neural Filter via the companion UXP bridge plugin.
Use when: skin smoothing, harmonize composite layers, depth blur, super zoom, or colorizing B&W photos. Do NOT use when: uxp_bridge_reachable is false — install uxp-plugin per docs/development.md.
Returns: { ok, summary, details }. Preconditions: UXP bridge plugin running in Photoshop; PS 22+.
Inputs: filter (required), blur, smoothness, document_id, +1 more.
photoshop_open_imageA
Open an image file as a new Photoshop document.
Use when: user provides a file path to edit or no document is open yet. Do NOT use when: adding to an existing composite — use photoshop_place_image.
Returns: document id, name, width, height. Preconditions: file must exist on disk. Side effects: opens document as active.
Inputs: filePath (required), document_id.
photoshop_pingA
Verify that the Photoshop scripting engine can run a script.
Use when: once at session start, and after extendscript_timeout until this call succeeds. Do NOT use when: on every tool call — after a successful ping, use photoshop_get_state. Do not call get_state or get_layers while this ping is still failing.
Returns: "Successfully connected to Photoshop" only after a short script runs inside Photoshop. While a previous script is still running, returns extendscript_timeout — retry photoshop_ping. If that timeout happens while the OS drive has under 10 GB free, returns scratch_disk_full instead: free space on the scratch disk and restart Photoshop. If Photoshop is not installed or not running, returns a failure string and does not launch the app. Preconditions: none. Side effects: may trigger Photoshop detection. Does not launch Photoshop.
Inputs: no named parameters.
photoshop_place_imageA
Place an external image file as a new layer in the active document.
x/y are absolute canvas coordinates for the placed layer's top-left bound in pixels (0,0 = document top-left). They are NOT an offset from Photoshop's default centered Place.
Use when: compositing assets into an open document at a known position. Do NOT use when: opening a file as a new document — use photoshop_open_image.
Returns: placed layer name, bounds, and position.semantics = absolute_top_left. Preconditions: active document; file must exist. Side effects: adds a new layer.
Inputs: filePath (required), x, y, document_id.
photoshop_play_actionA
Play a recorded action from the Actions palette.
Names are the ones the Actions panel shows, in the Photoshop UI language: the built-in set is "Default Actions" only in English Photoshop. When the set or the action does not exist, the error (code invalid_arguments) lists the names this Photoshop has; retry with one of them.
Inputs: actionName (required), actionSetName (required), document_id.
photoshop_rasterize_layerA
Rasterize the active layer (convert text/smart object to normal layer)
Inputs: document_id.
photoshop_recipe_apply_color_gradeA
Apply a named color grading preset as a non-destructive layer group (Hue/Saturation adjustment + brightness/contrast tweak).
Users often say: cinematic look, teal and orange, moody grade, color grade.
Use when: the user wants a quick stylistic look applied to the active document. Do NOT use when: the user wants subject-specific color edits (e.g. only the skin) — current recipe applies globally.
Returns: { ok, summary, details: { preset, group_name } }.
Preconditions: active document in RGB mode. CMYK/Grayscale return unsupported_color_mode. Side effects: adds one layer group with adjustment layers; one undo reverts.
Inputs: preset, document_id.
photoshop_recipe_batch_mockup_replaceA
Iterate a directory of asset images, replace the contents of the named Smart Object in the active mockup PSD for each asset, and export a flattened JPEG per variant. The mockup's perspective/warp on the Smart Object is preserved.
Use when: the user has a mockup PSD and wants to render it once per design asset (logos, screens, product photos). Do NOT use when: the asset is not a single layer (use photoshop_place_image manually) or when the active document has no Smart Object with the requested name.
Returns: { ok, summary, output_paths, details: { variants: [{ source_asset, output_path }] } }.
Preconditions: active document containing a Smart Object layer named exactly as requested; assets_dir must exist and be readable. Side effects: writes one JPEG per asset; the active mockup PSD ends up with the LAST asset placed.
Inputs: assets_dir (required), smart_object_layer_name (required), quality, document_id.
photoshop_recipe_batch_watermarkA
Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Replaces the clunky record-an-action + File > Automate > Batch workflow.
Use when: the user wants to watermark many photos at once (copyright text, studio logo). Do NOT use when: watermarking a single open document (use photoshop_create_text_layer / photoshop_place_image directly) or removing watermarks (not supported).
Returns: { ok, summary, output_paths, details: { processed, failed: [{ file, error }] } }. Files that fail are skipped, not fatal.
Preconditions: assets_dir exists; either text or logo_path given. No active document required. Side effects: writes one JPEG per source image; source files are never modified.
Inputs: assets_dir (required), text, opacity, quality, +6 more.
photoshop_recipe_csv_to_cardsA
Data-driven graphics batch: convert a CSV file into Photoshop data sets, apply each row to the active template document and export one image per row. "Mail merge for images" — name cards, badges, certificates, personalized banners.
Users often say: csv to images, batch name cards, personalized banners, generate badges from spreadsheet, sertifika bastır.
CSV rules: first row = variable names matching the variables defined in the template PSD (Image > Variables > Define). A cell holding an absolute path to an image file (.png/.jpg/.webp/.tif/.psd) is treated as a pixel-replacement variable.
Use when: the user has a template PSD with variable-bound layers and a CSV of rows. Do NOT use when: the document has no variables defined — define them in Photoshop first (Image > Variables > Define).
Returns: { ok, summary, details: { rows, exported, output_paths, xml_path } }.
Preconditions: active document with variable-bound layers; readable CSV file. Side effects: writes a temp variables XML and one output file per row into output_dir.
Inputs: csv_path (required), output_dir (required), format, document_id.
photoshop_recipe_dodge_burnA
One-shot dodge & burn setup: creates a 50% gray layer in Overlay or Soft Light mode for non-destructive light sculpting. Wrapped in a single undoable history step.
Users often say: dodge and burn, sculpt light, lighten face, darken shadows.
Use when: the user wants a ready-to-paint dodge & burn layer above the subject. Do NOT use when: the user wants automated retouch — this only sets up the paint layer; paint white (dodge) and black (burn) manually at low opacity. Do NOT use when: automated portrait smoothing is enough — use photoshop_recipe_enhance_portrait instead.
Returns: { ok, summary, undo_history_states_consumed, details: { layer_name, blend_mode } }.
Preconditions: active document with a raster-compatible active layer. Side effects: adds one "Dodge & Burn" layer above the active layer; one undo reverts.
Inputs: blend_mode, document_id.
photoshop_recipe_enhance_portraitA
Set up a non-destructive portrait enhancement: duplicates the active layer, builds a frequency separation pair (low/high) for skin smoothing, and adds an auto-tone curves adjustment on top. Grouped as "Enhance Portrait" and reversible with one undo.
Users often say: smooth skin, retouch portrait, fix blemishes, clean up face.
Use when: the user asks to "enhance", "retouch", "clean up" or "smooth" a portrait photo and is happy with a baseline that they can further tweak interactively. Do NOT use when: the user wants destructive, final edits — recommend manual frequency separation work via photoshop_recipe_frequency_separation instead so they can paint by hand.
Returns: { ok, summary, details: { intensity, radius_px, group_name } }.
Preconditions: active document with a NORMAL or background-converted raster layer. Side effects: appends one layer group of 2-3 layers above the active layer; original layer untouched.
Inputs: intensity, document_id, skin_smoothing, use_neural_skin.
photoshop_recipe_export_social_variantsA
Render one JPEG per requested social-media platform from the active document. Each variant is center-cropped/resized to the platform spec and saved to disk.
Use when: the user wants multi-platform deliverables in one shot. Do NOT use when: only one export is needed (use photoshop_recipe_prepare_for_web instead) or when platforms differ by content rather than crop (recipe does not change content, only frame).
Returns: { ok, summary, output_paths, details: { variants } }.
Preconditions: active document. Aspect ratios that differ from the source result in a center-crop (no padding). Side effects: writes one file per platform; source unchanged.
Inputs: quality, platforms, document_id.
photoshop_recipe_frequency_separationA
Build a frequency separation stack (Low + High) on top of the active layer for hands-on retouching. Does not apply any smoothing itself — the user paints into the layers afterwards.
Users often say: frequency separation, split texture and color, manual retouch setup.
Use when: the user explicitly wants frequency separation setup, typically for portrait or product retouching. Do NOT use when: the user wants a one-shot result without painting — use photoshop_recipe_enhance_portrait instead.
Returns: { ok, summary, details: { radius_px, group_name } }.
Preconditions: active document with a NORMAL raster active layer. Side effects: appends a "Frequency Separation" layer group with 2 prepared layers; one undo reverts everything.
Inputs: radius_px, document_id.
photoshop_recipe_gradient_fadeA
One-shot gradient fade on the active layer mask: creates a reveal-all mask if needed, then paints a linear black-to-white gradient for soft edge blending. Wrapped in a single undoable history step.
Users often say: fade into background, gradient mask, blend subject, soft edge fade, arka planı yumuşat.
This applies a linear gradient on the layer mask channel — not a Gradient Fill layer. Use when: the user wants the active layer to fade into the background or layers below through its mask. Do NOT use when: the subject is not isolated — use photoshop_recipe_remove_background first. Do NOT use when: replacing the sky with an external image — use photoshop_recipe_sky_blend.
Returns: { ok, summary, undo_history_states_consumed, details: { direction, start_pct, end_pct, mask_created, layer_name } }.
Preconditions: active document with an active layer. Side effects: creates or modifies the active layer mask; one undo reverts everything.
Inputs: end_pct, angle_deg, direction, start_pct, +1 more.
photoshop_recipe_organize_layersA
Tidy the active document's layer stack: rename layers using a consistent scheme and optionally auto-group them by kind. Never deletes, merges or rasterizes — visual output stays identical.
Use when: the user complains about layer mess ("layer 1 copy 2", "untitled 7") or asks for organization. Do NOT use when: the user wants smart, semantic naming based on layer content beyond text — recipe only summarizes text layers, not image content.
Returns: { ok, summary, details: { renamed_count, group_count } }.
Preconditions: active document. Side effects: renames top-level layers and (optionally) moves them into kind-grouped folders; one undo reverts everything.
Inputs: auto_group, document_id, naming_scheme.
photoshop_recipe_passport_photoA
Turn the active portrait into a passport/ID photo: removes the background via Select Subject, replaces it with white, crops around the subject with ICAO-style headroom, resizes to the exact official pixel size at 300 DPI, and exports a JPEG. Optionally also builds a 10×15 cm print sheet with multiple copies.
Use when: passport photo, visa photo, ID photo, vesikalık, biyometrik fotoğraf. Do NOT use when: the document has no clear single subject, or official compliance must be guaranteed — head-size rules are approximated from subject bounds (no face detection); official acceptance is NOT guaranteed.
Returns: { ok, summary, output_paths, details: { spec, width, height, sheet } }.
Preconditions: PS ≥ 23 (Select Subject v2); active document with a single-person portrait. Side effects: writes one JPEG (+ one sheet JPEG when make_sheet); source document is unchanged.
Inputs: spec, quality, make_sheet, document_id.
photoshop_recipe_prepare_for_webA
Export a web-optimized version of the active document: duplicate, convert to sRGB, downscale longest edge, sharpen for screen, save to disk. The source PSD stays untouched.
Use when: the user wants a shareable JPEG/PNG sized for the web from the current artwork. Do NOT use when: the user wants multiple platform-specific exports — use photoshop_recipe_export_social_variants. Do NOT call photoshop_save_document afterwards; this recipe already wrote the file.
Returns: { ok, summary, output_paths, undo_history_states_consumed }.
Preconditions: active document. Format is jpeg (default) or png. Side effects: writes one file to disk; the source document is unchanged.
Inputs: path, format, quality, document_id, +1 more.
photoshop_recipe_remove_backgroundA
THE tool for "remove background" / "arka planı sil" / cut out / isolate subject. Call this once and stop. Unlocks a locked Background layer, then runs Photoshop native Remove Background (Select Subject / Color Range only if native is unavailable). One undo reverts everything.
Use when: the user wants the background gone. Hair, busy interiors, product shots — still this tool. Do NOT rasterize, duplicate, hide layers, select_subject, create_layer_mask, or execute_script instead of this recipe.
Returns: { ok, summary, undo_history_states_consumed, details.method = remove_background | remove_layer_background | select_subject | color_range_fallback }.
Preconditions: an active document. Native Remove Background needs a current Photoshop; Select Subject fallback needs PS ≥ 23. Side effects: may unlock/rename the Background layer; attaches a pixel mask; no pixels destroyed; one undo reverts everything.
Inputs: feather_px, document_id, keep_shadow, use_generative.
photoshop_recipe_remove_distractionA
One-shot distraction removal: generative AI remove when available, else content-aware fill. Wrapped in a single undoable history step.
Users often say: remove that person, erase distraction, content aware remove, clone out object.
Use when: the user has selected the object or region to remove. Do NOT use when: no selection exists — use photoshop_select_rectangle or photoshop_select_subject first.
Returns: { ok, summary, undo_history_states_consumed, details }. Preconditions: active document with an active pixel selection. Side effects: fills/removes selected pixels; clears selection.
Inputs: feather_px, document_id, use_generative.
photoshop_recipe_sky_blendA
One-shot sky composite: places an external sky image, adds a layer mask, and applies a horizon gradient fade. Wrapped in a single undoable history step.
Users often say: replace sky, fix blown sky, better clouds, swap sky background.
Use when: the user provides a sky image path and native sky replacement is unavailable or manual blend is preferred. Do NOT use when: no sky_image_path is available — ask the user for an absolute file path first. Do NOT use when: fading the active subject layer only — use photoshop_recipe_gradient_fade.
Returns: { ok, summary, undo_history_states_consumed, details: { sky_image_path, layer_name, horizon_pct, feather_pct, direction } }.
Preconditions: active document; sky image file must exist on disk. Side effects: adds a placed sky layer with gradient mask; one undo reverts everything.
Inputs: sky_image_path (required), x, y, document_id, +3 more.
photoshop_recipe_split_carouselA
Split the active wide document into N equal vertical slices and export them as sequentially numbered files for a seamless Instagram/TikTok carousel (panorama swipe effect).
Use when: the user wants a seamless/swipeable carousel, split panorama, or multi-slide export of one wide design. Typical request: "split this into a 5-slide carousel". Do NOT use when: the user wants the same content reframed per platform (use photoshop_recipe_export_social_variants) or a single crop (use photoshop_crop_document).
Returns: { ok, summary, output_paths (in slide order), details: { slides, slice_width } }.
Preconditions: active document whose width is at least slides pixels.
Side effects: writes one file per slide; source document is unchanged.
Inputs: slides (required), format, quality, document_id, +2 more.
photoshop_redoA
Redo the previously undone operation(s) - equivalent to Ctrl/Cmd+Shift+Z
Inputs: steps, document_id.
photoshop_release_clipping_maskA
Release (remove) the clipping mask from the active layer (or a named layer).
Users often say: unclip, release clipping mask, remove clipping mask.
Use when: a clipped layer should become independent again. Do NOT use when: the layer is not clipped — returns not_clipping error.
Returns: JSON { ok, summary, details: { layer_name, is_clipping: false } }. Preconditions: active document; target layer must currently be a clipping mask (grouped). Side effects: sets layer.grouped = false; one history step.
Inputs: layer_name, document_id.
photoshop_rename_layerB
Rename the active layer
Inputs: name (required), document_id.
photoshop_replace_smart_object_contentsA
Replace the embedded contents of a Smart Object layer from an image file. Preserves transforms, warps, and Smart Filters on the layer.
Users often say: replace smart object, swap mockup screen, relink embedded file.
Use when: updating a mockup or template Smart Object with a new asset file. Do NOT use when: the target is not a Smart Object — convert first or use photoshop_place_image. Do NOT use for linked Smart Objects that need Relink to File — this replaces embedded contents.
Returns: JSON { ok, summary, details: { layer_name, file_path } }. Preconditions: Smart Object layer active or named; file_path must exist (absolute). Side effects: replaces embedded pixels.
Inputs: file_path (required), layer_name, document_id.
photoshop_resize_imageB
Resize the active image to specified dimensions
Inputs: width (required), height (required), document_id.
photoshop_rotate_layerB
Rotate the active layer
Inputs: degrees (required), document_id.
photoshop_save_documentA
Save the active document to disk in PSD, JPEG, or PNG format.
Use when: user requests export/save with a specific path and format. Do NOT use when: web-optimized resize+sharpen pipeline is needed — use photoshop_recipe_prepare_for_web.
Returns: confirmation with saved path and format. Preconditions: active document; path required. Side effects: writes file to disk.
Inputs: path (required), format, quality, document_id.
photoshop_save_selectionA
Save the active pixel selection to a new alpha channel.
Use when: preserving a selection for later reload or batch workflows. Do NOT use when: no selection exists — create one first.
Returns: JSON { ok, summary, details: { channel_name, context } }. Preconditions: active document and active pixel selection. Side effects: adds alpha channel.
Inputs: document_id, channel_name.
photoshop_scale_layerB
Scale the active layer by a percentage
Inputs: scalePercent (required), document_id, centerAnchor.
photoshop_select_allB
Select the entire document
Inputs: document_id.
photoshop_select_ellipseA
Create an elliptical pixel selection from a bounding box (anti-aliased).
Use when: circular or oval masks, vignettes, or radial edits inside a region. Do NOT use when: a rectangular region is enough — use photoshop_select_rectangle.
Returns: JSON { ok, summary, details: { shape, bounds?, context } }. Preconditions: active document; right > left and bottom > top. Side effects: replaces current selection.
Inputs: top (required), left (required), right (required), bottom (required), +1 more.
photoshop_select_layer_by_nameA
Select the active layer by exact name, including layers inside groups.
Use when: a transform or property tool must target a named layer (photoshop_scale_layer, etc.). Do NOT use when: the layer is already active — check photoshop_get_state first.
Returns: selected, layerName, kind, bounds (best-effort), context. First depth-first name match wins when duplicate names exist in different groups. Preconditions: active document. Side effects: changes active layer.
Inputs: name (required), document_id.
photoshop_select_rectangleA
Create a rectangular pixel selection from corner coordinates.
Use when: masking, cropping a region, or preparing for layer mask. Do NOT use when: subject isolation is needed — use photoshop_recipe_remove_background.
Returns: selection bounds [left, top, right, bottom]. Preconditions: active document. Side effects: replaces, adds, subtracts, or intersects the current selection. mode intersect/add/subtract uses Action Manager and does not depend on the SelectionType enum.
Inputs: top (required), left (required), right (required), bottom (required), +2 more.
photoshop_select_subjectA
Run Select Subject on the active layer (creates a pixel selection only, no mask).
Users often say: cut out, isolate subject, select person, select object.
Use when: you need a subject selection for masking, fill, or further edits. Do NOT use when: full background removal with mask — use photoshop_recipe_remove_background.
Returns: JSON { ok, summary, details: { selected, method } }. Preconditions: PS ≥ 23, active document, non-Background active layer with a recognizable subject. Side effects: replaces current selection.
Inputs: document_id, sample_all_layers.
photoshop_set_active_artboardA
Select an artboard layer group by artboard_id (preferred) or unique name so subsequent edits and Select All target that board.
Use when: switching between device frames in an artboard document. Do NOT use when: switching document tabs — use photoshop_set_active_document.
Returns: JSON { ok, summary, details: { artboard } }. Preconditions: target artboard exists (photoshop_list_artboards). Side effects: changes the active layer.
Inputs: name, artboard_id, document_id.
photoshop_set_active_documentA
Switch the active document tab by document_id (preferred), zero-based index, or name.
Use when: working across multiple open files and mutations must target a specific document. Do NOT use when: only one document is open — it is already active. Do NOT use document_name when duplicate names exist — use document_id from photoshop_list_documents.
Returns: JSON { ok, summary, details: { activated: { id, name }, context } }. Preconditions: target document must be open. Provide exactly one of document_id, index, or document_name. Side effects: changes active tab.
Inputs: index, document_id, document_name.
photoshop_set_layer_blend_modeA
Set the blend mode of the active layer.
COLOR is the Photoshop UI name (Colorize); it is mapped to ExtendScript BlendMode.COLORBLEND.
Inputs: blendMode (required), document_id.
photoshop_set_layer_lockedC
Lock or unlock the active layer
Inputs: locked (required), document_id.
photoshop_set_layer_opacityB
Set the opacity of the active layer
Inputs: opacity (required), document_id.
photoshop_set_layer_visibilityA
Show or hide the active layer
Inputs: visible (required), document_id.
photoshop_set_text_alignmentC
Set text alignment for active text layer
Inputs: alignment (required), document_id.
photoshop_set_text_colorB
Set color for active text layer
Inputs: red (required), blue (required), green (required), document_id.
photoshop_set_text_fontA
Set font family and size for active text layer.
Prefer the PostScript name (e.g. "ArialMT"): it is the same in every Photoshop UI language. A display name (e.g. "Arial") also works but can be localized; an exact PostScript match wins. Use photoshop_list_fonts to discover available fonts.
Inputs: fontName (required), fontSize, document_id.
photoshop_set_text_rangesA
Apply mixed fonts, sizes, and colors inside a single text layer (Action Manager textStyleRange).
Users often say: mixed type, two fonts in one line, multicolor text, 混排, 同一文字层.
Use when: one layer must contain more than one font or color. from is inclusive, to is exclusive (JavaScript slice / ExtendScript string indexes). Do NOT use when: the whole layer shares one style — use photoshop_set_text_style. Do NOT split into extra layers for mixed type unless this tool errors.
Returns: JSON { ok, summary, details: { style, ranges } }. Preconditions: active text layer. Unspecified gaps keep the layer default style. Side effects: rewrites character styles; restores tracking/leading/box afterward.
Inputs: ranges (required), document_id.
photoshop_set_text_styleA
Set layer-wide typography on the active text layer: tracking, leading, point vs paragraph box, alignment, font, size, color.
Users often say: letter spacing, tracking, line height, leading, text box width, paragraph text, 字间距, 行高, 文本框.
Use when: tightening/loosening type, setting line height, converting to a wrapped paragraph box, or batching several text attributes in one undo-friendly call. Do NOT use when: creating a new layer — pass the same fields on photoshop_create_text_layer. Do NOT use when: mixed fonts/colors inside one layer — use photoshop_set_text_ranges. Do NOT use execute_script for tracking/leading/box.
Returns: JSON { ok, summary, details: { style } }. Preconditions: active text layer. Side effects: mutates TextItem attributes.
Inputs: red, blue, kind, green, +9 more.
photoshop_sky_replacementA
Replace the sky using Photoshop native Sky Replacement when available.
Use when: a sky image path is provided and native AI sky replacement is supported. Fallback: photoshop_recipe_sky_blend for manual composite.
Returns: { ok, summary, details }. Preconditions: active document; optional sky_image_path for custom sky.
Inputs: document_id, sky_image_path.
photoshop_undoC
Undo the last operation(s) - equivalent to Ctrl/Cmd+Z
Inputs: steps, document_id.
photoshop_update_text_contentB
Update the text content of active text layer
Inputs: text (required), document_id.
ps_batchB
Run several operations in order. Each op: {operation, args}. Stops at the first error when stopOnError (default true). Returns one result per op.
Inputs: ops (required), stopOnError.
ps_catalogA
List Photoshop operations available through ps_do. Without category: categories with counts and operation names. With category: every operation of that category with its parameters. Call it before using an operation you have not used in this session.
Inputs: category.
ps_doA
Run one Photoshop operation by name (see ps_catalog), e.g. {"operation":"create_text_layer","args":{"text":"Hi"}}. Returns the operation result JSON. Prefer this over writing ExtendScript.
Inputs: operation (required), args.
ps_execute_scriptA
Run arbitrary ExtendScript in Photoshop and return its result. Use only when no ps_do operation covers the task. The code runs inside a function: use an explicit return to pass data back (objects are serialized); a bare trailing expression returns undefined.
Inputs: script (required).
ps_export_frameB
Export the current view of the active document as a PNG file to path (absolute). Use it for check frames the user will look at; name the file descriptively.
Inputs: path (required), quality.
ps_get_layersB
Layer tree of the active document (names, types, visibility, opacity, blend modes).
Inputs: no named parameters.
ps_get_stateA
Active document state: name, size, mode, layers summary, selection. Cheap — call it before and after edits instead of previews.
Inputs: no named parameters.
ps_recipeC
Run a multi-step recipe by name (ps_catalog category "recipe"): remove_background, enhance_portrait, apply_color_grade, prepare_for_web, sky_blend, …
Inputs: name (required), args.
ps_save_documentA
Save the active document (optionally to a new path / format). Save a copy before irreversible steps (flatten, merge, overwrite).
Inputs: path, format.
ps_skillA
The Photoshop agent skill. No doc: the router — tools, order of work, addressing, what scripts cannot do in Photoshop and which reference to read; read it at the start of any Photoshop task beyond a single read or edit. doc: one reference — Photoshop's generative tools (Generative Fill / Expand / Remove, Generate Image, partner models and credits, reference images), retouch (Remove tool, Harmonize, Generative Upscale, Neural Filters), selection and masking, colour and retouch recipes, batch and export, AI Assistant, multi-tool combos, gotchas.
Inputs: doc.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 135 tools
There are three parallel, overlapping surfaces: the photoshop_* family, the ps_* family (ps_get_state, ps_get_layers, ps_save_document, ps_export_frame, ps_execute_script) and the recipe/ps_do operation catalog, all covering the same operations. Recipes heavily overlap atomic tools (photoshop_recipe_gradient_fade vs photoshop_apply_gradient_mask vs photoshop_recipe_sky_blend; photoshop_recipe_remove_distraction vs photoshop_content_aware_fill vs photoshop_generative_remove). An agent faces real misselection risk despite detailed per-tool Do-Not-Use notes.
Within photoshop_ tools the verb_noun snake_case pattern is mostly held, but the presence of a second ps_* namespace (ps_catalog, ps_do, ps_batch, ps_skill, ps_recipe) alongside duplicate photoshop_ equivalents breaks predictability. Recipe tools use a recipe_ infix while sibling tools do not, and some tools drop the verb or use divergent verbs (photoshop_play_action, photoshop_image_stack, photoshop_sky_replacement).
135 tools is an extreme over-scoping for any single server; even with a broad Photoshop domain this far exceeds what an agent can reason about coherently. The parallel ps_*/photoshop_* namespaces and duplicated recipe/atomic layers compound the overload rather than adding distinct capability.
The surface is remarkably complete: documents, layers, selections/masks, text, smart objects, artboards, adjustments, generative AI, batch recipes, data-driven templates, export formats, and history/undo. Lifecycle coverage (create/open/save/close/export) and non-destructive workflows are all present with no obvious dead ends.
Maintenance
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceA professional MCP server that lets AI assistants directly control Adobe Photoshop for document creation, layer management, filters, adjustments, shapes, text, and design intelligence like palette generation and font pairing.322MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants control Adobe Illustrator locally—running ExtendScript, capturing canvas screenshots, exporting artwork, and optionally remembering techniques—all without network activity.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to programmatically control Adobe Photoshop through natural language, supporting design, image manipulation, and workflow automation.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants drive Adobe Photoshop on Windows through ExtendScript and COM automation, offering ~122 tools for documents, layers, text, filters, color, selections, masks, layout QA, and design systems.3MIT