photoshop-mcp

Apply Image > Adjustments > Brightness/Contrast once to the active layer. Values are deltas on pixels, not an adjustment layer. Users often say: fix exposure, add contrast, brighten, darken. Use when: a quick brightness/contrast pass on the current raster layer. Do NOT use when: exposure in stops on an editable layer — use photoshop_adjust_exposure. Do NOT use when: a non-destructive tonal curve — use photoshop_adjust_curves. Do NOT use when: automatic black and white points — use photoshop_auto_levels. Returns: the brightness and contrast values applied. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Calling again applies another delta. Reversible with photoshop_undo.

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.

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.

Shift hue, saturation, and lightness on the active layer via Image > Adjustments > Hue/Saturation. Values are applied once to pixels, not stored as an adjustment layer. Use when: a direct color shift on the current layer is enough. Do NOT use when: the change must stay editable — use photoshop_adjust_vibrance or photoshop_adjust_curves. Do NOT use when: the user wants a cinematic grade — use photoshop_recipe_apply_color_grade. Returns: the hue, saturation, and lightness that were applied. Preconditions: active document and active layer. Text and Smart Objects are rasterized first, and a non-Normal blend mode is reset to Normal. Side effects: destructive pixel edit, one history step. Reversible with photoshop_undo.

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.

Apply Gaussian Blur filter to the active layer

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.

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.

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.

Bake the active layer mask into its pixels and remove the mask. Pixels the mask hid are deleted. Use when: the user wants the mask permanently applied. Do NOT use when: the mask should stay editable — leave it, or create one with photoshop_create_layer_mask. Do NOT use when: the mask should be discarded without changing pixels — use photoshop_delete_layer_mask. Returns: confirmation that the mask was applied. Preconditions: active document and an active layer that has a mask. Side effects: destroys masked-out pixels and the mask. Reversible with photoshop_undo while history holds it.

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

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.

Apply Motion Blur to the active raster layer (angle in degrees, distance in pixels). Use when: directional streak blur on one layer. Do NOT use when: a round blur is enough — use photoshop_apply_gaussian_blur. Do NOT use when: blur should keep edges — use photoshop_apply_smart_blur. Returns: the angle and radius applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

Apply Add Noise to the active raster layer (amount percent, UNIFORM or GAUSSIAN, optional monochromatic). Use when: grain or noise on one raster layer. Do NOT use when: the goal is blur or sharpen — use photoshop_apply_gaussian_blur or photoshop_apply_sharpen. Returns: the amount, distribution, and monochromatic flag applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. A second call adds more noise. Reversible with photoshop_undo.

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.

Apply Unsharp Mask to the active raster layer (amount, radius, threshold). This is a pixel filter on one layer, not a web-export sharpen pass. Use when: sharpening one layer in the open document. Do NOT use when: preparing a file for the web — use photoshop_recipe_prepare_for_web. Do NOT use when: you want edge extraction for an overlay sharpen — use photoshop_apply_high_pass. Returns: the amount, radius, and threshold applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first, which drops live type and smart-object edits. Side effects: changes pixels in one history step. Reversible with photoshop_undo.

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.

Run Auto Contrast on the active layer. Photoshop picks the contrast; there is no amount parameter. Use when: a one-shot automatic contrast fix on the current layer. Do NOT use when: you need numeric brightness and contrast — use photoshop_adjust_brightness_contrast. Do NOT use when: black, white, and gray points should move — use photoshop_auto_levels. Do NOT use when: a non-destructive curve — use photoshop_adjust_curves. Returns: confirmation that Auto Contrast ran. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

Run Auto Levels on the active layer. Photoshop sets the black, white, and gray points; there is no amount parameter. Users often say: fix flat image, auto tone, make it pop (mild). Use when: a one-shot automatic level fix on the current layer. Do NOT use when: only contrast should move — use photoshop_auto_contrast. Do NOT use when: you want a specific brightness and contrast delta — use photoshop_adjust_brightness_contrast. Do NOT use when: the correction must stay an editable adjustment layer — use photoshop_adjust_curves. Returns: confirmation that Auto Levels ran. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

