Chapter 2 Use an agent to operate Photoshop

Reading note

This chapter is for users who can already describe requirements in natural language. Its goal is to connect an agent so it can operate Photoshop directly. Once connected, ask it to inspect images, organize layers, change text, adjust the image and export files, then request further changes based on the result. The main skills are connection and use.

Choose a connection method

There are two routes: Photoshop's built-in assistant or an external agent:

• Official Photoshop AI Assistant: type requests inside Photoshop without setting up MCP yourself. At the time of verification, Adobe still labeled the desktop feature an early-access Photoshop (Beta) feature. Install Photoshop (Beta) through Creative Cloud, open an image and click the AI Assistant icon at the upper right to start a conversation. Availability depends on your current version and account. Official overview and entry point
• External agent + MCP: chat in an AI client that supports local MCP tools; a connector sends the operations to Photoshop. Here, MCP is an interface through which the agent calls Photoshop tools. Choose either project below.

The following instructions are for Windows. Choose one external route; both are third-party projects with their own version requirements and operation limits.

Route A: drmedia/photoshop-mcp (UXP plugin)

1. Prepare the environment

You need Git, Node.js 22.12 or later, Photoshop and Adobe UXP Developer Tool. The project declares Photoshop 25.0 as its minimum; the author records testing with 27.8. Complete macOS validation is still missing, so this section uses Windows. Project requirements

Install UXP Developer Tool through Creative Cloud. On first launch, follow the instructions to enable Developer Mode and allow loading development plugins. Adobe installation guide

2. Download and build the project

This example installs to C:/AI/Tools. Run the following in PowerShell:

New-Item -ItemType Directory -Path C:/AI/Tools -Force
Set-Location C:/AI/Tools
git clone https://github.com/drmedia/photoshop-mcp.git
Set-Location C:/AI/Tools/photoshop-mcp
npm install
npm run build

The build generates the files needed by the server and plugin. At verification time, the project had not been published to npm; install from source. Build instructions, release status

3. Load the plugin in Photoshop

1. Start Photoshop and UXP Developer Tool.
2. Select Add Plugin in the developer tool and locate C:/AI/Tools/photoshop-mcp/photoshop-uxp/manifest.json.
3. Click Load, then open the Photoshop MCP panel through Photoshop's Plugins menu.

Keep Photoshop and the plugin panel open while configuring the AI client. Plugin loading instructions

4. Add the MCP server to the agent client

The client must support starting a local stdio MCP server. For example, in Claude Desktop, open %APPDATA%\Claude\claude_desktop_config.json and add the server entry below. If other servers already exist, merge this entry into the existing mcpServers object.

{
  "mcpServers": {
    "photoshop-uxp": {
      "command": "node",
      "args": [
        "C:/AI/Tools/photoshop-mcp/packages/mcp-server/bin/photoshop-mcp.js"
      ],
      "env": {
        "PHOTOSHOP_MCP_BRIDGE": "uxp",
        "PHOTOSHOP_MCP_PROFILE": "full",
        "PHOTOSHOP_MCP_ALLOW": "read,edit,external",
        "PHOTOSHOP_MCP_EXTENSIONS_ENABLED": "none"
      }
    }
  }
}

Replace the installation path with your actual path, save and restart the client. The client starts the configured server; do not run another npm start instance manually.

These settings select the real UXP bridge, expose the full Photoshop tool set, allow reading and editing plus Save As / export operations, and disable extensions not needed here. The default permission is read,edit; this example adds external for saving and exporting. Overwriting original files belongs to a different permission level and is not included. Project launch configuration, environment variables and permissions, Claude Desktop configuration location

For other agents, use the same command, arguments and environment variables in that client's configuration format. For example, in VS Code, run MCP: Add Server → Command (stdio) from the command palette. Clients may use mcpServers or servers as their top-level field; do not interchange them. Official VS Code connection guide

5. Connect the plugin and choose an output folder

Return to the Photoshop MCP panel and click Connect. Loading the plugin does not connect it automatically, so this is a separate step. Once connected, the panel shows bridge status and the port. It searches local ports 8765–8774 by default; you usually do not need to enter a port. Connection behavior

For saving or exporting, select and authorize an output folder in the panel yourself. The agent then supplies a filename such as poster-v1.psd, which is written there. This project does not accept arbitrary full output paths chosen by the agent. Output folder and saving rules

Route B: airtaxi/PhotoshopMcpServer (Windows COM)

This route controls Photoshop through Windows COM without the UXP plugin above. It requires Windows, Photoshop with COM automation and DoJavaScript support, and .NET 10 SDK or later. See the project documentation for installation and client configuration.

1. Download and publish the executable

Run in PowerShell:

New-Item -ItemType Directory -Path C:/AI/Tools -Force
Set-Location C:/AI/Tools
git clone https://github.com/airtaxi/PhotoshopMcpServer.git
Set-Location C:/AI/Tools/PhotoshopMcpServer
dotnet publish PhotoshopMcpServer/PhotoshopMcpServer.csproj -c Release -r win-x64 --self-contained

Publishing builds the project. With its current directory structure and target framework, the executable is at the location used below. Publish steps, target framework

2. Configure the client and connect

Again using Claude Desktop, add this server entry to its configuration:

{
  "mcpServers": {
    "photoshop-com": {
      "command": "C:/AI/Tools/PhotoshopMcpServer/PhotoshopMcpServer/bin/Release/net10.0-windows/win-x64/publish/PhotoshopMcpServer.exe"
    }
  }
}

Use your actual path, save, restart the client and open Photoshop. Other agents can use the same executable as the command for a local stdio server. Executable connection example

The project provides tools for reading documents, querying layers and exporting; it also lets the agent write and execute Photoshop JavaScript. Describe everyday tasks directly; you do not need to write scripts first. Tool list

Verify the connection

Open a test image in Photoshop, enable the relevant MCP tools in the agent client and enter:

Actually call the Photoshop tools to read the current document's name, width, height and layer names. Query only; do not make changes yet.

Compare the returned information with the open document and confirm that the client shows actual tool calls. The UXP route has document and layer query tools; the COM route can use GetActiveDocumentInfo and GetLayerInfo. A server configuration or a chat message saying “connected” is not sufficient evidence. UXP tool reference, COM tool reference

Then verify a small edit:

Create a blank layer at the top of the current document named “Connection test.” Query the layers again and report its name and position.

Finally, test Save As and export, and confirm the files actually appear in the selected folder. With the UXP route, enter:

Save the current document as connect-test-v1.psd, preserving layers, and export connect-test-v1.png. Use the folder I selected in the Photoshop MCP panel and report the result for each file.

These three steps verify reading, editing and file output separately. Once complete, proceed to everyday conversation-based operation.

Give tasks after connecting

If you can already write prompts, describe the object, requested changes, content to preserve and deliverables. For example:

Change the text layer named “Title” in the current poster to “Autumn arrivals,” preserving the font, size and position. Save the result as poster-v1.psd and export poster-v1.png.

After seeing the result, continue with “split the title into two lines,” “make the whole image brighter” or “adjust only the background.” When objects are unclear, ask the agent to query the layers first. With UXP, you can also request a screenshot and use it to guide changes.

Available operations depend on the selected tools. Reading and adjusting layers or placing an existing background are different from calling Generative Fill. Check the tool list and test whether a new background or a particular AI feature is actually supported.

Common connection problems

Resources and configurations were checked on October 31, 2026, against Adobe and client documentation and the two projects' source documentation. This section has not been installed and acceptance-tested in local Photoshop.