photoshop-mcp: Driving Photoshop Through an MCP Server and ExtendScript

The gap between a chat prompt and a finished Photoshop document

Photoshop automation has existed for years through ExtendScript and, more recently, UXP. The friction is not the scripting engine. It is that writing a script for a one-off edit takes longer than doing the edit by hand, and that most people who know what they want the image to look like do not write JavaScript. photoshop-mcp targets that gap. It is an MCP server, so an assistant such as Cursor or Claude can call named tools instead of generating a script file, and the README frames the pitch as chatting with Photoshop "like a colleague." The repository also ships a standalone browser UI for people who have no MCP client installed. The intended user is a designer, retoucher, or marketer who owns a Photoshop licence and wants batch or repeatable operations described in plain language. It is not aimed at developers building an image pipeline, because it depends on a running desktop application.

How the bridge works: MCP tools over a live Photoshop session

The README describes a three-step flow. You type a request, the AI plans the steps and checks the document state first, and Photoshop executes. The mechanism underneath is a bridge: the server exposes tools to an MCP client, and those calls reach Photoshop on the same machine. The topics list ExtendScript alongside TypeScript and Vue, which matches the architecture the project documents in docs/architecture.md. Two consequences follow from that design. First, Photoshop must be running, and the README states this as a prerequisite. Second, the server is local, not a cloud service, so the image data does not travel to the model unless the client sends it. The tool surface is split into 102 atomic tools and 16 recipes, according to the README, for 118 total. Atomic tools map to single operations. Recipes chain several operations into one user-facing action, and the README claims each recipe is a single undo step in Photoshop. That claim is the most interesting part of the design, because it means the recipe layer is doing history management, not just sequencing.

Installation paths: npx, MCP config, or the bundled chat UI

There are two documented ways in, and they assume different levels of tooling. The standalone UI runs with `npx -p @alisaitteke/photoshop-mcp photoshop-mcp-ui`, which opens a chat window in the browser. It accepts an AI provider API key, or it can reuse an existing Claude Code or Gemini CLI account with no key. The second path registers the server with an MCP client. For Claude Code the README gives `claude mcp add photoshop -- npx -y @alisaitteke/photoshop-mcp`. For other clients, including Cursor and Claude Desktop, the config block is a `mcpServers` entry named `photoshop` with `command` set to `npx` and `args` set to `["-y", "@alisaitteke/photoshop-mcp"]`. Requirements are Node.js 18 or later and Photoshop 2012 or newer on Windows or macOS. The README also carries Cursor and VS Code deeplink badges that encode the same config. Note the version spread: the README advertises 118 tools while the repository description says 102. The description likely predates the recipe layer, but the mismatch is worth checking against docs/available-tools.md before you plan around a specific count.

What the recipe layer buys you, and what it hides

The recipes are the part that separates this from a thin command wrapper. The README lists background removal with an editable mask, portrait enhancement with skin smoothing and tone fixes at a stated intensity, web export that converts to sRGB and produces sized variants for Instagram and X, carousel splitting that cuts a wide document into numbered slides, and batch watermarking across a folder with originals untouched. There is also a passport photo recipe and CSV-driven card generation. Each is a fixed sequence with parameters, which is why the AI does not have to invent a plan for common jobs. The trade-off is that a recipe encodes someone else's opinion about how a portrait should be smoothed or how much sharpening an export needs. The README shows an intensity parameter on the portrait recipe, so some of that is tunable, but the internal step order is not something you configure. If your studio has a house style, you will either accept the recipe's defaults or drop to atomic tools and rebuild the sequence, at which point you lose the single-undo guarantee.

Generative fill depends on an Adobe account, and that changes the deployment picture

The README marks generative fill and sky replacement as features requiring an Adobe account. That is a meaningful constraint, not a footnote. It means part of the tool surface is gated behind Adobe's own entitlement and network service, so a machine with a valid Photoshop licence but no signed-in Creative Cloud session will fail on those tools. It also means the failure mode is external: when Adobe's service is unreachable, the MCP call fails for reasons the server cannot fix. The AI is described as reading structured errors and choosing a next step, and docs/troubleshooting.md is pointed to for common fixes, but no error catalogue is reproduced in the README. If generative fill is the reason you are evaluating this project, test that path first, on the exact account and network you intend to use.

Where this is the wrong tool

The dependency on a running desktop Photoshop rules out the obvious server-side use cases. You cannot put this in a CI job that renders assets on a Linux build agent, because Photoshop does not run there and the README lists only Windows and macOS. Concurrency is the second limit. A single Photoshop instance is a single document-editing context, so parallel requests from several agents will contend for the same application state. The README does not describe a queue or locking model, and the architecture document is where that would live. Third, the AI plans steps but cannot see the result. It checks document state before acting, per the README, and it reads structured errors after a failure, but nothing in the material suggests it evaluates the rendered pixels. For subjective work such as retouching, a human still has to look at the output. Finally, the project is explicitly unofficial and not affiliated with Adobe, so a Photoshop update can break the bridge and the fix is community-paced. The release cadence visible in the repository, three patch releases across August and September 2026, suggests active maintenance, but that is a cadence observation, not a compatibility guarantee.

The alternative: hand-written ExtendScript or UXP plugins

The direct alternative is writing the ExtendScript yourself, or building a UXP plugin, and running it from Photoshop's Scripts menu or a panel. The difference is where the logic lives. A script is deterministic, version-controlled, and testable without an AI in the loop, and it does not need Node.js or an MCP client. What it lacks is the natural-language entry point and the tool discovery that an MCP server provides: a model can inspect the 118 named tools and pick one, whereas a script file has to be written, saved, and invoked deliberately. For a fixed weekly export job, a script is the better answer. For ad-hoc requests where the operator knows the outcome but not the menu path, photoshop-mcp removes the scripting step entirely. The project also sits next to Adobe's own automation surfaces rather than replacing them; it drives Photoshop through the same underlying scripting layer that a hand-written script would use.

Licence, analytics, and the cost of staying current

The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That covers the server code. It does not cover Photoshop itself, which remains a separate paid licence, nor Adobe's generative services, which are governed by Adobe's terms. This is a description of the licence text, not legal advice; if you are embedding the server in a product, have counsel review the notice requirements. On telemetry, the README states that anonymous, aggregated usage analytics are collected by default and can be disabled, with details in docs/anonymous-usage-analytics.md. That document is where the opt-out mechanism lives, and it should be read before deploying on a managed workstation. Upgrade cost is the recurring item. Because the server sits between an MCP client, a Node runtime, and a desktop application that updates on its own schedule, each Photoshop release is a potential breakage point, and each MCP client release can change how tools are surfaced. Pinning the npm version and reading the release notes before bumping is the practical posture the material supports.

Editorial conclusion

Adopt photoshop-mcp if your team already runs licensed Photoshop on Windows or macOS and you want AI assistants to drive repeatable edits through documented tool calls rather than hand-written ExtendScript. Do not adopt it if you need headless rendering on Linux, if you cannot keep a Photoshop session open, or if you expect the AI to judge visual quality. Before rollout, verify that your Photoshop version supports the specific tools you plan to call, confirm the analytics setting in docs/anonymous-usage-analytics.md, and test the recipe undo behaviour on a scratch document.

Official sources

1. alisaitteke/photoshop-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases