Available Tools

Reference for all atomic photoshop_* MCP tools exposed by this server (parameters, examples, and return shapes).

← Back to README

Connection & Info

photoshop_ping

Test connection to Photoshop.

// Example: Check if Photoshop is accessible
photoshop_ping()

photoshop_get_version

Get Photoshop version information.

// Example: Get version details
photoshop_get_version()

Document Management

photoshop_create_document

Create a new Photoshop document.

Parameters:

• width (number, required): Document width in pixels
• height (number, required): Document height in pixels
• resolution (number, optional): DPI resolution (default: 72)
• colorMode (string, optional): Color mode - RGB, CMYK, or Grayscale (default: RGB)

// Example: Create a 1920x1080 RGB document
photoshop_create_document({
  width: 1920,
  height: 1080,
  resolution: 72,
  colorMode: "RGB"
})

photoshop_get_document_info

Get information about the active document.

// Example: Get current document details
photoshop_get_document_info()

photoshop_save_document

Save the active document.

Parameters:

• path (string, required): Full path where to save
• format (string, optional): PSD, JPEG, or PNG (default: PSD)
• quality (number, optional): JPEG quality 1-12 (default: 8)

// Example: Save as JPEG
photoshop_save_document({
  path: "/Users/username/Desktop/output.jpg",
  format: "JPEG",
  quality: 10
})

photoshop_close_document

Close the active document.

Parameters:

• save (boolean, optional): Save before closing (default: false)

// Example: Close without saving
photoshop_close_document({ save: false })

Layer Operations

photoshop_create_layer

Create a new layer.

Parameters:

• name (string, optional): Layer name

// Example: Create a named layer
photoshop_create_layer({ name: "Background" })

photoshop_delete_layer

Delete the active layer.

// Example: Delete current layer
photoshop_delete_layer()

photoshop_create_text_layer

Create a text layer.

Parameters:

• text (string, required): Text content
• x (number, optional): X position in pixels (default: 100)
• y (number, optional): Y position in pixels (default: 100)
• fontSize (number, optional): Font size in points (default: 24)
• fontName (string, optional): Font display or PostScript name (see photoshop_list_fonts)

// Example: Create a text layer with Arial
photoshop_create_text_layer({
  text: "Hello World",
  x: 200,
  y: 150,
  fontSize: 48,
  fontName: "Arial"
})

photoshop_fill_layer

Fill the active layer with a solid color.

Parameters:

• red (number, required): Red component (0-255)
• green (number, required): Green component (0-255)
• blue (number, required): Blue component (0-255)

// Example: Fill with blue
photoshop_fill_layer({
  red: 0,
  green: 100,
  blue: 255
})

photoshop_get_layers

Get list of all layers in the active document.

// Example: List all layers
photoshop_get_layers()

photoshop_set_layer_opacity

Set the opacity of the active layer.

Parameters:

• opacity (number, required): Opacity value (0-100)

// Example: Set opacity to 75%
photoshop_set_layer_opacity({ opacity: 75 })

photoshop_set_layer_blend_mode

Set the blend mode of the active layer.

Parameters:

• blendMode (string, required): Blend mode (NORMAL, MULTIPLY, SCREEN, OVERLAY, etc.)

// Example: Set blend mode to multiply
photoshop_set_layer_blend_mode({ blendMode: "MULTIPLY" })

Available blend modes: NORMAL, DISSOLVE, DARKEN, MULTIPLY, COLORBURN, LINEARBURN, DARKERCOLOR, LIGHTEN, SCREEN, COLORDODGE, LINEARDODGE, LIGHTERCOLOR, OVERLAY, SOFTLIGHT, HARDLIGHT, VIVIDLIGHT, LINEARLIGHT, PINLIGHT, HARDMIX, DIFFERENCE, EXCLUSION, SUBTRACT, DIVIDE, HUE, SATURATION, COLOR, LUMINOSITY

photoshop_set_layer_visibility

Show or hide the active layer.

Parameters:

• visible (boolean, required): Visibility state

// Example: Hide layer
photoshop_set_layer_visibility({ visible: false })

photoshop_set_layer_locked

Lock or unlock the active layer.

Parameters:

• locked (boolean, required): Lock state

// Example: Lock layer
photoshop_set_layer_locked({ locked: true })

photoshop_rename_layer

Rename the active layer.

