convez.ai
MCP Server
alisaitteke

photoshop-mcp

alisaitteke/photoshop-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server for Adobe Photoshop automation - Control Photoshop from AI assistants with 50+ tools for design, image editing, and workflow automation

Instalação

$npx convez-ai alisaitteke/photoshop-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
911
Forks
87
Acompanhando
2
Saúde
28%
Último commit
há 6 dias
Versão
v1.7.38
Issues abertas
21
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Photoshop MCP Server

v1.1+ — recipe workflows, fewer round-trips, snappier sessions.

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

npm version License: MIT TypeScript Platform

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.

🖥️ Standalone UI (no IDE required)

Don't want to wire this into Claude Desktop or Cursor? The same package ships a fully local web UI that lets you chat with an AI model and drive Photoshop through this MCP server underneath.

Standalone UI Screenshot

npx -p @alisaitteke/photoshop-mcp photoshop-mcp-ui

That's it. A local server starts on 127.0.0.1 (random free port) and your default browser opens the chat UI automatically.

Supported providers

Pick any of the following on first launch — bring your own API key:

ProviderModelsGet a key
AnthropicClaude Sonnet / Opus / Haikuconsole.anthropic.com
OpenAIGPT-5, GPT-4.1, o-seriesplatform.openai.com
GoogleGemini 2.5 Pro / Flash / Flash-Liteaistudio.google.com
OpenRouter100+ models from any provideropenrouter.ai

What happens on first launch

  1. Pick a provider and paste your API key.
  2. The key is validated against the provider, then stored locally at ~/.photoshop-mcp/data.db (SQLite, chmod 600). It never leaves your machine.
  3. Type natural-language prompts. The UI streams the model's reply, runs Photoshop tool calls in real time, and renders each tool call as an inspectable card (input + result).
  4. Switch provider or model anytime from the model selector — chats, costs and tool history are persisted across sessions.

CLI flags

photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]

Notes

  • The agent is restricted to Photoshop MCP tools only — built-in shell, file and web tools are disabled.
  • Tech stack: Vue 3 + Tailwind v4 + shadcn-vue on the frontend; Hono + the Vercel AI SDK on the backend. The agent loop talks to this same Photoshop MCP server over STDIO — same code path as the IDE integration.

AI/Prompt Layer for Photoshop

On top of atomic photoshop_* tools, the server ships an opinionated AI/prompt layer that helps host LLMs (Cursor, Claude Desktop, etc.) translate vague user requests into reliable Photoshop actions:

  • Server instructions — workflow contract advertised on MCP initialize (ping once, state-before-action, prefer recipes, error recovery). See src/prompts/instructions.ts.
  • MCP prompts primitive — 16 pre-engineered templates (12 recipe + 4 guide: ps.enhance_portrait, ps.remove_background, ps.gradient_fade, ps.sky_blend, …) via prompts/list and prompts/get.
  • Recipe tools — 12 outcome-oriented photoshop_recipe_* tools (remove background, enhance portrait, prepare for web, export social variants, color grade, frequency separation, batch mockup, organize layers, gradient fade, sky blend, dodge & burn, remove distraction). Each wraps steps in a single Photoshop history state (one Undo reverts all). 78 tools total (66 atomic
    • 12 recipe).
  • State & preview — photoshop_get_state (cheap snapshot), photoshop_get_preview (base64 JPEG for vision verification), photoshop_get_capabilities (version-aware feature flags).
  • Structured errors — failures return JSON envelopes with code and suggested_next_tool for self-correction.

Full reference: docs/prompt-layer.md.

Verify parity: npm run verify:photoshop-prompts

Integration test results

Local MCP integration tests run against a live Photoshop instance over stdio (same path as Cursor / Claude Desktop). Last verified on Photoshop 26.5.0 (macOS).

Recorded on PS 26.5.0 before the intent-expansion tools landed; counts predate the 4 new atomics + 4 new recipes — re-run npm run test:mcp-all to refresh.

