MCP server for Adobe Photoshop — 102 tools (generative AI + recipes), standalone web UI. Control Ph…
The MCP server for Adobe Photoshop automation enables control of Photoshop from AI assistants, integrating model-context workflows with scripting and macOS/Windows support. It focuses on extending Illustrator- or Photoshop-related automation through TypeScript tooling and API-driven interactions.
🛠️ Key Features
Photoshop automation via Model Context Protocol
TypeScript-based tooling and scripting compatibility
Support for cross-platform (macOS and Windows)
Readme mentions v1.1+ with recipe workflows and reduced round-trips
Standalone UI option: Action Plan (beta) for plan-then-execute flows
🚀 Use Cases
AI-assisted image editing and graphic design workflows
Automating repetitive Photoshop tasks from AI prompts
Integrating Photoshop actions into broader AI assistant pipelines
⚡ Developer Benefits
Clear MCP server model-context integration for Photoshop
JavaScript/TypeScript tooling and scripting support
Community-maintained, unofficial project with ongoing updates
⚠️ Limitations
Unofficial project not affiliated with Adobe
Readme excerpt highlights beta features; stability may vary
Documentation scope limited to readme excerpt and topics listed
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.
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.
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:
Makes one planning LLM call that outputs an ordered todo list of
Photoshop MCP tool calls with parameters.
Executes those tools directly in sequence — no extra model round-trips
between steps.
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
Pick a provider and choose API key or Uses your account.
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/.
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).
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:
Action
API key mode
CLI account mode
Set up
Paste key → Save
Install CLI → auth login → Check connection
Switch away
Choose API key — stored key is kept
Choose Uses your account — key is not deleted
Custom binary
—
Optional CLI path if claude / gemini is not on PATH
Cost display
Per-token estimate in status bar
Included in subscription badge
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.
The UI server stores your provider API keys and can drive Photoshop, so /api/*
is not open to everything running on your machine. Each request must pass three
checks:
Host — must be the loopback address (or the --host you bound to) on the
server's port. Blocks DNS rebinding.
Origin — when present, must match the UI's own origin. Blocks
cross-origin browser callers.
Session token — a random per-start secret. Blocks other local processes,
which can forge any header but cannot read the token.
The browser never has to deal with the token: the server injects it into the
index.html it serves. For scripting, read it from
~/.photoshop-mcp/ui-session.json (chmod 600) and send it as x-psmcp-token or
Authorization: Bearer, or pin your own with PSMCP_UI_TOKEN before starting
the server. Requests without a valid token get 401 unauthorized.
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 — 23 pre-engineered templates (16 recipe + 7 guide:
ps.enhance_portrait, ps.remove_background, ps.generative_fill, …)
via prompts/list and prompts/get.
Recipe tools — 16 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, split carousel, batch watermark,
passport photo, csv to cards). Each wraps steps in a single
Photoshop history state (one Undo reverts all). 102 tools total (86 atomic
16 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/):
skin smoothing, harmonize, depth blur, super zoom, and colorize (B&W → color).
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.
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.
🧠 State-aware session (recommended first step)
code
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.
Recipes
Every recipe wraps a multi-step outcome in a single undo step and maps 1:1 to a ps.* prompt template.
✂️ Background removal
code
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.
There's a tourist photobombing my landscape on the active layer.
I'll rough-select him with the lasso — then run the remove-distraction recipe with a 1px feather.
Content-aware fill only; don't touch anything outside the selection.
Equivalent MCP prompt template: ps.remove_distraction with { feather_px: "1" }.
👤 Portrait retouch
code
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.
Set up dodge & burn on the active portrait layer: a 50% gray layer in overlay blend mode.
I'll paint with a white/black brush myself — just prepare the non-destructive setup.
Equivalent MCP prompt template: ps.dodge_burn with { blend_mode: "overlay" }.
🔬 Frequency separation setup
code
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" }.
🌗 Gradient fade
code
Fade the isolated subject into the background from the bottom up.
Apply a bottom_to_top gradient on the layer mask, 0 to 100%. Keep the mask editable.
Equivalent MCP prompt template: ps.gradient_fade with { direction: "bottom_to_top" }.
🌤️ Sky blend
code
The sky in my landscape is blown out. Blend ~/skies/sunset.jpg in as the new sky,
horizon at 45% of the frame height, feathered so the treeline stays natural.
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.
Equivalent MCP prompt template: ps.apply_color_grade with { preset: "warm_film" }.
🌐 Prepare for web + social export
code
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.
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.
Organize the layer stack: rename by kind, auto-group related layers, preserve originals.
Run the organize-layers recipe, then list layers so I can review the new structure.
Split the active document into a 5-slide seamless Instagram carousel.
Each slide should be 1080x1350 — crop the slices, don't letterbox them.
Give me the exported file paths in swipe order so I can upload them as-is.
Turn the open portrait into a US passport photo: white background, proper headroom,
exact 600x600 px at 300 DPI. Also give me a 10x15 cm print sheet with copies.
Note: framing is approximated from subject bounds — official acceptance is not guaranteed.
CSV rows become data sets; one personalized card exported per row
code
Generate a name card for every row in ~/cards/speakers.csv using the open template PSD.
PNG output to ~/cards/out — one file per row, named after the row.
Create a 1920x1080 Photoshop document with RGB color mode.
Add a light blue background layer and fill it with RGB(240, 248, 255).
Add centered text "Welcome" in 64pt font.
Save as welcome.psd to my Desktop.
🖼️ Stock Image Design (with Pexels MCP)
code
Search Pexels for "mountain sunset" images.
Create a 1920x1080 Photoshop document.
Place the downloaded image and fit it to fill the entire canvas.
Apply a subtle Gaussian blur of 3px.
Increase brightness by 15 and contrast by 10.
Add white text "Adventure Awaits" centered at the top in 72pt.
Set the text opacity to 90% and blend mode to OVERLAY.
Save as adventure.jpg with quality 10.
✨ Photo Enhancement
code
Open photo.jpg from my Desktop in Photoshop.
Get state, then run the enhance-portrait recipe at low intensity.
If I only need quick tone fixes, apply auto levels, auto contrast, and unsharp mask (120%, 1.5, 0) on the active layer instead.
Adjust hue +15 and saturation +15, or use prepare-for-web when I'm ready to export.
For old black-and-white scans, run the colorize neural filter first (requires the UXP bridge plugin).
Save as enhanced-photo.jpg with quality 12.
🎭 Layer Effects & Blending
code
Create a 1200x800 document.
Add a new layer named "Background" and fill with RGB(50, 50, 50).
Place logo.png at position (100, 100).
Fit the logo layer to 50% of its current size.
Set blend mode to SCREEN and opacity to 85%.
Add another layer, fill with RGB(255, 100, 50).
Set this layer's blend mode to MULTIPLY and opacity to 60%.
Merge all visible layers.
Save as composite.psd.
📝 Text Poster Design
code
Create a 1080x1350 portrait document (Instagram story size).
Add a layer and fill with gradient-like color RGB(120, 40, 200).
Add text "SUMMER" at (540, 300) in 96pt.
Change text color to white RGB(255, 255, 255).
Set text alignment to CENTER.
Add another text "2026" at (540, 450) in 128pt, white color.
Apply Gaussian blur 2px to the background layer.
Save as summer-poster.png.
🎬 Batch Processing
code
Open image1.jpg.
Resize to 1920x1080.
Apply auto contrast.
Apply subtle sharpen (amount 80%, radius 1.0).
Save as processed-1.jpg with quality 10.
Close without saving changes to original.
Repeat for image2.jpg and image3.jpg.
🖌️ Creative Manipulation
code
Create a 2000x2000 square document.
Place abstract-pattern.jpg and fit to fill document.
Duplicate the layer.
On the duplicate, apply motion blur at 45 degrees, radius 50px.
Set blend mode to OVERLAY and opacity to 70%.
Add centered text "MOTION" in 120pt white.
Apply a rectangular selection from (200, 200) to (1800, 1800).
Invert the selection and delete (to create a border effect).
Flatten the image.
Save as motion-art.jpg.
🎯 Advanced Workflow
code
Create a 3000x2000 document at 300 DPI for print.
Place hero-image.jpg and fit to fill the canvas.
Duplicate the image layer.
On the duplicate, desaturate it completely.
Set blend mode to LUMINOSITY and opacity to 50%.
Create a new layer named "Overlay".
Fill with RGB(255, 150, 0) and set blend mode to SOFTLIGHT at 30% opacity.
Add text "PORTFOLIO" at top center (1500, 200) in 96pt.
Set text color to white.
Add subtext "2026 Collection" at (1500, 320) in 36pt.
Create a rectangular selection around the text area.
Create a layer mask on the overlay layer.
Merge visible layers.
Save as portfolio-cover.psd.
Export as portfolio-cover.jpg at quality 12.
🔄 Using Actions
code
Open my-photo.jpg.
Play the "Vintage Look" action from "My Actions" set.
Adjust brightness by -10 to darken slightly.
Save as vintage-photo.jpg.
⚡ Custom Script Execution
code
Execute this custom ExtendScript code:
app.beep();
alert('Processing started!');
⏮️ Undo/Redo Operations
code
Apply Gaussian blur 15px to the active layer.
[Wait for result]
Actually, that's too much blur. Undo that.
Apply Gaussian blur 5px instead.
Or:
code
Get the history states to see what operations were performed.
Undo the last 3 operations.
Redo 1 step to bring back one operation.
🔁 Error recovery (structured envelopes)
code
If a recipe returns version_unsupported or generative_unavailable, call get_capabilities and tell me which Photoshop feature is missing.
If a tool fails with suggested_next_tool, follow that hint (e.g. rasterize_layer before a raster-only recipe).
Never guess — read get_state after a failure and propose the next single step.
Features
Standalone web UI — local chat interface (photoshop-mcp-ui); API key or CLI
subscription auth per provider (Anthropic, Google)
Action Plan (beta) — opt-in plan-then-execute mode in the web UI (API key
only): one planning call, direct tool execution, bounded repair on failure
Works on both Windows and macOS
Supports Photoshop 2012-2025+
ExtendScript API: Universal compatibility via AppleScript/COM automation
Auto-Detection: Automatically finds Photoshop installation on your system
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):
Can't find the config file? In Claude Desktop, open Settings → Developer → Edit Config — it opens the correct path for your install (the %APPDATA% path may differ on some setups).
CLI account auth (standalone UI) is macOS-first: run claude auth login /
gemini auth login in Terminal; credentials live under ~/.claude/ and
~/.gemini/
Supported Photoshop Versions
All Photoshop versions (2012-2025+): Uses ExtendScript API via AppleScript (macOS) or COM (Windows)
Important Note: While Photoshop 2022+ supports UXP for plugins, external automation via AppleScript/COM can only use ExtendScript. UXP is designed for internal plugins and cannot be invoked from external scripts. Therefore, this MCP server uses ExtendScript for maximum compatibility across all Photoshop versions.
This project started from a practical question: how do you make Photoshop reliably
controllable by LLMs without fragile one-off scripts? It grew into an MCP server
with 80 tools, a recipe/prompt layer for dependable multi-step workflows, and a
local web UI so creative work does not require an IDE.
What this codebase demonstrates: TypeScript systems design, MCP protocol
integration, cross-platform desktop automation (macOS AppleScript / Windows COM),
structured error recovery for agentic loops, and a production-minded local-first UI
(Vue 3 + Hono + SQLite).
Anonymous, aggregated usage events are collected by default to improve the
product. You can opt out at any time. Full details:
docs/anonymous-usage-analytics.md.