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

Install the UXP plugin from bridge/uxp-plugin/ (pending implementation)
Open Photoshop
Go to Plugins > Browse Plugins
Install from local manifest
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):

| Method | Description | |--------|-------------| | ps.executeScript | Execute JavaScript/UXP code | | ps.getDocumentInfo | Get active document metadata | | ps.listDocuments | List all open documents | | ps.listLayers | List layers in active document | | ps.createLayer | Create a new layer | | ps.applyFilter | Apply a filter to a layer | | ps.exportDocument | Export document to file |

Roadmap

v0.1.0 — Foundation (current)

[x] Package structure and API design
[x] PhotoshopBridge WebSocket client scaffold
[x] 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.

MCP Servers