# Photoshop MCP Pro

A professional [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants drive Adobe Photoshop directly — create and edit documents, manage layers, run filters and adjustments, build shapes and text, and apply higher-level design intelligence like palette generation, font pairing, and effect recipes.

It runs locally over stdio and controls Photoshop by executing ExtendScript through a platform-specific executor (macOS and Windows supported). Photoshop is launched **lazily** on the first tool call, so the server starts instantly and only opens Photoshop when you actually use it.

## Features

**Core editing tools**
- **Document** — create, open, save, export, resize, crop, flatten
- **Layer** — create, duplicate, group, reorder, mask, blend modes, opacity
- **Selection** — rectangular/elliptical, by color, invert, feather, modify
- **Transform** — move, scale, rotate, skew, flip
- **Shape & Path** — vector shapes, paths, fills, strokes
- **Text** — text layers, fonts, alignment, color
- **Image** — adjustments, filters, blur, sharpen, noise
- **Adjustment** — brightness/contrast, hue/saturation, levels, curves, color balance
- **Filter** — gaussian/motion blur, sharpen, noise, and more
- **Color** — foreground/background, swatches, sampling
- **Guide** — guides and rulers
- **Smart Object** — create and manage smart objects
- **History** — undo/redo, snapshots
- **Style** — layer styles (drop shadow, stroke, glow, etc.)
- **Export** — PNG, JPEG, and document export
- **Workflow** — multi-step composite operations
- **Script** — run arbitrary ExtendScript

**Design intelligence**
- **Palette** — generate palettes from mood, image, or brand
- **Typography** — suggest font pairings, install fonts, auto-size
- **Recipe** — 12 effect recipes with mood mapping
- **Analysis** — automatic design scoring (color, contrast, typography, composition) via `ps_review`

**Resources & prompts**
- Built-in resources for presets, palettes, fonts, recipes, and design knowledge
- A `create-design` prompt to kick off guided design work

## Requirements

- **Adobe Photoshop** (with scripting enabled — the default)
- **Node.js** >= 18
- **macOS or Windows**

## Installation

```bash
git clone https://github.com/ayushnagvanshi101098-ship-it/photoshop-mcp-pro.git
cd photoshop-mcp-pro
npm install
npm run build
```

This compiles the TypeScript in `src/` to `dist/`.

## Usage

Add the server to your MCP client. The entry point is `dist/index.js`.

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "photoshop": {
      "command": "node",
      "args": ["/absolute/path/to/photoshop-mcp-pro/dist/index.js"]
    }
  }
}
```

Restart your client. Photoshop opens automatically the first time a tool is called.

## Development

```bash
npm run dev    # tsc --watch — rebuild on change
npm run build  # one-off build
npm start      # run the compiled server
```

Source layout:

```
src/
  index.ts        # server entry — registers tools, resources, prompts
  platform/       # OS detection + ExtendScript executors (macOS / Windows)
  tools/          # MCP tool definitions
  scripts/        # ExtendScript generators per tool category
  resources/      # presets, palettes, fonts, recipes, design knowledge
  prompts/        # design prompts
  utils/          # color math, design analyzer, font manager, logging
```

## How it works

Each tool builds an ExtendScript snippet and hands it to a platform executor, which runs it inside Photoshop and returns the result. The connection layer handles lazy launch, reconnection, and relaunch if Photoshop quits mid-session.

## License

[MIT](LICENSE) © Ayush Nagvanshi