SuiteCommandResult
Full tool + recipe sweepnpm run test:mcp-all94 pass, 0 fail, 3 skip (97 total)
Prompt-layer smokenpm run test:mcp-local16 prompt templates + core recipes
Prompt ↔ recipe paritynpm run verify:photoshop-prompts12↔12 strict match + 4 guides

Tool coverage: 78 total tools (66 atomic photoshop_* + 12 recipe photoshop_recipe_*) — re-run npm run test:mcp-all for a fresh pass count.

Intentional skips (environment-dependent, not regressions):

ToolReason
photoshop_play_actionRequires a real Actions palette entry on the machine
photoshop_recipe_remove_backgroundSynthetic test canvas has no recognizable subject for Select Subject
photoshop_recipe_batch_mockup_replaceRequires a Smart Object mockup PSD

PS 26 compatibility notes (ExtendScript): layer masks use stringID make; mask apply uses delete + apply: true; hue/saturation uses Hst2 descriptors; frequency separation uses applyImageEvent calculation descriptors. See src/api/extendscript.ts and src/tools/recipes/_shared.ts.

Prerequisites: Photoshop installed and scriptable; run from the repo root after npm run build:server.


Example Prompts

Below are example prompts you can use with AI assistants (Claude, Cursor, etc.) when this MCP server is configured. Prefer recipe tools (photoshop_recipe_*) for multi-step outcomes — each recipe is a single undo step. Use atomic photoshop_* tools only for fine-grained edits no recipe covers.

Ping Photoshop and read capabilities for my installed version.
Get the current document state before changing anything.
Open portrait.jpg, get a downscaled preview so you can verify the subject.
After each major recipe, get another preview to confirm the result.
Enhance the portrait on the active layer at medium intensity with skin smoothing.
Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
Show me a preview when done.

Equivalent MCP prompt template: ps.enhance_portrait with { intensity: "medium", skin_smoothing: "true" }.

Remove the background from the active portrait layer.
Use Select Subject + a layer mask with a 2px feather. Keep the original pixels behind the mask.
The subject must be on the active layer — not a flat color fill.

Equivalent MCP prompt template: ps.remove_background with { feather_px: "2", keep_shadow: "false" }.

Apply a warm film color grade to the open document as non-destructive adjustment layers.
Use the apply-color-grade recipe with preset warm_film.
Preview the result when finished.
Set up frequency separation on the active raster layer with a 6px blur radius.
I will paint on the Low and High layers myself — do not apply extra smoothing.
Tell me which layers to edit when the stack is ready.

Equivalent MCP prompt template: ps.frequency_separation with { radius_px: "6" }.

Prepare the active document for web: sRGB, downscale, sharpen, export one optimized JPEG to ~/.photoshop-mcp/exports.
Then export Instagram post and X post variants as separate JPEGs from the same document.
List the output paths in a table.

Equivalent templates: ps.prepare_for_web, ps.export_social_variants.

I have a mockup PSD open with a Smart Object layer named "Screen".
Replace it with every PNG/JPG in ~/assets/mockups/ and export one JPEG per asset.
Do not place flat layers — swap the Smart Object so perspective is preserved.

Equivalent MCP prompt template: ps.batch_mockup_replace.