Parameters:

• name (string, required): New layer name

// Example: Rename layer
photoshop_rename_layer({ name: "Hero Image" })

photoshop_duplicate_layer

Duplicate the active layer.

Parameters:

• newName (string, optional): Name for duplicated layer

// Example: Duplicate layer with new name
photoshop_duplicate_layer({ newName: "Background Copy" })

photoshop_merge_visible_layers

Merge all visible layers into one.

// Example: Merge visible layers
photoshop_merge_visible_layers()

photoshop_flatten_image

Flatten all layers into a single background layer.

// Example: Flatten image
photoshop_flatten_image()

photoshop_rasterize_layer

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

// Example: Rasterize layer
photoshop_rasterize_layer()

Layer Ordering

photoshop_move_layer_to_position

Move the active layer relative to another layer.

Parameters:

• targetLayerName (string, required): Name of the reference layer
• position (string, required): ABOVE, BELOW, TOP, or BOTTOM

// Example: Move layer above "Background"
photoshop_move_layer_to_position({
  targetLayerName: "Background",
  position: "ABOVE"
})

photoshop_move_layer_to_top

Move the active layer to the top of the layer stack.

// Example: Move to top
photoshop_move_layer_to_top()

photoshop_move_layer_to_bottom

Move the active layer to the bottom of the layer stack.

// Example: Move to bottom
photoshop_move_layer_to_bottom()

photoshop_move_layer_up

Move the active layer up one position.

// Example: Move up
photoshop_move_layer_up()

photoshop_move_layer_down

Move the active layer down one position.

// Example: Move down
photoshop_move_layer_down()

Layer Transformations

photoshop_fit_layer_to_document

Scale the active layer to fit the document canvas while maintaining aspect ratio.

Parameters:

• fillDocument (boolean, optional): If true, fills entire canvas (may crop). If false, fits within canvas (may have margins). Default: false

// Example: Fit layer within canvas
photoshop_fit_layer_to_document({ fillDocument: false })

// Example: Fill entire canvas (cropping if needed)
photoshop_fit_layer_to_document({ fillDocument: true })

photoshop_scale_layer

Scale the active layer by a percentage.

Parameters:

• scalePercent (number, required): Scale percentage (e.g., 50 for 50%, 200 for 200%)
• centerAnchor (boolean, optional): Scale from center (true) or top-left (false). Default: true

// Example: Scale to 150%
photoshop_scale_layer({
  scalePercent: 150,
  centerAnchor: true
})

photoshop_move_layer

Move the active layer by specified offset.

Parameters:

• deltaX (number, required): Horizontal offset in pixels
• deltaY (number, required): Vertical offset in pixels

// Example: Move layer 100px right and 50px down
photoshop_move_layer({
  deltaX: 100,
  deltaY: 50
})

photoshop_rotate_layer

Rotate the active layer.

Parameters:

• degrees (number, required): Rotation angle in degrees (positive = clockwise)

// Example: Rotate 45 degrees clockwise
photoshop_rotate_layer({ degrees: 45 })

Filters

photoshop_apply_gaussian_blur

Apply Gaussian Blur filter to the active layer.

Parameters:

• radius (number, required): Blur radius in pixels (0.1-250)

// Example: Apply 10px blur
photoshop_apply_gaussian_blur({ radius: 10 })

photoshop_apply_sharpen

Apply Unsharp Mask (sharpen) filter.

Parameters:

• amount (number, required): Sharpening amount in percent (1-500)
• radius (number, required): Radius in pixels (0.1-250)
• threshold (number, optional): Threshold levels (0-255, default: 0)

// Example: Sharpen image
photoshop_apply_sharpen({
  amount: 100,
  radius: 1.5,
  threshold: 0
})

photoshop_apply_noise

Apply Add Noise filter.

Parameters:

• amount (number, required): Noise amount in percent (0.1-400)
• distribution (string, optional): UNIFORM or GAUSSIAN (default: UNIFORM)
• monochromatic (boolean, optional): Monochromatic noise (default: false)

// Example: Add noise
photoshop_apply_noise({
  amount: 10,
  distribution: "GAUSSIAN",
  monochromatic: false
})

photoshop_apply_motion_blur

Apply Motion Blur filter.

Parameters:

• angle (number, required): Blur angle in degrees (-360 to 360)
• radius (number, required): Blur distance in pixels (1-999)

