MCP server for Adobe Photoshop automation - control Photoshop from AI assistants
Copy the AI prompt to install this server into Claude Code, Cursor, or another agent โ or use 1-click editor setup below.
๐ก Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Languages: English ยท ็ฎไฝไธญๆ ยท Espaรฑol ยท Deutsch ยท ๆฅๆฌ่ช ยท Tรผrkรงe ยท Website
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.
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.
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.

That's it. A local server starts on 127.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 key or your existing CLI subscription account (Anthropic and Google):
| Provider | Models | API key | CLI account |
|---|---|---|---|
| Anthropic | Claude Sonnet / Opus / Haiku | console.anthropic.com | npm i -g @anthropic-ai/claude-code โ claude auth login |
| OpenAI | GPT-5, GPT-4.1, o-series | platform.openai.com | โ |
| Gemini 2.5 Pro / Flash / Flash-Lite | aistudio.google.com | npm i -g @google/gemini-cli โ gemini auth login | |
| OpenRouter | 100+ models from any provider | openrouter.ai | โ |
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).
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:
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.
~/.photoshop-mcp/data.db (SQLite, chmod 600). API keys never leave your
machine; CLI mode inherits OAuth from ~/.claude/ or ~/.gemini/.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 you bound to) on the
server's port. Blocks DNS rebinding.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.
stream-json (Google). All paths talk to this same
Photoshop MCP server over STDIO.claude auth login /
gemini auth login in Terminal).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:
instructions โ workflow contract advertised on MCP initialize
(ping once, state-before-action, prefer recipes, error recovery). See
src/prompts/instructions.ts.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.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
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).photoshop_neural_filter via optional UXP bridge plugin (uxp-plugin/):
skin smoothing, harmonize, depth blur, super zoom, and colorize (B&W โ color).photoshop_get_state (cheap snapshot),
photoshop_get_preview (base64 JPEG for vision verification),
photoshop_get_capabilities (version-aware feature flags).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.
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.
Every recipe wraps a multi-step outcome in a single undo step and maps 1:1 to a ps.* prompt template.
Equivalent MCP prompt template: ps.remove_background with { feather_px: "2", keep_shadow: "false" }.
Equivalent MCP prompt template: ps.remove_distraction with { feather_px: "1" }.
Equivalent MCP prompt template: ps.enhance_portrait with { intensity: "medium", skin_smoothing: "true" }.
Equivalent MCP prompt template: ps.dodge_burn with { blend_mode: "overlay" }.
Equivalent MCP prompt template: ps.frequency_separation with { radius_px: "6" }.
Equivalent MCP prompt template: ps.gradient_fade with { direction: "bottom_to_top" }.
Equivalent MCP prompt template: ps.sky_blend with { sky_image_path: "~/skies/sunset.jpg", horizon_pct: "45" }.
Equivalent MCP prompt template: ps.apply_color_grade with { preset: "warm_film" }.
Equivalent templates: ps.prepare_for_web, ps.export_social_variants.
Equivalent MCP prompt template: ps.batch_mockup_replace.
Equivalent MCP prompt template: ps.organize_layers.
Equivalent MCP prompt template: ps.split_carousel with { slides: "5", size: "1080x1350" }.
Equivalent MCP prompt template: ps.batch_watermark with { assets_dir: "~/photos/portfolio", text: "ยฉ Jane Doe 2026", position: "bottom_right", opacity: "40" }.
Equivalent MCP prompt template: ps.passport_photo with { spec: "us_2x2", make_sheet: "true" }.
Equivalent MCP prompt template: ps.csv_to_cards with { csv_path: "~/cards/speakers.csv", output_dir: "~/cards/out", format: "PNG" }.
Or:
photoshop-mcp-ui); API key or CLI
subscription auth per provider (Anthropic, Google)photoshop_* + 16 recipe photoshop_recipe_*Or from a terminal โ Claude Code:
No installation required! Just configure your MCP client:
To hack on the repo locally, see From Source in the development guide.
Add to your Cursor settings (.cursor/config.json or workspace settings):
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).
Use the Claude Code CLI or the Claude Agent SDK with the same MCP server entry.
Recommended (CLI):
Manual JSON โ merge into your project .mcp.json or Claude Code MCP settings (see examples/claude-code-mcp.json):
Agent SDK (TypeScript) โ pass the same mcpServers block in your query() options:
PHOTOSHOP_PATH: (Optional) Specify custom Photoshop installation pathLOG_LEVEL: Logging level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR)ANALYTICS_DISABLED: Set to 1 or true to disable anonymous usage analytics entirelyPOSTHOG_DISABLED: Legacy alias for ANALYTICS_DISABLEDANALYTICS_PROVIDER: Analytics backend โ mixpanel (default) or posthog (rollback)MIXPANEL_TOKEN: (Optional) Override the Mixpanel project tokenMIXPANEL_API_HOST: (Optional) Mixpanel ingest host (default: https://api-eu.mixpanel.com)POSTHOG_KEY: (Optional, legacy) PostHog project key โ used only when ANALYTICS_PROVIDER=posthogPOSTHOG_API_HOST: (Optional, legacy) PostHog ingest host (default: https://a.alisait.com)POSTHOG_UI_HOST: (Optional, legacy) PostHog UI host (default: https://eu.posthog.com)Full reference for all atomic photoshop_* tools (parameters, examples, and usage):
docs/available-tools.md.
Each tool returns comprehensive context information about the current state of Photoshop, including:
This allows AI assistants to maintain awareness of:
Example Response:
This context helps AI assistants remember what document and layer they're working on across multiple commands.
claude auth login /
gemini auth login in Terminal; credentials live under ~/.claude/ and
~/.gemini/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.
Common connection, scripting, and logging issues:
docs/troubleshooting.md.
| Symptom | Likely cause | Fix |
|---|---|---|
cli_not_found | Claude Code / Gemini CLI not installed | npm i -g @anthropic-ai/claude-code or npm i -g @google/gemini-cli |
not_authenticated | No CLI OAuth session (API key / SDK auth does not count) | Run claude auth login or gemini auth login in Terminal, or switch to API key auth |
| SDK client works, UI CLI mode fails | SDK/API credentials are separate from Claude Code CLI OAuth | Use API key in the standalone UI, or log in with claude auth login for CLI account mode |
claude / gemini not on PATH | Custom install location | Settings โ CLI path โ Check connection |
| Chat works in IDE but not UI (CLI mode) | OAuth tokens are CLI-only | Use CLI account in UI; API keys and CLI sessions are separate |
| Gemini multi-turn feels forgetful | Headless CLI may start a fresh session each turn | Known limitation; history is prepended to the prompt (MVP) |
From-source setup, build, lint, integration tests (with latest results), and usage examples:
docs/development.md.
System design, data flow, platform abstraction, and UI agent modes:
docs/architecture.md.
Sharing on LinkedIn or social? Use images/og-social.png and
docs/social-preview.md for OG setup and post copy.
Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.
Ali Sait Teke โ Full-Stack engineer & AI-era software architect (Python, Go, Node.js, React, Next.js, Vue).
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).
MIT
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.
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
[](https://allmcps.com/mcp/photoshop-mcp)<a href="https://allmcps.com/mcp/photoshop-mcp"><img src="https://allmcps.com/api/badge/photoshop-mcp?style=directory" alt="Photoshop Mcp on AllMCPs" /></a>