dcc-mcp-photoshop

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It does not update a running dcc-mcp-server; update that server in its own environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type photoshop
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type photoshop before retrying. For post-task improvement, attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the review_skill_improvement prompt from dcc-mcp-skills-creator.

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

Quick Start

Prerequisites

Follow the cross-platform Install SOP. It documents the pinned official adobepy CLI checksum release, env-only token contract, Adobe-signed Photoshop product attestation, and the currently blocked bounded UXP bootstrap.

1. Choose an installation path

For an Internal deployment with an approved prebuilt UXP bridge, use the studio's approved deployment tooling to create the Adobe debug-plugin link. The current dcc-mcp-cli install contract does not accept bridge source or debug-root arguments, so do not pass undocumented --plugin-source or --adobe-debug-root options. Skip dcc-mcp-photoshop install --json --yes for this path; it generates and owns a different bridge lifecycle.

After the approved link is created, restart Photoshop and wait for the bridge to load before running dcc-mcp-cli list, dcc-mcp-cli wait-ready --dcc-type photoshop, and dcc-mcp-photoshop verify --json. A filesystem link alone is not live readiness.

For non-Internal deployments, install and use the adapter-owned lifecycle:

python -m pip install dcc-mcp-photoshop
dcc-mcp-photoshop install --json --dry-run
dcc-mcp-photoshop install --json --yes

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 instances use OS-assigned ports; 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 named Photoshop Actions for advanced automation.

photoshop-adjustment

Channel operations and low-level batchPlay access.

Runtime Features

Canonical Installer

The dcc-mcp-photoshop CLI is the only lifecycle owner. The legacy photoshop-setup skill and PowerShell script remain discoverable compatibility routes, but they delegate operators to the same contract.

load_skill("photoshop-setup")

Tools

See install.md for the standard verbs, flags, JSON schema, exit codes, three-platform host paths, repair behavior, receipt-only uninstall, and verify-to-usable acceptance gate.

Installation

Use the canonical Install SOP for host integration. Installing a wheel alone does not load the UXP bridge or prove Photoshop readiness.

PyPI

pip install dcc-mcp-photoshop

Or via uvx:

uvx --with dcc-mcp-photoshop dcc-mcp-photoshop --gateway-port 9765

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

adobepy UXP Bridge

The canonical lifecycle uses the approved adobepy CLI through env-only authentication, stages the generated bridge, commits a redacted receipt, and then requires a real Photoshop RPC. See install.md; direct bridge generation is not a second supported installer surface.

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.

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": {
        "type": "http",
        "url": "http://127.0.0.1:9765/mcp"
      }
    }
  }
}

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 --skill-paths /path/to/my/skills

CLI Reference

dcc-mcp-photoshop [OPTIONS]

Options:
  --mcp-port PORT     Optional fixed MCP instance port (default: OS-assigned)
  --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(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)
• dcc-mcp-cli list — discover direct instance URLs

UXP Bridge Setup

The UXP bridge template is part of adobepy, while the canonical lifecycle owns its safe generation and receipt:

dcc-mcp-photoshop install --json --yes

This stages receipt-owned bridge files only. The canonical agent lifecycle does not automate UXP Developer Tool or treat an adobepy doctor call as installation progress. It remains fail-closed until the bounded Photoshop bootstrap/load contract in dcc-mcp/adobepy#67 is available, then continues with dcc-mcp-photoshop verify --json.

For human-controlled development only, outside the Install SOP readiness claim:

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.20.14, < 0.21.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-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 2022+ (min version 23.0.0) is running
2. Run dcc-mcp-photoshop status --json, then follow its single structured next step
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.