Organize the layer stack: rename by kind, auto-group related layers, preserve originals.
Run the organize-layers recipe, then list layers so I can review the new structure.
Create a 1920x1080 Photoshop document with RGB color mode.
Add a light blue background layer and fill it with RGB(240, 248, 255).
Add centered text "Welcome" in 64pt font.
Save as welcome.psd to my Desktop.
Search Pexels for "mountain sunset" images.
Create a 1920x1080 Photoshop document.
Place the downloaded image and fit it to fill the entire canvas.
Apply a subtle Gaussian blur of 3px.
Increase brightness by 15 and contrast by 10.
Add white text "Adventure Awaits" centered at the top in 72pt.
Set the text opacity to 90% and blend mode to OVERLAY.
Save as adventure.jpg with quality 10.
Open photo.jpg from my Desktop in Photoshop.
Get state, then run the enhance-portrait recipe at low intensity.
If I only need quick tone fixes, apply auto levels, auto contrast, and unsharp mask (120%, 1.5, 0) on the active layer instead.
Adjust hue +15 and saturation +15, or use prepare-for-web when I'm ready to export.
Save as enhanced-photo.jpg with quality 12.
Create a 1200x800 document.
Add a new layer named "Background" and fill with RGB(50, 50, 50).
Place logo.png at position (100, 100).
Fit the logo layer to 50% of its current size.
Set blend mode to SCREEN and opacity to 85%.
Add another layer, fill with RGB(255, 100, 50).
Set this layer's blend mode to MULTIPLY and opacity to 60%.
Merge all visible layers.
Save as composite.psd.
Create a 1080x1350 portrait document (Instagram story size).
Add a layer and fill with gradient-like color RGB(120, 40, 200).
Add text "SUMMER" at (540, 300) in 96pt.
Change text color to white RGB(255, 255, 255).
Set text alignment to CENTER.
Add another text "2026" at (540, 450) in 128pt, white color.
Apply Gaussian blur 2px to the background layer.
Save as summer-poster.png.
Open image1.jpg.
Resize to 1920x1080.
Apply auto contrast.
Apply subtle sharpen (amount 80%, radius 1.0).
Save as processed-1.jpg with quality 10.
Close without saving changes to original.

Repeat for image2.jpg and image3.jpg.
Create a 2000x2000 square document.
Place abstract-pattern.jpg and fit to fill document.
Duplicate the layer.
On the duplicate, apply motion blur at 45 degrees, radius 50px.
Set blend mode to OVERLAY and opacity to 70%.
Add centered text "MOTION" in 120pt white.
Apply a rectangular selection from (200, 200) to (1800, 1800).
Invert the selection and delete (to create a border effect).
Flatten the image.
Save as motion-art.jpg.
Create a 3000x2000 document at 300 DPI for print.
Place hero-image.jpg and fit to fill the canvas.
Duplicate the image layer.
On the duplicate, desaturate it completely.
Set blend mode to LUMINOSITY and opacity to 50%.
Create a new layer named "Overlay".
Fill with RGB(255, 150, 0) and set blend mode to SOFTLIGHT at 30% opacity.
Add text "PORTFOLIO" at top center (1500, 200) in 96pt.
Set text color to white.
Add subtext "2026 Collection" at (1500, 320) in 36pt.
Create a rectangular selection around the text area.
Create a layer mask on the overlay layer.
Merge visible layers.
Save as portfolio-cover.psd.
Export as portfolio-cover.jpg at quality 12.
Open my-photo.jpg.
Play the "Vintage Look" action from "My Actions" set.
Adjust brightness by -10 to darken slightly.
Save as vintage-photo.jpg.
Execute this custom ExtendScript code:
app.beep();
alert('Processing started!');
Apply Gaussian blur 15px to the active layer.
[Wait for result]
Actually, that's too much blur. Undo that.
Apply Gaussian blur 5px instead.

Or:

Get the history states to see what operations were performed.
Undo the last 3 operations.
Redo 1 step to bring back one operation.
If a recipe returns version_unsupported or generative_unavailable, call get_capabilities and tell me which Photoshop feature is missing.
If a tool fails with suggested_next_tool, follow that hint (e.g. rasterize_layer before a raster-only recipe).
Never guess — read get_state after a failure and propose the next single step.

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
  • ✅ 78 Tools: 66 atomic photoshop_* + 12 recipe photoshop_recipe_*
  • ✅ AI/Prompt Layer: 16 MCP prompt templates (12 recipe + 4 guide), server instructions, state/preview/capabilities tools
  • ✅ 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, Curves, Auto Levels/Contrast
  • ✅ Selections & Masks: Rectangular selections, select subject, content-aware fill, gradient mask, 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/alisaitteke/photoshop-mcp.git
