Photoshop MCP Server

Photoshop MCP Server

⚠️ WINDOWS ONLY: This server only works on Windows operating systems due to its dependency on Windows-specific COM interfaces.

A Model Context Protocol (MCP) server for Photoshop integration using photoshop-python-api.

English | 简体中文

Overview

This project provides a bridge between the Model Context Protocol (MCP) and Adobe Photoshop, allowing AI assistants and other MCP clients to control Photoshop programmatically.

What Can It Do?

With this MCP server, AI assistants can:

• Create, open, and save Photoshop documents
• Create and manipulate layers (text, solid color, etc.)
• Get information about the Photoshop session and documents
• Apply effects and adjustments to images
• And much more!

Requirements

System Requirements

• 🔴 WINDOWS OS ONLY: This server ONLY works on Windows operating systems
  • The server relies on Windows-specific COM interfaces to communicate with Photoshop
  • macOS and Linux are NOT supported and CANNOT run this software

Software Requirements

• Adobe Photoshop: Must be installed locally (tested with versions CC2017 through 2024)
• Python: Version 3.10 or higher

Installation

Note: Remember that this package only works on Windows systems.

# Install using pip
pip install photoshop-mcp-server

# Or using uv
uv install photoshop-mcp-server

MCP Host Configuration

This server is designed to work with various MCP hosts. The PS_VERSION environment variable is used to specify which Photoshop version to connect to (e.g., "2024", "2023", "2022", etc.).

The recommended way to configure the server is using uvx as the command, which is the official standard format.

Standard Configuration (Recommended)

Add the following to your MCP host configuration (works with Claude Desktop, Windsurf, Cline, and other MCP hosts):

{
  "mcpServers": {
    "photoshop": {
      "command": "uvx",
      "args": ["--python", "3.10", "photoshop-mcp-server"],
      "env": {
        "PS_VERSION": "2024"
      }
    }
  }
}

Configuration Options

• PS_VERSION: Specify the Photoshop version to connect to (e.g., "2024", "2023", "2022", etc.)
• command: Use uvx for the standard approach
• args: Use ["photoshop-mcp-server"] to run the Photoshop MCP server
  • To specify a Python version explicitly, use ["--python", "3.10", "photoshop-mcp-server"] (any version from 3.10 to 3.14 is supported)

Key Features

Available Resources

• photoshop://info - Get Photoshop application information
• photoshop://document/info - Get active document information (name, width, height, resolution, layers count). When Photoshop does not report the document dimensions, width/height are 0.0 and an extra dimensions_unavailable: true field marks them as unreadable rather than genuinely zero. photoshop_open_document reports the same signal.
• photoshop://document/layers - Get layers in the active document

Available Tools

The server provides various tools for controlling Photoshop:

• Document Tools: Create, open, and save documents
• Layer Tools: Create text layers, solid color layers, etc.
• Session Tools: Get information about Photoshop session, active document, selection
• Script Tools: Run arbitrary Photoshop JavaScript (JSX) with photoshop_execute_jsx

photoshop_execute_jsx

A universal escape hatch: it runs any Photoshop JavaScript (ExtendScript/JSX) snippet, so you can reach parts of the Photoshop API that the dedicated tools above do not cover (channels, paths, history states, filters, custom automation, batch operations, ...).

• Supported scripts: any Photoshop JavaScript the running Photoshop version accepts. Photoshop's ExtendScript engine is based on ECMAScript 3, so stick to ES3 syntax (var, no arrow functions, no let/const). A JSON.stringify polyfill is injected automatically, so JSON.stringify(...) works even though the engine has no native JSON object.
• Script type: pass the script body as a single string. Return a value with an explicit return statement, or leave the last expression as the result.
• Return value: { "success": true, "result": <script output> } on success, and { "success": false, "error": <message> } on failure. A script that throws inside Photoshop and a Photoshop instance that cannot be reached at all both report success: false, so callers never have to inspect the payload to tell the two apart.

Examples:

// Count art layers in the active document
app.activeDocument.artLayers.length;

// Get every layer name as JSON
var doc = app.activeDocument;
var names = [];
for (var i = 0; i < doc.artLayers.length; i++) {
    names.push(doc.artLayers[i].name);
}
JSON.stringify(names);

Note: The script runs with the same privileges as the Photoshop UI, so it can modify or destroy the active document. Save your work before running destructive automation.

Example Prompts for AI Assistants

Once configured in your MCP host, you can use the Photoshop MCP server in your AI assistant conversations. Here are some example prompts to get you started:

Basic Examples

User: Can you create a new Photoshop document and add a text layer with "Hello World"?

AI Assistant: I'll create a new document and add the text layer for you.

[The AI uses the Photoshop MCP server to:
1. Create a new document using the `create_document` tool
2. Add a text layer using the `create_text_layer` tool with the text "Hello World"]

I've created a new Photoshop document and added a text layer with "Hello World".

More Advanced Examples

User: Open my latest PSD file and tell me how many layers it has.

AI Assistant: I'll check your latest PSD file and count the layers.

[The AI uses the Photoshop MCP server to:
1. Get information about open documents
2. If no document is open, it can browse and open a PSD file
3. Retrieve and analyze the layer structure]

Your document has 12 layers, including 3 group folders and 2 adjustment layers.

User: Create a social media post with a gradient background and the text "Summer Sale" in a bold font.

AI Assistant: I'll create that social media post for you.

[The AI uses the Photoshop MCP server to:
1. Create a new document with appropriate dimensions for social media
2. Create a gradient fill layer with summer colors
3. Add a text layer with "Summer Sale" in a bold font
4. Position and style the text appropriately]

I've created your social media post with a gradient background and bold "Summer Sale" text.

License

MIT

Acknowledgements

• photoshop-python-api - Python API for Photoshop
• Model Context Protocol - MCP Python SDK