Photoshop MCP Server

v1.1+ — recipe workflows, fewer round-trips, snappier sessions.

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).

🖥️ 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).

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 — 16 pre-engineered templates (12 recipe + 4 guide: ps.enhance_portrait, ps.remove_background, ps.gradient_fade, ps.sky_blend, …) 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). 80 tools total (68 atomic
  • 12 recipe).
• 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 example prompts you can use with AI assistants (Claude, Cursor, etc.) when this MCP server is configured. Prefer recipe tools (photoshop_recipe_*) for multi-step outcomes — each recipe is a single undo step. Use atomic photoshop_* tools only for fine-grained edits no recipe covers.

Ping Photoshop and read capabilities for my installed version.
Get the current document state before changing anything.
Open portrait.jpg, get a downscaled preview so you can verify the subject.
After each major recipe, get another preview to confirm the result.

Enhance the portrait on the active layer at medium intensity with skin smoothing.
Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
Show me a preview when done.

Equivalent MCP prompt template: ps.enhance_portrait with { intensity: "medium", skin_smoothing: "true" }.

Remove the background from the active portrait layer.
Use Select Subject + a layer mask with a 2px feather. Keep the original pixels behind the mask.
The subject must be on the active layer — not a flat color fill.

Equivalent MCP prompt template: ps.remove_background with { feather_px: "2", keep_shadow: "false" }.

Apply a warm film color grade to the open document as non-destructive adjustment layers.
Use the apply-color-grade recipe with preset warm_film.
Preview the result when finished.

Set up frequency separation on the active raster layer with a 6px blur radius.
I will paint on the Low and High layers myself — do not apply extra smoothing.
Tell me which layers to edit when the stack is ready.

Equivalent MCP prompt template: ps.frequency_separation with { radius_px: "6" }.

Prepare the active document for web: sRGB, downscale, sharpen, export one optimized JPEG to ~/.photoshop-mcp/exports.
Then export Instagram post and X post variants as separate JPEGs from the same document.
List the output paths in a table.

Equivalent templates: ps.prepare_for_web, ps.export_social_variants.

I have a mockup PSD open with a Smart Object layer named "Screen".
Replace it with every PNG/JPG in ~/assets/mockups/ and export one JPEG per asset.
Do not place flat layers — swap the Smart Object so perspective is preserved.

Equivalent MCP prompt template: ps.batch_mockup_replace.