Crop the active document to a pixel rectangle (left, top, right, bottom). Pixels outside that rectangle are deleted and the canvas shrinks. Use when: the user gives explicit crop bounds in pixels. Do NOT use when: only one layer should scale inside the existing canvas — use photoshop_fit_layer_to_document or photoshop_scale_layer. Do NOT use when: the whole image should be resampled to a new width and height — use photoshop_resize_image. Returns: the new document width and height. Preconditions: active document; right > left and bottom > top. Side effects: destructive crop of every layer, one history step. Reversible with photoshop_undo.

Delete the active layer, including its pixels, mask, and effects. Use when: the user wants that layer removed from the stack. Do NOT use when: it should only be hidden — use photoshop_set_layer_visibility. Do NOT use when: only the mask should go — use photoshop_delete_layer_mask. Do NOT use when: the whole stack should collapse — use photoshop_flatten_image. Returns: confirmation that the layer was deleted. Preconditions: active document and a deletable active layer. Side effects: destroys the layer. Reversible with photoshop_undo while history holds it.

Delete the layer mask from active layer

Desaturate the active layer (convert to grayscale)

Clear the current pixel selection. Pixels are unchanged. Use when: a selection should be cleared before the next edit. Do NOT use when: you want the inverse region selected — use photoshop_invert_selection. Do NOT use when: you want every pixel selected — use photoshop_select_all. Returns: confirmation that the selection was cleared. Preconditions: active document. Safe when nothing is selected. Side effects: selection only. Idempotent. Reversible with photoshop_undo if a selection existed.

Duplicate the active layer. The duplicate becomes the active layer; returns its name and, when available, its layer id.

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.

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. Do NOT use when: painting a two-color gradient — use photoshop_fill_gradient. Document.gradients does not exist and throws "undefined is not an object". 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.

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.

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.

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

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.

Paint a two-color linear gradient on the active layer pixels. Use when: the user asks for a color gradient, blend, or "mavi yeşil" style ramp on a layer. Do NOT use when: a flat color is enough — use photoshop_fill_layer. Do NOT use when: the gradient should fade the layer into the background — use photoshop_recipe_gradient_fade. Do NOT use when: you would write ExtendScript. Document.gradients does not exist. Returns: the two colors and direction applied. Preconditions: active document and an unlocked non-text layer. Side effects: overwrites those pixels, one history step. The same colors on the same pixels are idempotent. Reversible with photoshop_undo.

Fill the active layer with a solid RGB color. If a selection exists, only that region is filled and the selection stays; otherwise the whole layer is filled and the selection is cleared. Use when: a flat color fill on the active layer or on the current selection. Do NOT use when: a new empty layer is needed first — use photoshop_create_layer, then this. Do NOT use when: the fill should be a two-color gradient — use photoshop_fill_gradient. Do NOT use when: the selection should be filled with surrounding content — use photoshop_content_aware_fill. Do NOT use when: the active layer is text — rasterize with photoshop_rasterize_layer first, or recolor type with photoshop_set_text_color. A smart object is rasterized in place and then filled. No extra layer is created. Returns: the RGB color applied. Preconditions: active document and an unlocked non-text layer. Side effects: overwrites those pixels. The same color on the same pixels is idempotent. Reversible with photoshop_undo.

Scale the active layer to the document canvas, keeping aspect ratio. `fillDocument: false` (default) fits inside and may letterbox; `true` covers the canvas and may crop the layer. Use when: a placed layer should match the canvas size. Do NOT use when: you want a specific percent — use photoshop_scale_layer. Do NOT use when: the document canvas itself should change size — use photoshop_resize_image or photoshop_crop_document. Returns: confirmation of the fit. Preconditions: active document and active layer. Side effects: transforms that layer. Does not change document dimensions. Reversible with photoshop_undo.

Flatten the active document into a single Background layer. Hidden layers are discarded. Use when: the user explicitly wants one background layer and no remaining layer stack. Do NOT use when: hidden layers should survive — use photoshop_merge_visible_layers. Do NOT use when: layers must stay editable. Returns: confirmation that the document was flattened. Preconditions: active document. Side effects: destroys every layer, mask, and hidden pixel. photoshop_undo can restore the stack while history still holds it.

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.

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.

Extend the canvas beyond its edges using Generative Expand (Firefly). 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.

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.