# Photoshop MCP Studio

[![CI](https://github.com/Vlad14ok228/photoshop-mcp-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/Vlad14ok228/photoshop-mcp-studio/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Control Adobe Photoshop from **Claude Code** and **Claude Desktop** in plain language ("cut out the girl", "make a 1080x1080 banner with this text").

This repository packages three things so you can set everything up in a few minutes:

1. **A Photoshop MCP server** (128 tools: documents, layers, selections, filters, export, background removal, ...). It is the open-source [`@alisaitteke/photoshop-mcp`](https://github.com/alisaitteke/photoshop-mcp), pinned to a tested version with its anonymous telemetry switched off.
2. **`studio-tools`, our own MCP server** with high-level, tested tools, for example `ps_cutout_polygon` (cut one specific object out of an image, non-destructively) and `ps_unstick` (close Photoshop hint popups that block scripting).
3. **Skills and guides for Claude** (Claude Code) so the AI knows which tool to use when, and which approaches do *not* work. The same key rules are built into the server instructions, so Claude Desktop gets them too.

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

## Requirements

| | |
|---|---|
| OS | **Windows 10/11** (macOS is not supported yet) |
| Photoshop | 2025 or 2026. Developed and tested on Photoshop 2026 (27.0). Photoshop must be **running** when you use the tools |
| Node.js | 18 or newer ([nodejs.org](https://nodejs.org/)) |
| Claude | [Claude Code](https://claude.com/claude-code) and/or Claude Desktop |
| Git | Needed for Claude Desktop setup (clone) |

## Install: Claude Code

```powershell
claude plugin marketplace add Vlad14ok228/photoshop-mcp-studio
claude plugin install photoshop-studio@photoshop-mcp-studio
```

Restart Claude Code, then check:

```powershell
claude mcp list
```

You should see `plugin:photoshop-studio:photoshop` and `plugin:photoshop-studio:studio-tools`, both `Connected`. The first start of `studio-tools` installs its dependencies automatically (a few seconds).

If you already added a server called `photoshop` by hand, remove it to avoid duplicates: `claude mcp remove photoshop -s user`.

## Install: Claude Desktop

```powershell
git clone https://github.com/Vlad14ok228/photoshop-mcp-studio.git
cd photoshop-mcp-studio
node scripts/claude-desktop.mjs --dry-run   # shows what will change, writes nothing
node scripts/claude-desktop.mjs             # does it
```

The script finds your Claude Desktop config (Microsoft Store build or classic installer), **makes a backup**, adds two servers (`photoshop`, `photoshop-studio-tools`) and leaves every other server and setting untouched. Then **fully quit Claude Desktop** (tray icon, Quit) and start it again.

Keep the cloned folder where it is: the config points into it. To remove everything: `node scripts/claude-desktop.mjs --uninstall`.

> Claude Desktop does not load Claude Code skills. It receives the key rules through the server instructions of `studio-tools` instead.
>
> In Claude Desktop the first use of each tool asks for permission (**Allow once** / **Always allow**). Both servers are listed under **+ > Connectors** and can be switched on or off there. If the very first call right after starting Claude Desktop says Photoshop is not running, just ask again (seen once during testing, the next call worked).

## Quick test

1. Start Photoshop.
2. Ask Claude: *"Open C:\Pictures\photo.jpg in Photoshop and remove the background."*
3. Or: *"Create a 800x600 document with a blue layer and the text Hello."*

More example requests are in [docs/EXAMPLES.md](docs/EXAMPLES.md).

## Strongly recommended Photoshop setting

Photoshop shows hint popups (for example the *Generative Fill* tooltip of the Contextual Task Bar). While one is open, **every scripting call fails** with `General Photoshop error`. Turn the bar off once:

**Window → Contextual Task Bar** (remove the check mark).

`ps_unstick` can close a popup that still appears. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## What is included

| Piece | What it does |
|---|---|
| `photoshop` server | The generic 128 tools. `photoshop_recipe_remove_background` removes the background around the main subject in one call |
| `ps_cutout_polygon` | Cuts **one** object out by polygon (pixel coordinates), as a layer mask or as pixels, with Color Range cleanup. Works on a copy and rolls back on errors |
| `ps_unstick` | Closes Photoshop hint popups |
| Skills (Claude Code) | `photoshop-basics`, `photoshop-cutout`, `photoshop-troubleshooting` |

## Known limitations (read this)

- **Windows only**, tested only with Photoshop 2026. Verified end-to-end in Claude Code and in the Microsoft Store build of Claude Desktop (2.42304.2): both servers appear under *Connectors*, and `ps_cutout_polygon` ran successfully from a Desktop chat.
- `ps_cutout_polygon` needs coordinates. Color Range cleanup only catches saturated hues, so on a hard image a thin pale fringe or dark remnants can remain. Measured on one test illustration: 6.1% fringe without cleanup, 1.3% with 4 passes. Always look at the result.
- For "remove the background around the main subject" use `photoshop_recipe_remove_background`; it cannot be told which of several objects to keep.

## Privacy and security

- Everything runs **locally**. The tools talk to your Photoshop through Windows COM; no image is uploaded by this project.
- The third-party server collects anonymous usage analytics by default. **This project turns it off** (`ANALYTICS_DISABLED=1`, `PSMCP_FEEDBACK=0`). If you add that server yourself, do the same.
- The `photoshop_execute_script` tool of the generic server runs arbitrary ExtendScript inside Photoshop. This is powerful: only connect it to AI clients you trust and review what it is asked to do.
- The third-party package is pinned to `1.7.37` on purpose. Update the pin deliberately after reading its changelog.

## Uninstall

- Claude Code: `claude plugin uninstall photoshop-studio@photoshop-mcp-studio` and `claude plugin marketplace remove photoshop-mcp-studio`.
- Claude Desktop: `node scripts/claude-desktop.mjs --uninstall`, then delete the folder.
- Optional: turn the Contextual Task Bar back on in Photoshop (Window menu).

## Development and contributing

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) (architecture, tests, how to add a tool, lessons learned) and [CONTRIBUTING.md](CONTRIBUTING.md).

## License and credits

[MIT](LICENSE). Uses [`@alisaitteke/photoshop-mcp`](https://github.com/alisaitteke/photoshop-mcp) (MIT) at run time; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).