Photoshop MCP Server (AppleScript)

A Model Context Protocol (MCP) server that enables AI clients to control Adobe Photoshop on macOS through AppleScript. This project adapts the architecture from adb-mcp using native macOS automation instead of a Node.js proxy and UXP plugin.

Features

• Document Operations: List open documents, retrieve document metadata (dimensions, resolution, aspect ratio)
• Layer Management: List layers with hierarchy, rename layers, toggle visibility, adjust opacity and blend modes
• Layer Organization: Create new pixel layers, duplicate layers, delete layers, reorder layers (top/bottom/up/down)
• Document Control: Save documents, flatten all layers
• MCP Compatible: Works with any MCP-compatible AI client (Claude Desktop, OpenAI Agent SDK, etc.)

Requirements

• macOS with AppleScript support
• Adobe Photoshop 2026 or later
• Python 3.10 or later
• MCP-compatible client

Installation

1. Clone the repository

git clone https://github.com/<username>/photoshop-mcp.git
cd photoshop-mcp

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install mcp fastmcp

Configuration

Set the PHOTOSHOP_APPLICATION_NAME environment variable if your Photoshop installation has a different name:

export PHOTOSHOP_APPLICATION_NAME="Adobe Photoshop 2026"

Default value is Adobe Photoshop 2026.

Usage

Start the MCP server

python3 photoshop_mcp.py

The server communicates via stdio and exposes tools to MCP clients.

Available Tools

Tool	Description
get_documents	Returns a list of open Photoshop documents with name, path, and modified status
get_document_info	Returns current document metadata: width, height, resolution, pixel aspect ratio
get_layers	Returns all layers with id, name, type, visibility, opacity, blend mode, and nested children
set_layer_visibility	Sets visibility of a layer by id
set_layer_properties	Updates opacity, blend mode, and visibility for a layer
rename_layer	Renames a layer by id
create_pixel_layer	Creates a new art/pixel layer
duplicate_layer	Duplicates a layer by id
delete_layer	Deletes a layer by id
move_layer	Moves a layer by id. Positions: TOP, BOTTOM, UP, DOWN
get_layer_bounds	Returns pixel bounds of a layer
flatten_all_layers	Flattens all layers into a single layer
save_document	Saves the current document

Example Prompts

Once connected to an MCP client:

List all layers in the current Photoshop document.

Rename layer 3 to "Background - Final".

Set layer 5 to 50% opacity and multiply blend mode.

Create a new layer named "Adjustment Layer" with 80% opacity.

Architecture

AI Client <-> MCP Server (Python/FastMCP) <-> AppleScript <-> Adobe Photoshop

This implementation replaces the Node.js proxy server and UXP plugin architecture from the original adb-mcp with direct AppleScript execution, reducing complexity and external dependencies.

Project Structure

photoshop-mcp/
  photoshop_applescript.py  # AppleScript wrappers for Photoshop operations
  photoshop_mcp.py          # FastMCP server exposing tools
  pyproject.toml            # Project metadata and dependencies
  README.md                 # Documentation
  ROADMAP.md                # Development roadmap

Development

Running tests

python3 -c "
import sys
sys.path.insert(0, '.')
from photoshop_applescript import get_documents, get_layers
print(get_documents())
print(get_layers())
"

Adding new tools

1. Add an AppleScript wrapper function in photoshop_applescript.py
2. Expose it as an MCP tool in photoshop_mcp.py using the @mcp.tool() decorator

Roadmap

• [x] Core layer editing (rename, visibility, opacity, blend mode)
• [x] Layer creation, duplication, deletion, reordering
• [x] Document info and document listing
• [x] Layer bounds retrieval
• [x] Save and flatten operations
• [ ] Image export (PNG, JPG)
• [ ] Layer image extraction
• [ ] Place image into layer
• [ ] Selection tools
• [ ] Fill and delete selection
• [ ] Adjustment layers
• [ ] Text layers
• [ ] Layer masks

License

MIT

Acknowledgments

Inspired by adb-mcp by Mike Chambers.