Tool Pick｜photoshop-mcp — Let Claude Drive Your Local Photoshop, With Every Edit a Checkpoint Away From Undo

🌏 中文版

Tool Info

What Problem It Solves

You ask Claude to run a batch of grading, background removal, and cropping in Photoshop. What you're actually worried about isn't whether the agent knows how to drive Photoshop — it's whether it wrecks an original PSD you never backed up, or applies an edit to the wrong document after you've switched tabs to look at something else. Most "let AI control Photoshop" projects stop at "it can call a handful of APIs" and never get to the failure modes that actually destroy real work.

photoshop-mcp bridges to the Photoshop running on your Mac over AppleScript and wraps every operation as an ExtendScript transaction: a failure rolls back automatically into a single undo step, never leaving a half-applied edit behind. More importantly, it layers on three safety mechanisms. Each MCP session pins itself to the document it first touched — even if you manually switch to another file, the agent's next call still targets the original one. Before the first edit of a session, it silently saves a history snapshot plus a layered backup copy on disk (~/Library/Application Support/photoshop-mcp/checkpoints, keeping the newest 20 or 7 days by default). Saving over an existing file needs an explicit overwrite: true, and closing an unsaved document needs discard: true. Before acting, tools like ps_render convert the canvas to an sRGB image so the agent can actually see the result instead of guessing at Photoshop's internal state. The README ships a table of "quirks this version of Photoshop has" — a new layer silently nesting inside a selected group, pixel-to-point conversion breaking on non-72-ppi documents — each one found and fixed while running the server through forty real documents on Photoshop 27.11.

Good fit for: photographers or designers who want an agent to run repetitive grading, cutout, cropping, and export jobs without risking the original files; also worth a look if you're curious how an MCP tool can design real safety boundaries — this one puts far more care into rollback, pinning, and verification than "it technically works."

Quick Start

Install

# macOS only; requires a licensed Photoshop install and Node.js 18+
git clone https://github.com/kathan3009/photoshop-mcp.git
cd photoshop-mcp
./scripts/install.sh --client claude-code   # or claude-desktop / cursor / codex

# Restart the client, open Photoshop, and ask the agent to run ps_status
# macOS will prompt for an Automation permission — allow it

Basic Usage

# Test directly with the bundled psctl CLI, no agent in the loop
psctl status                                    # docs, history, EXIF
psctl snapshot depth=2                          # layer tree with stable ids
psctl render out=/tmp/look.jpg maxSize=1200     # sRGB preview the agent can "see"
psctl adjustment type=hueSaturation \
  params='{"reds":{"saturation":25}}'           # create a hue/saturation adjustment layer
psctl history action=undo                       # roll back one step

The MCP tools an agent gets (ps_status, ps_snapshot, ps_render, ps_adjustment, ps_mask, ps_history, …) behave identically — you're just issuing the same commands in natural language.

Advanced Usage

# Bundle several operations into one atomic undo step (any failure rolls back everything)
psctl batch @grade.json

# The ExtendScript escape hatch is off by default; it must be enabled explicitly
PS_MCP_ALLOW_EXEC=1 ./scripts/install.sh --client claude-code --exec

Comparison with Existing Tools

Photoshop MCP integrations aren't a new idea — the community already has more mature options like alisaitteke/photoshop-mcp (128 tools, cross-platform, built-in chat UI). photoshop-mcp takes a different angle: it trades platform coverage for depth on the one failure mode that actually hurts — a wrecked file.

Things to Watch For

• Only one commit since release, 0 stars: this project went live this week. Its CHANGELOG shows real iteration going back to 2026-10-08, but it hasn't had much community use yet — test on disposable files before trusting it with anything that matters.
• macOS only: it drives Photoshop over AppleScript; Windows support would need the UXP-plugin approach the author mentions as a possible future direction.
• ps_exec (arbitrary ExtendScript execution) is off by default: this is a deliberate safety boundary. Don't set PS_MCP_ALLOW_EXEC=1 unless you fully trust the scripts being passed in.
• Only verified against Photoshop 27.11: other versions are untested; ps_status and doctor flag an unverified version rather than failing outright.

Today's Takeaway

Most "let AI control some piece of software" MCP servers compete on tool count and feature coverage. photoshop-mcp took the other path: solve the easy-to-overlook, actually-fatal-in-production question of "what happens to the user's file when an edit fails" before shipping anything else. Fewer tools isn't automatically a downside — sometimes it means the author thought through the safety boundary first.

References

• kathan3009/photoshop-mcp — GitHub
• photoshop-mcp CHANGELOG
• Claude AI Now Controls Photoshop via MCP Integration — emergent.sh
• alisaitteke/photoshop-mcp — GitHub (cross-platform comparison)