photoshop-mcp

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.

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 }. Preconditions: generative_upscale capability; signed-in Adobe account.

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.

Read the active document id, name, size, resolution, and color mode. Does not change pixels or which tab is active. Use when: you need dimensions or color mode of the front document only. Do NOT use when: several documents are open and you need every tab — use photoshop_list_documents. Do NOT use when: you also need the active layer and selection — use photoshop_get_state. Returns: document context JSON. Preconditions: an open document. Side effects: none.

Read the history stack of the active document, including which state is current. Does not change pixels. Use when: deciding how many steps photoshop_undo or photoshop_redo should take. Do NOT use when: you want to change the document — use photoshop_undo or photoshop_redo. Returns: the history state list as text. Preconditions: active document. Side effects: none.

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.

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 (document size, color mode, up to 40 top-level layer names). Hosts that support MCP Apps also render ui://photoshop/preview. Preconditions: active document required. Side effects: creates and deletes a temp file; does not modify the document.

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.

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, documents[] (id, name, width, height, saved, is_active for every open file), document (id, name, path, saved, width, height, resolution, colorMode, bitsPerChannel, layerCount, layers[] up to 40 top-level layers, artboards), activeLayer, activeArtboard, hasSelection. path is omitted until the file has been saved. Capture document.id and pass it as document_id on later mutating calls. Artboard ids come from document.artboards[].id. Preconditions: none (safe on empty session). Side effects: none.

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.

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.

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

Install a font file for the current user and reload Photoshop's font list without quitting. Use when: photoshop_list_fonts does not include a font the user wants, and they already have the font file. Does not download fonts. file_path is an absolute path to a .ttf, .otf, .ttc, or .otc. macOS copies it to ~/Library/Fonts (Font Book, Current User). Windows installs it for the current user only, not for all users. If Photoshop is open, this calls app.refreshFonts() so the new PostScript names are listed immediately. Do not quit Photoshop. Fredoka Bold is the Bold named instance inside the variable font Fredoka[wdth,wght].ttf (SIL Open Font License, Google Fonts). Its PostScript name is Fredoka-Bold. There is no separate Fredoka Bold file in that release. Returns: installed_path, post_script_names, fonts_refreshed. Side effects: writes the current-user font folder and reloads the open app's font list.

Invert colors of the active layer

Invert the current pixel selection: selected pixels become unselected and the rest become selected. Layer pixels are unchanged. Use when: a selection exists and the user wants the opposite region. Do NOT use when: no selection exists — create one with photoshop_select_rectangle or photoshop_select_all. Do NOT use when: the layer colors should invert — use photoshop_invert. Returns: confirmation that the selection was inverted. Preconditions: active document and an existing selection. Side effects: selection only. Calling twice restores the original selection. Reversible with photoshop_undo.

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.

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.

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.

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, or pass display name to set/create tools (they resolve automatically). 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.

Merge every visible layer into one layer. Hidden layers stay in the stack. Use when: the user wants visible layers combined and hidden layers kept. Do NOT use when: every layer, including hidden ones, should become a single Background — use photoshop_flatten_image. Do NOT use when: only two named layers should combine — this always merges all visible layers. Returns: confirmation that visible layers were merged. Preconditions: active document with at least one visible layer. Side effects: destroys the separate visible layers in one history step. Reversible with photoshop_undo.

Move the active layer by specified offset

Move the active layer down one position in the layer stack

Move the active layer to the bottom of the layer stack

Reorder the active layer relative to a named layer. `position` is ABOVE, BELOW, TOP, or BOTTOM of `targetLayerName`. This changes stacking order, not canvas pixels. Use when: the active layer must sit above or below a specific other layer. Do NOT use when: it should go to the top or bottom of the whole stack — use photoshop_move_layer_to_top or photoshop_move_layer_to_bottom. Do NOT use when: it should move one step — use photoshop_move_layer_up or photoshop_move_layer_down. Do NOT use when: you mean a pixel offset on the canvas — use photoshop_move_layer. Returns: text confirmation of the new stack position. Preconditions: active document, an active layer, and an existing targetLayerName. Side effects: stacking order only. Reversible with photoshop_undo.

Move the active layer to the top of the layer stack

Move the active layer up one position in the layer stack

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

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.

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 "Failed to connect to Photoshop" plus a second text block saying which, and does not launch the app. On macOS, Apple-event failures return photoshop_unreachable, automation_permission_denied or photoshop_app_not_resolved with the osascript error and a fix. May append a FEEDBACK_NUDGE block 15 minutes after the first successful ping, then at most once per 7 days (disabled with PSMCP_FEEDBACK=0). May append an UPDATE_AVAILABLE block when a newer photoshop-mcp release is on npm, at most once per 7 days (disabled with PSMCP_UPDATE_CHECK=0). A single ping carries at most one of these blocks. Preconditions: none. Side effects: may trigger Photoshop detection. Does not launch Photoshop.

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.

Play a named action from a named action set in the Actions panel. The action runs whatever steps were recorded; this tool does not limit them. Use when: the user names an existing action and action set to replay. Do NOT use when: no recorded action exists — use a photoshop_recipe_* tool or an atomic photoshop_* tool. Do NOT use when: you need to run arbitrary JSX — use photoshop_execute_script. Returns: the action result text. Preconditions: actionName and actionSetName must match the Actions panel; an open document if the action expects one. Side effects: whatever the action recorded (it may delete layers, change pixels, or save). photoshop_undo reverts only the history steps the action left behind.

Rasterize the active layer (convert text/smart object to normal layer)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

One-shot sticker / white-border outline. single: applies a solid stroke plus (optionally) a soft drop shadow to the active layer. die_cut: the classic double outline — a white border with a thin dark outer line — built by adding two stroked copies of the active layer. Both run in one undoable history step. Users often say: sticker, white border, white outline, cut-out border, die-cut sticker, double outline, 贴画, 白边描边, 一键白边, sticker effect, kontur ekle, beyaz çerçeve, çift çizgi. Use when: the user wants a sticker-style white outline around the active layer, optionally with a drop shadow, without assembling multiple layer styles by hand. Use outline_style="die_cut" when they ask for a die-cut / double-line sticker. Do NOT use when: the user wants a single plain effect — use photoshop_apply_layer_style. Do NOT use when: the layer must first be isolated — use photoshop_recipe_remove_background first when there is still a background. Returns: { ok, summary, undo_history_states_consumed, details: { outline_style, layer_name, stroke_width, stroke_position, stroke_rgb, shadow, border_layer?, line_layer? } }. Preconditions: active document with a non-group active layer (pixel, text, or smart object). The white stroke defaults to 12px outside. die_cut forces the stroke outside and adds two layers named "<layer> - white border" and "<layer> - dark line". Side effects: single sets the stroke (and adds/removes the drop shadow) on the active layer, preserving other existing effects. die_cut adds two stroked copies (original layer untouched on top). One undo reverts everything.

Redo the previously undone operation(s), equivalent to Ctrl/Cmd+Shift+Z. Users often say: redo, yinele, geri alınanı uygula. Use when: reapplying the change that was just undone. Do NOT use when: stepping back through history — use photoshop_undo. Returns: text confirmation with the step count. Preconditions: active document with something on the redo stack. Side effects: moves the history state forward.