dcc-mcp-photoshop

Bring Adobe Photoshop to MCP-native AI agents.

dcc-mcp-photoshop turns Photoshop into a standards-compliant MCP Streamable HTTP backend via the adobepy Rust broker and UXP bridge. Agents can inspect documents, create and edit layers, apply text, filters, smart objects, selections, export images, and automate Photoshop workflows through typed tools instead of brittle ad-hoc scripts.

The Python MCP server communicates with Photoshop through the adobepy Rust broker (port 47391), which proxies between the Python SDK and the UXP bridge running inside Photoshop.

Why Use It

Related MCP server: Photoshop MCP Server

Quick Start

Prerequisites

1. adobepy broker — Install and start the Rust broker:

   cargo install adobepy-cli
   adobepy broker

2. adobepy UXP bridge — Install in Photoshop:

   adobepy install-bridge photoshop

1. Install dcc-mcp-photoshop

2. Configure your MCP client

Point your MCP client to the gateway URL. The gateway auto-discovers which DCC (Photoshop, Maya, etc.) to route each tool call to, so you only need one endpoint:

{
  "mcpServers": {
    "photoshop": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

3. Smoke test

Search for Photoshop tools, load the photoshop-document skill, and list layers in the current document.

Architecture

AI Agent (Claude Desktop / Cursor / Copilot)
    │  MCP Streamable HTTP (gateway port 9765)
    ▼
dcc-mcp-server Gateway
    │  auto-discovers DCC via capability index
    ▼
PhotoshopMcpServer  [Python sidecar]
    │  HTTP JSON-RPC (port 47391)
    ▼
adobepy Rust Broker  [adobepy broker]
    │  WebSocket (port 47391)
    ▼
adobepy UXP Bridge  [bridges/uxp/photoshop/, TypeScript]
    │  Photoshop UXP API
    ▼
Adobe Photoshop 2022+

Key architectural decisions:

• The adobepy Rust broker (port 47391) is the central hub — Python SDK and UXP bridge both connect to it.

• Python MCP server runs independently (port 8765); skill scripts use adobe.photoshop.Photoshop() facade to call the broker.

• The adobepy UXP bridge (bridges/uxp/photoshop/) handles all Photoshop DOM operations with 60+ typed methods.

• All Photoshop automation goes through the adobepy facade layer, which abstracts over the broker.

Tool Surface

Skills are lazy-loaded: only meta-tools are available initially. Use load_skill to expand:

search_skills / dcc_capability_manifest
  -> load_skill("photoshop-document")
  -> list_layers(...)

photoshop-document

Document information, listing, and lifecycle management.

photoshop-image

Document creation, export, canvas/image resize, flatten, and merge operations.

photoshop-layers

Full CRUD for layers plus visual property changes.

photoshop-text

Text layer creation, editing, and inspection.

photoshop-selection

Selection creation, modification, and saving.

photoshop-filter

Apply filters to layers.

photoshop-smart-object

Smart Object operations for non-destructive editing.

photoshop-script

Execute scripts and actions for advanced automation.

photoshop-adjustment

Channel operations and low-level batchPlay access.

Runtime Features

One-Click Installer

The photoshop-setup skill provides a complete installer workflow that automates environment checks, package installation, UXP plugin setup, and MCP client configuration.

load_skill("photoshop-setup")

Tools

Standard Install Flow

check_environment → install_package → setup_uxp_plugin → configure_mcp_client → verify_connection

1. check_environment — Verifies Python, pip, and Photoshop are available.

2. install_package — Installs dcc-mcp-photoshop and dependencies from PyPI.

3. setup_uxp_plugin — Installs the .ccx plugin into Photoshop.

4. configure_mcp_client — Sets up mcpServers entries for Claude Desktop, Cursor, and VS Code.

5. verify_connection — Confirms the bridge is connected and Photoshop responds.

Installing a Specific Version

Pin to a specific version for compatibility with your existing dcc-mcp-core deployment:

install_package(version="0.1.14")

Upgrading

Upgrade dcc-mcp-photoshop and its dependencies to the latest version on PyPI:

install_package(upgrade=True)

Rolling Back

Install a previous version to roll back from a regression. The UXP plugin version must match the Python package version:

install_package(version="0.1.13")

Uninstalling

Remove the Python package via pip:

pip uninstall dcc-mcp-photoshop

Remove the UXP plugin from Creative Cloud Desktop → Plugins → Manage Plugins, or delete the .ccx from the UXP plugins directory:

# Windows
Remove-Item "$env:APPDATA\Adobe\UXP\Plugins\External\dcc-mcp-photoshop-bridge-*.ccx"

# macOS
rm ~/Library/Application\ Support/Adobe/UXP/Plugins/External/dcc-mcp-photoshop-bridge-*.ccx

Installation

PyPI

pip install dcc-mcp-photoshop

Install with sidecar dependencies (recommended for the default plugin gateway mode):

pip install "dcc-mcp-photoshop[sidecar]"

Or via uvx:

uvx --with dcc-mcp-photoshop dcc-mcp-photoshop --embedded

From source:

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

Standalone Binary

Each GitHub Release includes platform-specific binaries built with PyOxidizer. No Python runtime required.

# Download the latest release binary (example: Linux)
curl -LO https://github.com/dcc-mcp/dcc-mcp-photoshop/releases/latest/download/dcc-mcp-photoshop-linux
chmod +x dcc-mcp-photoshop
./dcc-mcp-photoshop --help

UXP .ccx Plugin

Install the .ccx into Photoshop if you only need the UXP sidecar:

1. Download the .ccx from the latest release assets

2. Open Creative Cloud Desktop → Plugins → Manage Plugins

3. Click the gear icon → Install from file...

4. Select the downloaded .ccx file

5. Restart Photoshop

Manual install:

# Windows
copy dcc-mcp-photoshop-bridge-*.ccx "$env:APPDATA\Adobe\UXP\Plugins\External\"

# macOS
cp dcc-mcp-photoshop-bridge-*.ccx ~/Library/Application\ Support/Adobe/UXP/Plugins/External/

Configuration

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "photoshop": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

The gateway URL (:9765) is a unified facade that aggregates tools from all registered DCCs. On tools/call, the gateway auto-discovers the correct DCC instance via the capability index — no need to specify the DCC type in the URL.

Embedded mode via command:

{
  "mcpServers": {
    "photoshop": {
      "command": "dcc-mcp-photoshop",
      "args": ["--embedded"],
      "env": {}
    }
  }
}

Cursor

In Cursor Settings → Features → MCP Servers:

Name: photoshop
Type: url
URL: http://127.0.0.1:9765/mcp

VS Code (via MCP extension)

{
  "mcp": {
    "servers": {
      "photoshop": {
        "command": "dcc-mcp-photoshop",
        "args": ["--embedded"]
      }
    }
  }
}

Environment Variables

Bridge Protocol

The Python ↔ Photoshop communication goes through the adobepy Rust broker using the adobepy protocol (v0.2.0). The broker handles JSON-RPC 2.0 routing, session management, and timeout control.

For protocol details, see the adobepy protocol contract.

Skill Authoring

Skills use the adobepy facade layer:

from adobe.dcc_mcp import action_result
from adobe.photoshop import Photoshop
from dcc_mcp_core.skill import skill_entry


@skill_entry
def list_layers(**kwargs) -> dict:
    """List all layers in the active Photoshop document."""
    app = Photoshop()
    return action_result(
        "Listed active Photoshop layers",
        lambda: {"layers": [layer.name for layer in app.activeLayers]},
        prompt="Use the layer names in the next Photoshop operation.",
    )


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


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

Skill directory structure

skills/
├── photoshop-document/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-image/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-layers/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-text/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-selection/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-filter/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-smart-object/
│   ├── SKILL.md
│   └── scripts/
├── photoshop-script/
│   ├── SKILL.md
│   └── scripts/
└── photoshop-adjustment/
    ├── SKILL.md
    └── scripts/

Setting custom skill paths

export DCC_MCP_PHOTOSHOP_SKILL_PATHS=/path/to/my/skills
dcc-mcp-photoshop --embedded --skill-paths /path/to/my/skills

CLI Reference

dcc-mcp-photoshop [OPTIONS]

Options:
  --mcp-port PORT     MCP HTTP server port (default: 8765)
  --broker-url URL    adobepy broker URL (default: http://127.0.0.1:47391)
  --gateway-port PORT Gateway competition port
  --server-name NAME  Server name in MCP initialize (default: photoshop-mcp)
  --skill-paths PATH  Extra skill directories
  --no-builtins       Do not discover built-in skills
  --verbose, -v       Enable debug logging
  --version           Show version and exit

Python API

import dcc_mcp_photoshop

handle = dcc_mcp_photoshop.start_server(port=8765, broker_url="http://127.0.0.1:47391")
print(f"MCP URL: {handle.mcp_url()}")

# ... use with Claude Desktop, Cursor, etc.

handle.shutdown()

Ports

Gateway Mode (Recommended for Deployment)

This mode uses the standalone dcc-mcp-server for the MCP server with the adobepy broker as the Photoshop communication layer.

Terminal 1 — Start the adobepy broker:

adobepy broker

Terminal 2 — Start the MCP server:

dcc-mcp-photoshop --broker-url http://127.0.0.1:47391

MCP clients connect to the gateway URL:

• http://127.0.0.1:9765/mcp — Gateway proxy (recommended)

• http://127.0.0.1:8765/mcp — Direct access

UXP Bridge Setup

The UXP bridge is part of the adobepy project. To install:

adobepy install-bridge photoshop

This copies the bridge files to Photoshop's UXP plugins directory. Restart Photoshop to load the bridge.

For development, load from source:

1. Open Photoshop

2. Go to Plugins → Development → Load Plugin...

3. Navigate to adobepy's bridges/uxp/photoshop/ and select manifest.json

Bridge manifest

The bridge manifest is at bridges/uxp/photoshop/manifest.json in the adobepy repository:

Development

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

Requirements

• Photoshop: Adobe Photoshop 2022+ (UXP support required)

• Python (pip path only): Python 3.8+

• Dependencies (auto-installed with pip):

  • dcc-mcp-core >= 0.19.17, < 1.0.0

  • adobepy >= 0.1.0

  • websockets >= 12.0

• Build (to build standalone binary from source): Python 3.8+, Rust toolchain, and PyOxidizer (pip install pyoxidizer)

Version Compatibility

Distribution

Release artifacts per version:

• dcc-mcp-photoshop-<version>-py3-none-any.whl — Python wheel

• dcc-mcp-photoshop-<version>.tar.gz — Python sdist

• dcc-mcp-photoshop-bridge-<version>.ccx — UXP plugin

• dcc-mcp-photoshop-windows.exe — Windows binary

• dcc-mcp-photoshop-linux — Linux binary

• dcc-mcp-photoshop-macos — macOS binary

Roadmap

v0.1.0 — Foundation ✅

• Package structure and API design

• PhotoshopBridge WebSocket client scaffold

• Skill authoring helpers

v0.2.0 — adobepy Integration ✅

• adobepy Rust broker integration (port 47391)

• Python SDK facade (adobe.photoshop)

• 40+ Photoshop skills across 8 packages

• Selection, filter, smart object, script, adjustment tools

• UXP code convergence (removed old bridge/uxp-plugin/)

• Configuration externalization (config.py)

v0.3.0 — Skills & Polish (next)

• Color adjustments (levels, curves, hue/saturation)

• Layer styles and effects

• Batch processing workflows

• Performance optimizations

v1.0.0 — Production Ready

• Photoshop 2025+ UXP API compatibility

• Authentication and security hardening

• E2E test coverage

Troubleshooting

Broker not reachable

adobepy broker not reachable at http://127.0.0.1:47391

1. Start the broker: adobepy broker

2. Verify the broker is running: curl http://127.0.0.1:47391/v1/capabilities

3. Check the ADOBEPY_BROKER_URL environment variable matches the broker endpoint

UXP bridge not connecting

1. Ensure Photoshop 2024+ (min version 25.0.0) is running

2. Run adobepy install-bridge photoshop and restart Photoshop

3. Check the bridge is loaded: Plugins → Adobe Python Bridge

No active document error

If skills return "No active document":

1. Open a document in Photoshop (File → New or File → Open)

2. Retry the skill call

Default ports used

Contributing

Contributions are especially welcome from those with:

• Adobe UXP / ExtendScript experience

• Photoshop automation knowledge

• WebSocket and JSON-RPC protocol experience

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.