Skip to content
Back to search

photoshop-python-api-mcp-server

A Model Context Protocol (MCP) server that interfaces with Adobe Photoshop's Python API. Enables LLMs to execute image editing operations, automate workflows, and manage Photoshop tasks through structured commands and context-aware interactions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/loonghao--photoshop-python-api-mcp-server/badge.svg)](/listings/loonghao--photoshop-python-api-mcp-server)

HTML

<a href="/listings/loonghao--photoshop-python-api-mcp-server"><img src="/api/listings/loonghao--photoshop-python-api-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 199 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Photoshop MCP Server
  2. [![PyPI Version](https://img.shields.io/pypi/v/photoshop-mcp-server.svg)](https://pypi.org/project/photoshop-mcp-server/)
  3. [![PyPI Downloads](https://img.shields.io/pypi/dm/photoshop-mcp-server.svg)](https://pypi.org/project/photoshop-mcp-server/)
  4. [![Build Status](https://github.com/loonghao/photoshop-python-api-mcp-server/actions/workflows/python-publish.yml/badge.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server/actions/workflows/python-publish.yml)
  5. [![License](https://img.shields.io/github/license/loonghao/photoshop-python-api-mcp-server.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server/blob/main/LICENSE)
  6. [![Python Version](https://img.shields.io/pypi/pyversions/photoshop-mcp-server.svg)](https://pypi.org/project/photoshop-mcp-server/)
  7. [![Platform](https://img.shields.io/badge/platform-windows-lightgrey.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server)
  8. [![GitHub stars](https://img.shields.io/github/stars/loonghao/photoshop-python-api-mcp-server.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server/stargazers)
  9. [![GitHub issues](https://img.shields.io/github/issues/loonghao/photoshop-python-api-mcp-server.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server/issues)
  10. [![GitHub last commit](https://img.shields.io/github/last-commit/loonghao/photoshop-python-api-mcp-server.svg)](https://github.com/loonghao/photoshop-python-api-mcp-server/commits/main)
  11. > **⚠️ WINDOWS ONLY**: This server only works on Windows operating systems due to its dependency on Windows-specific COM interfaces.
  12. A Model Context Protocol (MCP) server for Photoshop integration using photoshop-python-api.
  13. English | [简体中文](README_zh.md)
  14. ## Overview
  15. 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.
  16. ![Photoshop MCP Server Demo](assets/ps-mcp.gif)
  17. ### What Can It Do?
  18. With this MCP server, AI assistants can:
  19. - Create, open, and save Photoshop documents
  20. - Create and manipulate layers (text, solid color, etc.)
  21. - Get information about the Photoshop session and documents
  22. - Apply effects and adjustments to images
  23. - And much more!
  24. ## Requirements
  25. ### System Requirements
  26. - **🔴 WINDOWS OS ONLY**: This server ONLY works on Windows operating systems
  27. - The server relies on Windows-specific COM interfaces to communicate with Photoshop
  28. - macOS and Linux are NOT supported and CANNOT run this software
  29. ### Software Requirements
  30. - **Adobe Photoshop**: Must be installed locally (tested with versions CC2017 through 2024)
  31. - **Python**: Version 3.10 or higher
  32. ## Installation
  33. > **Note**: Remember that this package only works on Windows systems.
  34. ```bash
  35. # Install using pip
  36. pip install photoshop-mcp-server
  37. # Or using uv
  38. uv install photoshop-mcp-server
  39. ```
  40. ## MCP Host Configuration
  41. 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.).
  42. The recommended way to configure the server is using `uvx` as the command, which is the official standard format.
  43. ### Standard Configuration (Recommended)
  44. Add the following to your MCP host configuration (works with Claude Desktop, Windsurf, Cline, and other MCP hosts):
  45. ```json
  46. {
  47. "mcpServers": {
  48. "photoshop": {
  49. "command": "uvx",
  50. "args": ["--python", "3.10", "photoshop-mcp-server"],
  51. "env": {
  52. "PS_VERSION": "2024"
  53. }
  54. }
  55. }
  56. }
  57. ```
  58. ### Configuration Options
  59. - **PS_VERSION**: Specify the Photoshop version to connect to (e.g., "2024", "2023", "2022", etc.)
  60. - **command**: Use `uvx` for the standard approach
  61. - **args**: Use `["photoshop-mcp-server"]` to run the Photoshop MCP server
  62. - To specify a Python version explicitly, use `["--python", "3.10", "photoshop-mcp-server"]` (any version from 3.10 to 3.14 is supported)
  63. ## Key Features
  64. ### Available Resources
  65. - `photoshop://info` - Get Photoshop application information
  66. - `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.
  67. - `photoshop://document/layers` - Get layers in the active document
  68. ### Available Tools
  69. The server provides various tools for controlling Photoshop:
  70. - **Document Tools**: Create, open, and save documents
  71. - **Layer Tools**: Create text layers, solid color layers, etc.
  72. - **Session Tools**: Get information about Photoshop session, active document, selection
  73. - **Script Tools**: Run arbitrary Photoshop JavaScript (JSX) with `photoshop_execute_jsx`
  74. ### `photoshop_execute_jsx`
  75. A universal escape hatch: it runs any Photoshop JavaScript (ExtendScript/JSX) snippet, so you can reach
  76. parts of the Photoshop API that the dedicated tools above do not cover (channels, paths, history states,
  77. filters, custom automation, batch operations, ...).
  78. - **Supported scripts**: any Photoshop JavaScript the running Photoshop version accepts. Photoshop's
  79. ExtendScript engine is based on ECMAScript 3, so stick to ES3 syntax (`var`, no arrow functions, no
  80. `let`/`const`). A `JSON.stringify` polyfill is injected automatically, so `JSON.stringify(...)` works
  81. even though the engine has no native `JSON` object.
  82. - **Script type**: pass the script body as a single string. Return a value with an explicit `return`
  83. statement, or leave the last expression as the result.
  84. - **Return value**: `{ "success": true, "result": <script output> }` on success, and
  85. `{ "success": false, "error": <message> }` on failure. A script that throws inside Photoshop and
  86. a Photoshop instance that cannot be reached at all both report `success: false`, so callers never
  87. have to inspect the payload to tell the two apart.
  88. Examples:
  89. ```javascript
  90. // Count art layers in the active document
  91. app.activeDocument.artLayers.length;
  92. ```
  93. ```javascript
  94. // Get every layer name as JSON
  95. var doc = app.activeDocument;
  96. var names = [];
  97. for (var i = 0; i < doc.artLayers.length; i++) {
  98. names.push(doc.artLayers[i].name);
  99. }
  100. JSON.stringify(names);
  101. ```
  102. > **Note**: The script runs with the same privileges as the Photoshop UI, so it can modify or destroy the
  103. > active document. Save your work before running destructive automation.
  104. ## Example Prompts for AI Assistants
  105. 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:
  106. ### Basic Examples
  107. ```text
  108. User: Can you create a new Photoshop document and add a text layer with "Hello World"?
  109. AI Assistant: I'll create a new document and add the text layer for you.
  110. [The AI uses the Photoshop MCP server to:
  111. 1. Create a new document using the `create_document` tool
  112. 2. Add a text layer using the `create_text_layer` tool with the text "Hello World"]
  113. I've created a new Photoshop document and added a text layer with "Hello World".
  114. ```
  115. ### More Advanced Examples
  116. ```text
  117. User: Open my latest PSD file and tell me how many layers it has.
  118. AI Assistant: I'll check your latest PSD file and count the layers.
  119. [The AI uses the Photoshop MCP server to:
  120. 1. Get information about open documents
  121. 2. If no document is open, it can browse and open a PSD file
  122. 3. Retrieve and analyze the layer structure]
  123. Your document has 12 layers, including 3 group folders and 2 adjustment layers.
  124. ```
  125. ```text
  126. User: Create a social media post with a gradient background and the text "Summer Sale" in a bold font.
  127. AI Assistant: I'll create that social media post for you.
  128. [The AI uses the Photoshop MCP server to:
  129. 1. Create a new document with appropriate dimensions for social media
  130. 2. Create a gradient fill layer with summer colors
  131. 3. Add a text layer with "Summer Sale" in a bold font
  132. 4. Position and style the text appropriately]
  133. I've created your social media post with a gradient background and bold "Summer Sale" text.
  134. ```
  135. ## License
  136. MIT
  137. ## Acknowledgements
  138. - [photoshop-python-api](https://github.com/loonghao/photoshop-python-api) - Python API for Photoshop
  139. - [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk) - MCP Python SDK

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.