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

• Print Workflows: Automated A3, A4, A5, Business Card preparation with bleed and CMYK conversion

• Social Media Workflows: Instagram, Facebook, Twitter/X, LinkedIn, YouTube asset creation

• 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 MCP Tools

Workflows

Print Workflows

Automated preparation of print-ready documents with proper dimensions, bleed, and CMYK color profiles.

Usage:

python3 workflows/print/a3_poster.py

Social Media Workflows

Pre-configured assets for all major social platforms in optimal dimensions.

Usage:

python3 workflows/social/instagram.py

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.

Prepare this document as an A3 print poster with 3mm bleed.

Export this design as Instagram square and story formats.

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
└── workflows/
    ├── print/
    │   ├── README.md             # Print workflow documentation
    │   ├── a3_poster.py          # A3 poster preparation
    │   ├── a4_document.py        # A4 document preparation
    │   └── business_card.py      # Business card preparation
    └── social/
        ├── README.md             # Social media workflow documentation
        ├── instagram.py          # Instagram asset creation
        ├── facebook.py           # Facebook asset creation
        ├── twitter.py            # Twitter/X asset creation
        ├── linkedin.py           # LinkedIn asset creation
        └── youtube.py            # YouTube asset creation

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

Adding new workflows

1. Create a new Python script in the appropriate workflows/ subdirectory

2. Follow the existing workflow patterns

3. Update the README with the new workflow documentation

Roadmap

See ROADMAP.md for detailed development roadmap.

Completed

• Core layer editing (rename, visibility, opacity, blend mode)

• Layer creation, duplication, deletion, reordering

• Document info and document listing

• Layer bounds retrieval

• Save and flatten operations

• Print workflows (A3, A4, Business Card)

• Social media workflows (Instagram, Facebook, Twitter, LinkedIn, YouTube)

In Progress

• Additional print formats (A5, Legal, Custom)

• Pinterest workflow

• TikTok workflow

• Batch processing capabilities

Planned

• Image export (PNG, JPG) via MCP tools

• Layer image extraction

• Selection tools

• Fill and delete selection

• Adjustment layers

• Text layers

• Layer masks

• Smart object support

• Template system

• GUI interface

License

MIT

Acknowledgments

Inspired by adb-mcp by Mike Chambers.