// Example: Apply motion blur
photoshop_apply_motion_blur({
  angle: 45,
  radius: 20
})

Color Adjustments

photoshop_adjust_brightness_contrast

Adjust brightness and contrast.

Parameters:

• brightness (number, required): Brightness adjustment (-100 to 100)
• contrast (number, required): Contrast adjustment (-100 to 100)

// Example: Increase brightness and contrast
photoshop_adjust_brightness_contrast({
  brightness: 20,
  contrast: 15
})

photoshop_adjust_hue_saturation

Adjust hue, saturation, and lightness.

Parameters:

• hue (number, required): Hue shift (-180 to 180)
• saturation (number, required): Saturation adjustment (-100 to 100)
• lightness (number, required): Lightness adjustment (-100 to 100)

// Example: Adjust colors
photoshop_adjust_hue_saturation({
  hue: 30,
  saturation: 20,
  lightness: 0
})

photoshop_auto_levels

Apply auto levels adjustment.

// Example: Auto levels
photoshop_auto_levels()

photoshop_auto_contrast

Apply auto contrast adjustment.

// Example: Auto contrast
photoshop_auto_contrast()

photoshop_adjust_curves

Create a Curves adjustment layer on the active document.

Parameters:

• preset (string, optional): auto_tone (S-curve) or neutral (identity curve); default auto_tone

// Example: Auto-tone S-curve
photoshop_adjust_curves({ preset: 'auto_tone' })

photoshop_desaturate

Desaturate the layer (convert to grayscale).

// Example: Desaturate
photoshop_desaturate()

photoshop_invert

Invert colors of the layer.

// Example: Invert colors
photoshop_invert()

Text Formatting

photoshop_list_fonts

List installed fonts available to Photoshop. First call may be slow (app.fonts can exceed 1000 entries).

Parameters:

• query (string, optional): Substring filter (matches name, postScriptName, or family)
• limit (number, optional): Maximum fonts to return (default: 200)

Returns: { fonts: [{ name, postScriptName, family, style }], total, truncated }

Use postScriptName when setting fonts manually via execute_script; photoshop_set_text_font and photoshop_create_text_layer resolve display names automatically.

// Example: Find Arial variants
photoshop_list_fonts({ query: "Arial", limit: 20 })

photoshop_set_text_font

Set font family and size for active text layer. Accepts display name (e.g. "Arial") or PostScript name (e.g. "ArialMT").

Parameters:

• fontName (string, required): Font display or PostScript name (use photoshop_list_fonts to discover)
• fontSize (number, optional): Font size in points

// Example: Change font
photoshop_set_text_font({
  fontName: "Helvetica",
  fontSize: 48
})

photoshop_set_text_color

Set color for active text layer.

Parameters:

• red (number, required): Red component (0-255)
• green (number, required): Green component (0-255)
• blue (number, required): Blue component (0-255)

// Example: Set text to blue
photoshop_set_text_color({
  red: 0,
  green: 100,
  blue: 255
})

photoshop_set_text_alignment

Set text alignment.

Parameters:

• alignment (string, required): LEFT, CENTER, RIGHT, LEFTJUSTIFIED, CENTERJUSTIFIED, RIGHTJUSTIFIED, FULLYJUSTIFIED

// Example: Center align text
photoshop_set_text_alignment({ alignment: "CENTER" })

photoshop_update_text_content

Update text content of active text layer.

Parameters:

• text (string, required): New text content

// Example: Update text
photoshop_update_text_content({ text: "New Text" })

Selections & Masks

photoshop_select_rectangle

Create a rectangular selection.

Parameters:

• left, top, right, bottom (number, required): Selection bounds in pixels

// Example: Select area
photoshop_select_rectangle({
  left: 100,
  top: 100,
  right: 500,
  bottom: 400
})

photoshop_select_all

Select the entire document.

// Example: Select all
photoshop_select_all()

photoshop_deselect

Clear all selections.

// Example: Deselect
photoshop_deselect()

photoshop_invert_selection

Invert the current selection.

// Example: Invert selection
photoshop_invert_selection()

photoshop_create_layer_mask

Create a layer mask from the current selection.

// Example: Create mask
photoshop_create_layer_mask()

photoshop_delete_layer_mask

Delete the layer mask from active layer.

// Example: Delete mask
photoshop_delete_layer_mask()

