Photoshop MCP

🚀 Photoshop MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to control Adobe Photoshop programmatically, allowing you to create designs, manipulate images, and automate Photoshop workflows through natural language commands while working in your IDE.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by Adobe Inc.

🎨 50+ Tools | 🖥️ Cross-Platform | 📦 NPX Ready | 🔧 ExtendScript API | ⏮️ Undo/Redo

🚀 Quick Start

A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to control Adobe Photoshop programmatically. This allows you to create designs, manipulate images, and automate Photoshop workflows through natural language commands while working in your IDE.

✨ Features

• ✅ Works on both Windows and macOS
• ✅ Supports Photoshop 2012 - 2025+
• ✅ ExtendScript API: Universal compatibility via AppleScript/COM automation
• ✅ Auto - Detection: Automatically finds Photoshop installation on your system
• ✅ 50+ 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
• ✅ Auto - Rasterize: Automatically converts layers when needed for filters
• ✅ Context Tracking: Returns document/layer state after each operation for AI context awareness

📦 Installation

Using NPX (Recommended)

No installation required! Just configure your MCP client:

npx @alisaitteke/photoshop-mcp

From Source

git clone https://github.com/yourusername/photoshop-mcp.git
cd photoshop-mcp
npm install
npm run build

💻 Usage Examples

Create a Simple Design

// 1. Create a new document
photoshop_create_document({
  width: 800,
  height: 600,
  colorMode: "RGB"
})

// 2. Create a background layer
photoshop_create_layer({ name: "Background" })

// 3. Fill it with a color
photoshop_fill_layer({
  red: 240,
  green: 240,
  blue: 255
})

// 4. Add a text layer
photoshop_create_text_layer({
  text: "My Design",
  x: 400,
  y: 300,
  fontSize: 64
})

// 5. Save the result
photoshop_save_document({
  path: "/Users/username/Desktop/design.psd",
  format: "PSD"
})

Batch Process Images

// 1. Open existing document (manual step)
// 2. Resize image
photoshop_resize_image({ width: 1920, height: 1080 })

// 3. Save as JPEG
photoshop_save_document({
  path: "/Users/username/Desktop/resized.jpg",
  format: "JPEG",
  quality: 12
})

// 4. Close document
photoshop_close_document({ save: false })

Create Design with Stock Images (using Pexels MCP)

This example shows how to combine Photoshop MCP with Pexels MCP:

// 1. Search for images on Pexels (using Pexels MCP server)
// Note: You need to have Pexels MCP server configured
pexels_photos_search({
  query: "nature landscape",
  per_page: 5
})

// 2. Download the image you want (manually or via script)
// 3. Create a new Photoshop document
photoshop_create_document({
  width: 1920,
  height: 1080,
  colorMode: "RGB"
})

// 4. Place the downloaded image
photoshop_place_image({
  filePath: "/Users/username/Downloads/pexels-photo.jpg",
  x: 0,
  y: 0
})

// 5. Fit the image to document (NEW!)
photoshop_fit_layer_to_document({
  fillDocument: true  // Fill entire canvas
})

// 6. Add text overlay
photoshop_create_text_layer({
  text: "Beautiful Nature",
  x: 960,
  y: 100,
  fontSize: 72
})

// 7. Save the final design
photoshop_save_document({
  path: "/Users/username/Desktop/nature-design.psd",
  format: "PSD"
})

📚 Documentation

Configuration

For Cursor

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

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "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": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "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)

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.

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

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

• photoshop_close_document: Close the active document.

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

Layer Operations

• photoshop_create_layer: Create a new layer.

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

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

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

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

• photoshop_set_layer_blend_mode: Set the blend mode of the active layer.

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

• photoshop_set_layer_visibility: Show or hide the active layer.

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

• photoshop_set_layer_locked: Lock or unlock the active layer.

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

• photoshop_rename_layer: Rename the active layer.

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

• photoshop_duplicate_layer: Duplicate the active 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.

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

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

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

• photoshop_move_layer: Move the active layer by specified offset.

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

• photoshop_rotate_layer: Rotate the active layer.

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

Filters

• photoshop_apply_gaussian_blur: Apply Gaussian Blur filter to the active layer.

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

• photoshop_apply_sharpen: Apply Unsharp Mask (sharpen) filter.

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

• photoshop_apply_noise: Apply Add Noise filter.

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

• photoshop_apply_motion_blur: Apply Motion Blur filter.

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

Color Adjustments

