dcc-mcp-photoshop

Adobe Photoshop adapter for the DCC Model Context Protocol ecosystem. Bridges AI agents (Claude, Cursor, Copilot) to Adobe Photoshop via UXP WebSocket.

⚠️ Pre-Alpha: UXP plugin implementation is pending. API design is stable.

Architecture

AI Agent (Claude / Cursor)
    ↓  MCP Streamable HTTP (port 8765)
PhotoshopMcpServer  [this package, Python]
    ↓  WebSocket JSON-RPC (port 3000)
UXP Plugin  [bridge/uxp-plugin/, JavaScript]
    ↓  Photoshop UXP API
Adobe Photoshop 2022+

DCC Capabilities:

DccCapabilities(
    has_embedded_python=False,
    bridge_kind="websocket",
    bridge_endpoint="ws://localhost:3000",
    snapshot=True,
    file_operations=True,
    selection=True,
)

Features

Current (v0.1.0 — Placeholder):

• ✅ Package structure and API design

• ✅ PhotoshopBridge WebSocket client scaffold

• ✅ Skill authoring helpers (ps_success, ps_error, with_photoshop)

• ✅ PhotoshopMcpServer wrapping dcc-mcp-core

• ⏳ UXP plugin implementation (pending)

• ⏳ WebSocket bridge implementation (pending)

Planned:

• Document management (open, save, export)

• Layer management (create, delete, reorder, blend modes)

• Selection tools (marquee, lasso, magic wand)

• Filter application

• Color adjustments

• Smart Object operations

• Batch processing

Requirements

• Adobe Photoshop 2022+ (UXP support)

• Python 3.8+

• dcc-mcp-core >= 0.12.14

• websockets >= 12.0

Installation

pip install dcc-mcp-photoshop

Or from source:

git clone https://github.com/loonghao/dcc-mcp-photoshop
cd dcc-mcp-photoshop
pip install -e ".[dev]"

Photoshop UXP Plugin Setup

1. Install the UXP plugin from bridge/uxp-plugin/ (pending implementation)

2. Open Photoshop

3. Go to Plugins > Browse Plugins

4. Install from local manifest

5. The plugin starts a WebSocket server on port 3000 automatically

Quick Start

import dcc_mcp_photoshop

handle = dcc_mcp_photoshop.start_server(
    port=8765,     # MCP HTTP port
    ws_port=3000,  # Photoshop UXP WebSocket port
)
print(handle.mcp_url())
handle.shutdown()

Skill Authoring Guide

Photoshop skills use get_bridge() to communicate via the UXP WebSocket plugin instead of importing a DCC Python module directly.

from dcc_mcp_core.skill import skill_entry
from dcc_mcp_photoshop.api import get_bridge, with_photoshop, ps_success


@skill_entry
@with_photoshop
def list_layers(document_index: int = 0, **kwargs) -> dict:
    """List all layers in a Photoshop document."""
    bridge = get_bridge()
    layers = bridge.call("ps.listLayers", documentIndex=document_index)
    return ps_success(
        f"Found {len(layers)} layer(s)",
        count=len(layers),
        layers=[layer["name"] for layer in layers],
    )


def main(**kwargs):
    return list_layers(**kwargs)


if __name__ == "__main__":
    from dcc_mcp_core.skill import run_main
    run_main(main)

SKILL.md format

---
name: my-photoshop-skill
description: "Description of what this skill does"
dcc: photoshop
version: "1.0.0"
tags: [photoshop, layers, document]
license: "MIT"
depends: []
---

Setting skill paths

export DCC_MCP_PHOTOSHOP_SKILL_PATHS=/path/to/my/skills

UXP Plugin Protocol

The UXP plugin (JavaScript) runs inside Photoshop and implements a WebSocket server with JSON-RPC 2.0 protocol:

Request format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ps.listLayers",
  "params": {"documentIndex": 0}
}

Response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [{"name": "Background", "visible": true}]
}

Supported methods (planned):

Roadmap

v0.1.0 — Foundation (current)

• Package structure and API design

• PhotoshopBridge WebSocket client scaffold

• Skill authoring helpers

• UXP plugin architecture design

v0.2.0 — UXP Plugin + Bridge

• UXP plugin WebSocket server (JavaScript)

• Python bridge WebSocket client

• JSON-RPC 2.0 protocol implementation

• Authentication and security

v0.3.0 — Document Skills

• get_document_info skill

• list_documents skill

• list_layers skill

• create_layer skill

• export_document skill

v0.4.0 — Advanced Skills

• apply_filter skill

• color_adjustment skill

• selection_tool skill

• smart_object skill

v1.0.0 — Production Ready

• Smart Object support

• Batch processing

• Photoshop 2025+ UXP API compatibility

• Performance optimizations

Contributing

This project is especially looking for contributors with:

• Adobe UXP / ExtendScript experience

• Photoshop automation knowledge

• WebSocket and JSON-RPC protocol experience

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.