photoshop_apply_layer_mask

Apply (merge) the layer mask to the layer.

// Example: Apply mask
photoshop_apply_layer_mask()

photoshop_select_subject

Run Select Subject on the active layer (pixel selection only, no mask). Requires Photoshop 23+.

Parameters:

• sample_all_layers (boolean, optional): Sample all layers for autoCutout fallback; default false

// Example: Select the main subject
photoshop_select_subject()

photoshop_content_aware_fill

Fill the current pixel selection using Content-Aware Fill. Requires an active selection.

// Example: Remove selected distraction
photoshop_content_aware_fill()

photoshop_apply_gradient_mask

Apply a linear black-to-white gradient on the active layer mask (fade/blend).

Parameters:

• direction (string, optional): Fade direction — bottom_to_top, top_to_bottom, left_to_right, right_to_left; default bottom_to_top
• start_pct (number, optional): Gradient start along fade axis (0–100); default 0
• end_pct (number, optional): Gradient end along fade axis (0–100); default 100
• angle_deg (number, optional): Override gradient angle in degrees

// Example: Fade subject into background from bottom
photoshop_apply_gradient_mask({
  direction: 'bottom_to_top',
  start_pct: 0,
  end_pct: 100
})

History & Undo/Redo

photoshop_undo

Undo the last operation(s) - equivalent to Ctrl/Cmd+Z.

Parameters:

• steps (number, optional): Number of steps to undo (default: 1)

// Example: Undo last operation
photoshop_undo()

// Example: Undo last 3 operations
photoshop_undo({ steps: 3 })

photoshop_redo

Redo previously undone operation(s) - equivalent to Ctrl/Cmd+Shift+Z.

Parameters:

• steps (number, optional): Number of steps to redo (default: 1)

// Example: Redo last undone operation
photoshop_redo()

// Example: Redo last 2 undone operations
photoshop_redo({ steps: 2 })

photoshop_get_history

Get the history states of the active document.

// Example: View history
photoshop_get_history()

Actions & Automation

photoshop_play_action

Play a recorded action from the Actions palette.

Parameters:

• actionName (string, required): Action name
• actionSetName (string, required): Action set name

// Example: Play action
photoshop_play_action({
  actionName: "My Action",
  actionSetName: "Default Actions"
})

photoshop_execute_script

Execute custom ExtendScript code (advanced).

Parameters:

• code (string, required): ExtendScript code

Your code runs inside a wrapping IIFE on the server side. Use an explicit return to pass data back — a bare trailing expression or assignment (e.g. layer.name = "X") evaluates to undefined, so the tool result shows "undefined" even when the mutation succeeded.

// Example: Rename the active layer and return confirmation
photoshop_execute_script({
  code: `
    var layer = app.activeDocument.activeLayer;
    layer.name = "Renamed";
    return { ok: true, name: layer.name };
  `
})

// Example: Read-only query (always return a value you can inspect)
photoshop_execute_script({
  code: "return app.documents.length;"
})

Image Manipulation

photoshop_resize_image

Resize the active image.

Parameters:

• width (number, required): New width in pixels
• height (number, required): New height in pixels

// Example: Resize to Instagram post size
photoshop_resize_image({
  width: 1080,
  height: 1080
})

photoshop_crop_document

Crop the document to specified bounds.

Parameters:

• left (number, required): Left edge in pixels
• top (number, required): Top edge in pixels
• right (number, required): Right edge in pixels
• bottom (number, required): Bottom edge in pixels

// Example: Crop document
photoshop_crop_document({
  left: 100,
  top: 100,
  right: 1820,
  bottom: 980
})

photoshop_place_image

Place an image file as a layer in the active document.

Parameters:

• filePath (string, required): Full path to the image file
• x (number, optional): X position offset in pixels (default: 0)
• y (number, optional): Y position offset in pixels (default: 0)

// Example: Place an image at specific position
photoshop_place_image({
  filePath: "/Users/username/Pictures/photo.jpg",
  x: 100,
  y: 200
})

photoshop_open_image

Open an image file as a new document.

Parameters:

• filePath (string, required): Full path to the image file

// Example: Open an image
photoshop_open_image({
  filePath: "/Users/username/Pictures/photo.jpg"
})

Generative AI (Firefly)

