Photoshop MCP Server

Languages: English · 简体中文 · Español · Deutsch · 日本語 · Türkçe

v1.1+ — recipe workflows, fewer round-trips, snappier sessions. Standalone UI ships Action Plan (beta) for plan-then-execute runs.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by Adobe Inc.

A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to control Adobe Photoshop programmatically. This allows you to create designs, manipulate images, and automate Photoshop workflows through natural language commands while working in your IDE — or through the bundled standalone web UI, which supports both API keys and CLI subscription accounts (Claude Code / Gemini CLI). The UI also offers an opt-in Action Plan (beta) mode that plans every Photoshop step in one LLM call, then runs them in a single pass.

Why this exists

Designers and developers want to drive Photoshop from AI assistants, but raw ExtendScript calls are brittle: agents waste tokens on trial-and-error, layer types break filters, and one failed command leaves the document in an unknown state.

Photoshop MCP adds state awareness (get_state, get_preview, get_capabilities), recipe tools that wrap multi-step outcomes in a single undo step, and structured error envelopes so agents know what to try next. The optional standalone UI and Action Plan mode reduce round-trips for longer workflows — so natural language can actually ship pixels, not just suggest them.

Engineering deep-dive: docs/architecture.md.

🖥️ Standalone UI (no IDE required)

Don't want to wire this into Claude Desktop or Cursor? The same package ships a fully local web UI that lets you chat with an AI model and drive Photoshop through this MCP server underneath. Connect with a provider API key or, for Anthropic and Google, reuse the OAuth session from Claude Code or Gemini CLI — no separate API key required.

npx -p @alisaitteke/photoshop-mcp photoshop-mcp-ui

That's it. A local server starts on 127.0.0.1 (random free port) and your default browser opens the chat UI automatically.

Supported providers

Pick any of the following on first launch — use an API key or your existing CLI subscription account (Anthropic and Google):

Authentication modes

• api_key (default) — Vercel AI SDK + your provider API key. Usage is billed per token at API rates; the UI shows estimated cost per chat.
• cli_account — Uses your local Claude Code or Gemini CLI OAuth session. No API key is stored; the UI probes claude auth status / gemini headless to verify login. Usage counts against your subscription quota, not API billing — the status bar shows "Included in subscription".

You can switch auth method per provider in Settings without losing the other credential (e.g. keep an API key while trying CLI account, then switch back).

Action Plan (beta)

An optional execution mode in the standalone web UI for API key auth only (cli_account always uses the default agentic flow). Turn it on with the Action Plan toggle next to the model selector in the composer.

Instead of a per-step ReAct loop (model → tool → model → tool …), Action Plan:

1. Makes one planning LLM call that outputs an ordered todo list of Photoshop MCP tool calls with parameters.
2. Executes those tools directly in sequence — no extra model round-trips between steps.
3. On a failed step or unresolved dependency, runs a bounded repair loop (re-plans only the remaining steps, up to 3 times).

The plan appears as a live todo list above the tool-call cards, with per-step status (pending → running → done / error). Plans are persisted in chat history so they survive reload. The toggle is off by default; the existing agentic flow is unchanged when Action Plan is disabled.

Good for multi-step prompts such as "remove the background and export for web" where you want fewer model calls and faster end-to-end execution.

What happens on first launch

1. Pick a provider and choose API key or Uses your account.
2. Validate the key or check the CLI connection. Config is stored locally at ~/.photoshop-mcp/data.db (SQLite, chmod 600). API keys never leave your machine; CLI mode inherits OAuth from ~/.claude/ or ~/.gemini/.
3. Type natural-language prompts. The UI streams the model's reply, runs Photoshop tool calls in real time, and renders each tool call as an inspectable card (input + result).
4. Switch provider, auth method, or model anytime from Settings / model selector — chats, costs and tool history are persisted across sessions.

Switching auth method later

Open Settings from the sidebar at any time:

Auth method is stored per provider in ~/.photoshop-mcp/data.db (authMethod: api_key or cli_account). Existing configs without authMethod default to api_key and keep working unchanged.

CLI flags

photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]

Notes

• The agent is restricted to Photoshop MCP tools only — built-in shell, file and web tools are disabled.
• Tech stack: Vue 3 + Tailwind v4 + shadcn-vue on the frontend; Hono on the backend. API-key mode uses the Vercel AI SDK; CLI account mode uses the Claude Agent SDK (Anthropic) or Gemini CLI headless stream-json (Google). All paths talk to this same Photoshop MCP server over STDIO.
• CLI account limitations: Gemini headless may open a new session each turn (history is prepended to the prompt). Anthropic CLI account consumes subscription quota. OAuth login is macOS-first (claude auth login / gemini auth login in Terminal).

AI/Prompt Layer for Photoshop

On top of atomic photoshop_* tools, the server ships an opinionated AI/prompt layer that helps host LLMs (Cursor, Claude Desktop, etc.) translate vague user requests into reliable Photoshop actions:

• Server instructions — workflow contract advertised on MCP initialize (ping once, state-before-action, prefer recipes, error recovery). See src/prompts/instructions.ts.
• MCP prompts primitive — 19 pre-engineered templates (12 recipe + 7 guide: ps.enhance_portrait, ps.remove_background, ps.generative_fill, …) via prompts/list and prompts/get.
• Recipe tools — 12 outcome-oriented photoshop_recipe_* tools (remove background, enhance portrait, prepare for web, export social variants, color grade, frequency separation, batch mockup, organize layers, gradient fade, sky blend, dodge & burn, remove distraction). Each wraps steps in a single Photoshop history state (one Undo reverts all). 86 tools total (74 atomic
  • 12 recipe).
• Generative AI — photoshop_generative_fill, photoshop_generative_remove, photoshop_generative_expand, photoshop_generative_upscale, photoshop_sky_replacement, photoshop_generate_image (Firefly via ExtendScript; Adobe account + credits required).
• Neural Filters — photoshop_neural_filter via optional UXP bridge plugin (uxp-plugin/).
• State & preview — photoshop_get_state (cheap snapshot), photoshop_get_preview (base64 JPEG for vision verification), photoshop_get_capabilities (version-aware feature flags).
• Structured errors — failures return JSON envelopes with code and suggested_next_tool for self-correction.

Full reference: docs/prompt-layer.md.

Verify parity: npm run verify:photoshop-prompts. Latest results: docs/development.md#integration-test-results.

Example Prompts

Below are