photoshop-python-api-mcp-server

# Photoshop MCP Server [](https://pypi.org/project/photoshop-mcp-server/) [](https://pypi.org/project/photoshop-mcp-server/) [](https://github.com/loonghao/photoshop-python-api-mcp-server/actions/workflows/python-publish.yml) [](https://github.com/loonghao/photoshop-python-api-mcp-server/blob/main/LICENSE) [](https://pypi.org/project/photoshop-mcp-server/) [](https://github.com/loonghao/photoshop-python-api-mcp-server) [](https://github.com/loonghao/photoshop-python-api-mcp-server/stargazers) [](https://github.com/loonghao/photoshop-python-api-mcp-server/issues) [](https://github.com/loonghao/photoshop-python-api-mcp-server/commits/main) > **⚠️ 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 | [简体中文](README_zh.md) ## 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. ```bash # 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): ```json { "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 - `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: ```javascript // Count art layers in the active document app.activeDocument.artLayers.length; ``` ```javascript // 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 ```text 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 ```text 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. ``` ```text 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](https://github.com/loonghao/photoshop-python-api) - Python API for Photoshop - [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk) - MCP Python SDK