photoshop-mcp

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 keyor, for Anthropic and Google, reuse the OAuth session fromClaude CodeorGemini CLI— no separate API key required.

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

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

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

- 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 probesclaude auth status/geminiheadless to verify login. Usage counts against yoursubscription 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).

An optional execution mode in the standalone web UI forAPI key auth only(cli_accountalways uses the default agentic flow). Turn it on with theAction Plantoggle next to the model selector in the composer.

Instead of a per-step ReAct loop (model → tool → model → tool …), Action Plan:
- Makesoneplanning LLM call that outputs an ordered todo list of Photoshop MCP tool calls with parameters.
- Executes those toolsdirectlyin sequence — no extra model round-trips between steps.
- On a failed step or unresolved dependency, runs a boundedrepairloop (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.
- Pick a provider and chooseAPI keyorUses 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.

OpenSettingsfrom the sidebar at any time:

Auth method is stored per provider in~/.photoshop-mcp/data.db(authMethod:api_keyorcli_account). Existing configs withoutauthMethoddefault toapi_keyand keep working unchanged.

On top of atomicphotoshop_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:

Below are example prompts you can use with AI assistants (Claude, Cursor, etc.) when this MCP server is configured. Preferrecipe tools(photoshop_recipe_) for multi-step outcomes — each recipe is a single undo step. Use atomicphotoshop_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.

Every recipe wraps a multi-step outcome in asingle undo stepand maps 1:1 to aps.prompt template.

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_backgroundwith{ feather_px: "2", keep_shadow: "false" }.

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_distractionwith{ feather_px: "1" }.

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_portraitwith{ intensity: "medium", skin_smoothing: "true" }.

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_burnwith{ blend_mode: "overlay" }.

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_separationwith{ radius_px: "6" }.

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_fadewith{ direction: "bottom_to_top" }.

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.

Equivalent MCP prompt template:ps.sky_blendwith{ sky_image_path: "~/skies/sunset.jpg", horizon_pct: "45" }.

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_gradewith{ preset: "warm_film" }.

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.

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.

Equivalent MCP prompt template:ps.organize_layers.

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.

Equivalent MCP prompt template:ps.split_carouselwith{ slides: "5", size: "1080x1350" }.

Watermark every photo in ~/photos/portfolio with the text "© Jane Doe 2026". Bottom-right corner, 40% opacity, small margin from the edges. Export watermarked JPEGs — never touch the originals.

Equivalent MCP prompt template:ps.batch_watermarkwith{ assets_dir: "~/photos/portfolio", text: "© Jane Doe 2026", position: "bottom_right", opacity: "40" }.

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.

Equivalent MCP prompt template:ps.passport_photowith{ spec: "us_2x2", make_sheet: "true" }.

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.

Equivalent MCP prompt template:ps.csv_to_cardswith{ csv_path: "~/cards/speakers.csv", output_dir: "~/cards/out", format: "PNG" }.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Execute this custom ExtendScript code: app.beep(); alert('Processing started!');