# 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](https://github.com/mikechambers/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

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

### 2. Create virtual environment

```bash
python3 -m venv venv
source venv/bin/activate
```

### 3. Install dependencies

```bash
pip install mcp fastmcp
```

## Configuration

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

```bash
export PHOTOSHOP_APPLICATION_NAME="Adobe Photoshop 2026"
```

Default value is `Adobe Photoshop 2026`.

## Usage

### Start the MCP server

```bash
python3 photoshop_mcp.py
```

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

### Available MCP 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 |

## Workflows

### Print Workflows

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

| Workflow | Dimensions | Bleed | Resolution | Script |
|----------|------------|-------|------------|--------|
| A3 Poster | 297×420mm | 3mm | 300 PPI | `workflows/print/a3_poster.py` |
| A4 Document | 210×297mm | 3mm | 300 PPI | `workflows/print/a4_document.py` |
| A5 Flyer | 148×210mm | 3mm | 300 PPI | `workflows/print/a5_flyer.py` |
| Business Card | 85×55mm | 2mm | 300 PPI | `workflows/print/business_card.py` |
| Letter Size | 8.5×11in | 0.125in | 300 PPI | `workflows/print/letter.py` |

**Usage:**
```bash
python3 workflows/print/a3_poster.py
```

### Social Media Workflows

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

| Platform | Formats | Script |
|----------|---------|--------|
| Instagram | Square (1080×1080), Portrait (1080×1350), Story (1080×1920) | `workflows/social/instagram.py` |
| Facebook | Post (1200×630), Cover (820×312), Story (1080×1920) | `workflows/social/facebook.py` |
| Twitter/X | Post (1200×675), Header (1500×500), Card (1200×628) | `workflows/social/twitter.py` |
| LinkedIn | Post (1200×627), Cover (1584×396) | `workflows/social/linkedin.py` |
| YouTube | Thumbnail (1280×720), Banner (2560×1440) | `workflows/social/youtube.py` |

**Usage:**
```bash
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

```bash
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](ROADMAP.md) for detailed development roadmap.

### Completed
- [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
- [x] Print workflows (A3, A4, Business Card)
- [x] 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](https://github.com/mikechambers/adb-mcp) by Mike Chambers.