cd photoshop-mcp
npm install
npm run build

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.

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_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_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" })

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
// Example: Execute custom code
photoshop_execute_script({
  code: "app.beep();"
})

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"
})

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"
})

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:

{
  "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
    }
  }
}

This context helps AI assistants remember what document and layer they're working on across multiple commands.


Platform-Specific Notes

Windows

  • Uses COM automation to communicate with Photoshop
  • Registry-based auto-detection for installation paths
  • Supports both 32-bit and 64-bit versions

macOS

  • Uses AppleScript/OSA for Photoshop communication
  • Spotlight-based auto-detection
  • Supports multiple Photoshop versions installed simultaneously

Supported Photoshop Versions

  • All Photoshop versions (2012-2025+): Uses ExtendScript API via AppleScript (macOS) or COM (Windows)

Important Note: While Photoshop 2022+ supports UXP for plugins, external automation via AppleScript/COM can only use ExtendScript. UXP is designed for internal plugins and cannot be invoked from external scripts. Therefore, this MCP server uses ExtendScript for maximum compatibility across all Photoshop versions.

Troubleshooting

"Photoshop not found"

  1. Make sure Photoshop is installed in the default location
  2. Or set PHOTOSHOP_PATH environment variable to custom installation path
{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

"Failed to connect to Photoshop"

  1. Ensure Photoshop is running (the server will try to launch it if not)
  2. Check that scripting is enabled in Photoshop preferences
  3. On Windows, verify COM automation is not blocked by security settings

"Script execution timeout"

  • Some operations may take longer on large documents
  • The default timeout is 30 seconds
  • For complex operations, consider breaking them into smaller steps

Debug Logging

Enable detailed logging by setting LOG_LEVEL=0:

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

Development

Build

npm run build

Watch Mode

npm run dev

Lint & Format

npm run lint
npm run format

Integration tests (requires running Photoshop)

npm run build:server
npm run test:mcp-local    # prompt-layer smoke
npm run test:mcp-all      # full sequential tool sweep
npm run verify:photoshop-prompts

Quick Start Examples

💡 Common Use Cases

TaskPrompt Example
Basic Design"Create 1920x1080 document, add blue background, center text 'Hello'"
Photo Edit"Open photo.jpg, apply auto levels, sharpen 100%, save as edited.jpg"
Stock Image"Place image.jpg, fit to fill canvas, add overlay text 'Summer 2026'"
Layer Effects"Set active layer blend mode to MULTIPLY, opacity 80%"
Filters"Apply 10px Gaussian blur to current layer"
Text Styling"Change text to Helvetica 64pt, color red, center aligned"
Batch Work"Resize to 1080x1080, auto contrast, save as square.jpg, close"
Masks"Select rectangle 100,100 to 500,500, create layer mask"
Portrait recipe"Enhance portrait at medium intensity with skin smoothing, then preview"
Background removal"Remove background from active layer, 2px feather, non-destructive mask"
Web export"Prepare for web + export Instagram and X post variants to exports folder"
Color grade"Apply warm_film color grade as adjustment layers"
Frequency separation"Build FS stack at 6px — I'll paint the Low/High layers myself"
State check"Ping Photoshop, get capabilities, then get_state before editing"

Architecture

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 (78 tools: 66 atomic + 12 recipe)
│   │   ├── 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 & subject isolation
│   │   ├── mask-tools.ts            # Gradient mask blending
│   │   ├── state-tools.ts           # State, preview, capabilities
│   │   ├── action-tools.ts          # Actions & custom scripts
│   │   └── recipes/                 # 12 outcome-oriented recipe tools
│   └── utils/            # Utilities
│       └── logger.ts     # Logging system (stderr-based)
└── examples/             # Configuration examples
    ├── cursor-config.json
    └── claude-desktop-config.json

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

Ver o original no GitHub

Bom para

Relacionados