Photoshop Mcp Windows First

Photoshop MCP Windows-First

> Unofficial Adobe Photoshop automation tooling for local MCP workflows. Not affiliated with or endorsed by Adobe Inc.

[](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) []()

A Model Context Protocol (MCP) server for controlling Adobe Photoshop from AI assistants, with a Windows-first workflow layer, structured state, smoke-tested action playback, and a bundled Codex skill for high-fidelity image editing.

> 🎨 90+ Tools | 🖥️ Windows-First | 🧠 Bundled Codex Skill | 🔧 ExtendScript + UI Fallback | 🧪 Real Smoke Coverage

Features

• ✅ Works on both Windows and macOS
• ✅ Supports Photoshop 2012-2025+
• ✅ ExtendScript API: Universal compatibility via AppleScript/COM automation
• ✅ Windows-first control layer: structured state, targeting, prompts, resources, and UI recovery tools
• ✅ Auto-Detection: Automatically finds Photoshop installation on your system
• ✅ 90+ Tools: Comprehensive Photoshop automation
• ✅ Document Management: Create, open, save, close, crop documents
• ✅ Layer Operations: Create, delete, duplicate, merge, transform layers
• ✅ Layer Properties: Opacity, blend modes, visibility, locking
• ✅ Text Formatting: Font, size, color, alignment controls
• ✅ Image Placement: Place images, open files, fit to document
• ✅ Filters: Gaussian Blur, Sharpen, Noise, Motion Blur
• ✅ Color Adjustments: Brightness/Contrast, Hue/Saturation, Auto Levels/Contrast
• ✅ Selections & Masks: Rectangular selections, layer masks
• ✅ History Control: Undo/Redo operations, view history states
• ✅ Actions: Play recorded actions, execute custom scripts
• ✅ Fixture-backed smoke action: bundled MCP Smoke / 動作 1 action fixture for unattended verification
• ✅ Auto-Rasterize: Automatically converts layers when needed for filters
• ✅ Context Tracking: Returns document/layer state after each operation for AI context awareness
• ✅ Bundled Codex skill: skills/image-editing-agent aligned to this MCP server

Quick Start

git clone https://github.com/rookietopred02-gif/photoshop-mcp-windows-first.git
cd photoshop-mcp-windows-first
npm install
npm run build

Installation

From Source

git clone https://github.com/rookietopred02-gif/photoshop-mcp-windows-first.git
cd photoshop-mcp-windows-first
npm install
npm run build

Configuration

For Cursor

Add to your Cursor settings (.cursor/config.json or workspace settings):

{
  "mcpServers": {
    "photoshop": {
      "command": "node",
      "args": ["C:/path/to/photoshop-mcp-windows-first/dist/index.js"],
      "env": {
        "PHOTOSHOP_PATH": "C:/Program Files/Adobe/Adobe Photoshop 2024/Photoshop.exe",
        "LOG_LEVEL": "1"
      }
    }
  }
}

For Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "photoshop": {
      "command": "node",
      "args": ["C:/path/to/photoshop-mcp-windows-first/dist/index.js"],
      "env": {
        "PHOTOSHOP_PATH": "C:/Program Files/Adobe/Adobe Photoshop 2024/Photoshop.exe",
        "LOG_LEVEL": "1"
      }
    }
  }
}

Environment Variables

• PHOTOSHOP_PATH: (Optional) Specify custom Photoshop installation path
• LOG_LEVEL: Logging level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR)

Bundled Codex Skill

This repo includes the aligned Codex skill at skills/image-editing-agent.

To install it locally:

Copy-Item -Recurse -Force `
  ".\\skills\\image-editing-agent" `
  "$HOME\\.codex\\skills\\image-editing-agent"

The skill is tuned to:

• prefer structured Photoshop MCP tools before raw scripts
• use checkpoints and validation after major edits
• treat default Photoshop actions as unreliable unless already proven unattended
• work cleanly with the bundled smoke-tested MCP Smoke action fixture when action playback is needed

Validation

Real-machine validation is built in:

npm run lint
npm test
npm run test:real

npm run test:real uses the bundled fixture-backed action smoke path instead of probing random installed default actions.

Available Tools

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)

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

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_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_set_text_font

Set font family and size for active text layer.

Parameters:

• fontName (string, required): Font family name
• 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" })

Select

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Vaxaxas
• Source: Vaxaxas/photoshop-mcp-windows-first
• License: MIT

Install and usage instructions live in the source repository linked above.