• photoshop_adjust_brightness_contrast: Adjust brightness and contrast.

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

• photoshop_adjust_hue_saturation: Adjust hue, saturation, and lightness.

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

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

• photoshop_set_text_color: Set color for active text layer.

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

• photoshop_set_text_alignment: Set text alignment.

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

• photoshop_update_text_content: Update text content of active text layer.

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

Selections & Masks

• photoshop_select_rectangle: Create a rectangular selection.

// 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()

History & Undo/Redo

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

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

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

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

• photoshop_execute_script: Execute custom ExtendScript code (advanced).

// Example: Execute custom code
photoshop_execute_script({
  code: "app.beep();"
})

Image Manipulation

• photoshop_resize_image: Resize the active image.

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

• photoshop_crop_document: Crop the document to specified bounds.

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

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

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

Example Prompts

Below are example prompts you can use with AI assistants (Claude, Cursor, etc.) when this MCP server is configured:

</details>
<details>
<summary>🖌️ Creative Manipulation</summary>

</details>
<details>
<summary>🎯 Advanced Workflow</summary>

</details>
<details>
<summary>🔄 Using Actions</summary>

</details>
<details>
<summary>⚡ Custom Script Execution</summary>

</details>
<details>
<summary>⏮️ Undo/Redo Operations</summary>

Or:

</details>

## 🔧 Technical Details
### Context Tracking
Each tool returns comprehensive context information about the current state of Photoshop, including:
- **Document Info**: Name, dimensions, resolution, color mode, layer count
- **Active Layer Info**: Name, type, opacity, blend mode, visibility, lock state
- **Selection State**: Whether a selection is active
- **Operation Result**: Specific details about what was changed

This allows AI assistants to maintain awareness of:
- Which document is active
- Which layer is being worked on
- Current layer properties (opacity, blend mode, etc.)
- Document dimensions and settings

**Example Response:**
```javascript
{
  "applied": true,
  "filter": "Gaussian Blur",
  "radius": 10,
  "wasRasterized": true,
  "context": {
    "hasDocument": true,
    "document": {
      "name": "design.psd",
      "width": 1920,
      "height": 1080,
      "resolution": 72,
      "colorMode": "RGBColorMode",
      "layerCount": 3,
      "hasSelection": false
    },
    "activeLayer": {
      "name": "Background",
      "kind": "NORMAL",
      "opacity": 100,
      "blendMode": "NORMAL",
      "visible": true,
      "locked": false,
      "isBackground": false
    }
  }
}

{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

{
  "env": {
    "LOG_LEVEL": "0"
  }
}

npm run build

npm run dev

npm run lint
npm run format

photoshop-mcp/
├── src/
│   ├── core/              # MCP server core
│   │   ├── server.ts      # Main MCP server
│   │   ├── session.ts     # Session management
│   │   └── tool-registry.ts  # Tool registration system
│   ├── platform/          # Platform-specific detection & execution
│   │   ├── detector.ts    # Main detector
│   │   ├── connection.ts  # Connection manager
│   │   ├── windows-detector.ts  # Windows registry detection
│   │   ├── windows-executor.ts  # Windows COM automation
│   │   ├── macos-detector.ts    # macOS Spotlight detection
│   │   └── macos-executor.ts    # macOS AppleScript execution
│   ├── api/              # Photoshop API abstractions
│   │   ├── photoshop-api.ts    # API factory
│   │   ├── batch-play.ts       # UXP batchPlay helpers (legacy)
│   │   └── extendscript.ts     # ExtendScript snippets library
│   ├── tools/            # MCP tool implementations (42+ tools)
│   │   ├── document-tools.ts        # Document operations
│   │   ├── layer-tools.ts           # Layer creation/deletion
│   │   ├── layer-properties-tools.ts # Opacity, blend modes, etc.
│   │   ├── layer-transform-tools.ts  # Scale, rotate, move
│   │   ├── image-tools.ts           # Resize, crop
│   │   ├── image-placement-tools.ts # Place/open images
│   │   ├── filter-tools.ts          # Blur, sharpen, noise
│   │   ├── adjustment-tools.ts      # Color adjustments
│   │   ├── text-tools.ts            # Text formatting
│   │   ├── selection-tools.ts       # Selections & masks
│   │   └── action-tools.ts          # Actions & custom scripts
│   └── utils/            # Utilities
│       └── logger.ts     # Logging system (stderr-based)
└── examples/             # Configuration examples
    ├── cursor-config.json
    └── claude-desktop-config.json