Requires Photoshop 24+ and signed-in Adobe generative credits. Call photoshop_get_capabilities first.

photoshop_generative_fill

Fill the current selection with Generative Fill. Parameters: prompt (required)

photoshop_generative_remove

AI Remove on the current selection. Parameters: feather_px, auto_select_subject

photoshop_generative_expand

Extend canvas with Generative Expand. Parameters: prompt, direction

photoshop_generative_upscale

Generative Upscale (PS 27+). Parameters: target_scale (2 or 4)

photoshop_sky_replacement

Native Sky Replacement. Parameters: sky_image_path (optional)

photoshop_generate_image

Text-to-image. Parameters: prompt, width, height

Neural Filters (UXP bridge)

Requires uxp-plugin/ — see development.md.

photoshop_neural_filter

Parameters: filter (skin_smoothing|harmonize|depth_blur|super_zoom|colorize), smoothness, blur

Layer Styles

photoshop_apply_layer_style

Apply a layer effect (Action Manager layerEffects) to the active layer.

Parameters:

• style (string, required): drop_shadow | outer_glow | stroke | bevel_emboss
• red, green, blue (number, optional): Effect color (default 0/0/0)
• opacity (number, optional): 0-100 (default 60)
• size (number, optional): Blur/size in px — stroke width for stroke (default 10)
• distance (number, optional): Offset in px, drop shadow only (default 8)
• angle (number, optional): Light angle in degrees (default 120)

// Example: soft drop shadow on the active layer
photoshop_apply_layer_style({ style: "drop_shadow", opacity: 55, size: 14, distance: 10 })

Color Grading

photoshop_apply_lut

Color Lookup (3D LUT) adjustment layer — cinematic grades in one step.

Parameters:

• lut (string, required): Built-in LUT name (e.g. "Crisp_Warm.3dl", "Kodak 5218 Fuji 3510.3dl", "Moonlight.3dl") or absolute path to a .cube/.3dl/.look file

photoshop_apply_lut({ lut: "Crisp_Warm.3dl" })

photoshop_adjust_vibrance

Vibrance adjustment layer. Parameters: vibrance (-100..100, default 40), saturation (-100..100, default 0)

photoshop_adjust_exposure

Exposure adjustment layer. Parameters: exposure (stops, default 0.5), offset (default 0), gamma (default 1)

photoshop_apply_photo_filter

Photo Filter adjustment layer (warming/cooling/tint). Parameters: red, green, blue (default 236/138/0 ≈ warming 85), density (0-100, default 25), preserve_luminosity (default true)

photoshop_apply_gradient_map

Gradient Map adjustment layer (black→white). Parameters: reverse (boolean, default false)

Data-Driven Graphics

Photoshop's hidden "mail merge for images": template PSD with variable-bound layers (Image > Variables > Define) + data sets → one image per row.

photoshop_list_datasets

List data sets on the active document. Returns: { datasets, active, count }

photoshop_import_datasets

Import a variables/data-sets XML file. Parameters: xml_path (required)

photoshop_generate_from_datasets

Batch-export the document once per data set.

Parameters:

• output_dir (string, required)
• format (string, optional): JPEG | PNG | PSD (default JPEG)
• dataset_names (string[], optional): subset to export (default all)

photoshop_generate_from_datasets({ output_dir: "/Users/me/cards", format: "PNG" })

One-shot alternative: photoshop_recipe_csv_to_cards converts a CSV straight into data sets and exports every row (prompt template ps.csv_to_cards).

Image Stacking

photoshop_image_stack

Load 2+ images into one document, convert to a smart object, apply a stack mode — classic tourist removal / noise reduction without generative AI.

Parameters:

• files (string[], required): 2+ absolute image paths
• mode (string, optional): mean | median | maximum | minimum | summation | stddev (default median)

// Example: remove tourists from 3 aligned shots
photoshop_image_stack({
  files: ["/shots/a.jpg", "/shots/b.jpg", "/shots/c.jpg"],
  mode: "median"
})

Modern Export

photoshop_export_as

Export a copy as PNG/JPEG (Save for Web) or WebP/AVIF (native, PS 23.2+). Returns version_unsupported when the build lacks WebP/AVIF.

Parameters:

• path (string, required): Absolute output path
• format (string, optional): PNG | JPEG | WEBP | AVIF (default PNG)
• quality (number, optional): 0-100 (default 80)