Photoshop MCP Server

A Model Context Protocol (MCP) server that lets AI assistants (Claude, opencode, Cursor, etc.) drive Adobe Photoshop on Windows through ExtendScript + COM automation.

Built for Photoshop 2020 (v21.x) but compatible with newer versions. ~122 tools covering documents, layers, text, filters, color adjustments, selections & masks, layer styles, export, layout analysis, design QA, and Photoshop state introspection.

Unofficial community project. Not affiliated with or endorsed by Adobe.

How it works

MCP client (opencode/Claude) 
   → Node MCP server (server.js, stdio)
   → bridge.ps1 (PowerShell)
   → Photoshop COM (Application.DoJavaScriptFile)
   → ExtendScript DOM

• ExtendScript, not UXP — external automation via COM can only use ExtendScript, which works on all Photoshop versions (2012–2025+). UXP is for in-process plugins and cannot be invoked externally.
• Unicode-safe — non-ASCII text (e.g. £, —) is escaped to \uXXXX in generated JSX and a UTF-8 BOM is prepended, so prices/accents round-trip correctly.
• Retry on busy — transient COM RPC_E_SERVERCALL_RETRYLATER ("application is busy") errors are retried with backoff.

Requirements

• Windows
• Adobe Photoshop installed (tested on PS 2020 / v21.2)
• Node.js 18+

Install

npm install

Configure as an MCP server

Add to your MCP client config (e.g. ~/.config/opencode/opencode.jsonc, Claude Desktop, Cursor):

{
  "mcpServers": {
    "photoshop": {
      "command": "node",
      "args": ["C:\\path\\to\\photoshop-mcp\\server.js"]
    }
  }
}

Restart your MCP client after changes so the updated tool list loads.

Tool highlights

Area	Tools
Documents	create_document, open_image, save_psd, export_image, export_as, crop_document, resize_image, close_document, generate_variants
Layers	create_layer, add_text, add_text_box, add_rectangle, add_image, place_image, duplicate_layer, delete_layer, rename_layer, rasterize_layer, group_layers, merge_visible_layers, flatten_image, opacity / blend mode / visibility / lock
Layer ops	move_layer, resize_layer, rotate_layer, move_layer_up/down/to_position, fit_layer_to_document, align_layers, distribute_layers, center_in_canvas, snap_to_safe_area
Text	list_fonts, check_font_available, set_font, set_color, set_text_alignment, update_text_content, fit_text, fit_text_to_box
Filters	apply_gaussian_blur, apply_sharpen, apply_noise, apply_motion_blur
Color	adjust_brightness_contrast, adjust_hue_saturation, auto_levels, auto_contrast, desaturate_layer, invert_layer, adjust_curves, apply_lut, adjust_vibrance, adjust_exposure, apply_photo_filter, apply_gradient_map
Selections & masks	select_rectangle, select_all, deselect, invert_selection, create_layer_mask, delete_layer_mask, apply_layer_mask, apply_gradient_mask, content_aware_fill
Layer styles	apply_layer_style (drop shadow / outer glow / stroke)
History	undo, redo, get_history, save_checkpoint, restore_checkpoint
Layout / QA	analyze_layout, detect_overlaps, validate_layout, design_qa, visual_hierarchy, brand_check, execute_design_plan, apply_constraints
Design system	save_design_system, load_design_system, list_design_systems, capture_design_system, create_component
Introspection	get_version, get_capabilities, get_state, get_session_info, get_active_document_info, get_selection_info, get_document_info, list_layers, get_layer_bounds, get_preview, render_preview
Data-driven	image_stack, list_datasets, import_datasets, generate_from_datasets
Automation	play_action, execute_script

Run tools/list in your MCP client to see all ~122 tools.

Configuration reference

run/	Temp JSX files (auto-created)
snapshots/	Named PNG snapshots for visual regression (render_snapshot)
checkpoints/	PSD backups for rollback (save_checkpoint)
design-systems/	Saved design systems (save_design_system)

Known limitations

• Generative AI (Firefly) and Neural Filters require PS 24+ / a UXP bridge plugin and cannot be driven via ExtendScript.
• select_subject needs PS 23+. export_as WebP/AVIF needs PS 23.2+.
• On PS 2020, some commands prompt a "Photoshop is busy" if a modal dialog is open — dismiss it and retry.

Credits

Capability design inspired by:

• alisaitteke/photoshop-mcp
• loonghao/photoshop-python-api-mcp-server

Both are MIT licensed. This project is an independent implementation with additional tools (layout analysis, design QA, design systems, visual regression).

License

MIT