photoshop-mcp

An MCP server that lets an MCP client (Claude Code, Claude Desktop) work in a live Adobe Photoshop: open or place reference images, build documents and check the result with previews.

MCP client --stdio--> server (src/, Node) <--WebSocket 127.0.0.1 + token-- UXP plugin in Photoshop (plugin/)

A UXP plugin can only make outgoing connections, so the server listens and the plugin connects to it. Each server writes ~/.photoshop-mcp/bridges/<pid>.json (port + token, mode 0600). The plugin checks that folder every 2 s and connects to every server it finds, so several Claude sessions can share one Photoshop. Commands run one at a time, because Photoshop has one modal state. Every change runs in executeAsModal as one history step (one undo).

Status: 0.5.0. Needs Photoshop 26.9+ (tested on 27.10). Tested against a fake Photoshop (npm test) that models every quirk found live, and against real Photoshop with npm run live. Changes: CHANGELOG.md.

Setup

Needs Node 22.18+ and Photoshop 26.9+ (tested: Photoshop 2026, 27.10).

npm install
npm run build

Load the plugin (once). Either install the package: npm run package, then double-click dist/photoshop-mcp-<version>.ccx (Creative Cloud installs it; not yet tried on a machine without Developer Mode), or load it for development:

1. Photoshop: Settings > Plugins > Enable Developer Mode, then restart Photoshop.

2. Open Adobe UXP Developer Tools: Add Plugin > choose plugin/manifest.json > Load. Accept the prompt for full file access (needed to read the bridge folder and your images).

3. In Photoshop: Plugins > Photoshop MCP. The panel shows "Connected to 1 MCP server" once a server runs.

Register the server with Claude Code:

claude mcp add photoshop -- node /absolute/path/to/photoshop-mcp/dist/index.js

After changing plugin-src/, run npm run build and press Reload in UXP Developer Tools.

Related MCP server: Photoshop MCP Server

Tools

Errors are {error:{code,message,hint}} (arguments that fail the schema come back as the MCP SDK's own validation text). code is one of NOT_FOUND, BAD_ARGS, PS_ERROR, BUSY (Photoshop is in a dialog or modal tool), BRIDGE_DOWN, TIMEOUT, FORBIDDEN or UNSUPPORTED.

Reference images

An image you paste into the chat is visible to the model, but its bytes don't reach the server. Give the file's path instead ("place ~/Desktop/ref.png"), or the client can pass base64 as data. Typical flow: open_image (or create_document at the reference's size), then place_image with opacity: 40, locked: true, build over it, and preview to compare.

Settings

Development

npm test            # build, then test/*.test.ts (no Photoshop needed)
npm run typecheck   # server, plugin and tests
npm run live        # every tool against real Photoshop (plugin loaded, panel open); creates "mcp-live" documents
npm run check-api   # the Photoshop API the plugin declares, against Adobe's reference
npm run package     # dist/photoshop-mcp-<version>.ccx

• test/tools-document.test.ts, tools-edit.test.ts, tools-layers-looks.test.ts: the built plugin's commands in a vm against test/fake-ps.ts, which models what real Photoshop does (changes only in executeAsModal, a busy modal state, Photoshop's enums only, the quirks listed in CLAUDE.md).

• test/e2e.test.ts: the built server over stdio with a real MCP client, plus the real plugin over a real WebSocket: sandboxing (also inside batch_play descriptors), base64 uploads, timeouts, disconnects, bad tokens, two servers, stale bridge files, outdated plugin builds, the error format.

• test/docs.test.ts (uxp_docs against a local stand-in for GitHub), slim.test.ts, registry.test.ts, static.test.ts. CI (.github/workflows/test.yml) runs the typecheck, the tests and the package.

Security

The server listens on 127.0.0.1 only, with a random token per run (bridge files are mode 0600). Path arguments, and every _path inside batch_play descriptors, must be inside PS_MCP_ALLOWED_DIRS. The plugin itself asks for full file access (to read the bridge folder and your images) and network: all: Photoshop's manifest has no reliable way to allow only a local WebSocket with a changing port. uxp_docs is the only tool that reaches the internet (GitHub).