# 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

```bash
npm install
```

## Configure as an MCP server

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

```json
{
  "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](https://github.com/alisaitteke/photoshop-mcp)
- [loonghao/photoshop-python-api-mcp-server](https://github.com/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