Photoshop MCP Server

Photoshop MCP 服务

⚠️ 仅限 WINDOWS：由于依赖 Windows 专属的 COM 接口，此服务只能在 Windows 操作系统上运行。

一个使用 photoshop-python-api 实现 Photoshop 集成的模型上下文协议（MCP）服务。

English | 简体中文

概述

此项目在模型上下文协议（MCP）与 Adobe Photoshop 之间搭建桥梁，让 AI 助手和其他 MCP 客户端能够以编程方式控制 Photoshop。

它能做什么？

借助此 MCP 服务，AI 助手可以：

• 创建、打开和保存 Photoshop 文档
• 创建和操作图层（文本、纯色等）
• 获取 Photoshop 会话和文档的信息
• 为图像应用效果和调整
• 还有更多功能！

要求

系统要求

• 🔴 仅限 WINDOWS 操作系统：此服务只能在 Windows 操作系统上运行
  • 此服务依赖 Windows 专属的 COM 接口与 Photoshop 通信
  • 不支持 macOS 和 Linux，且无法在这些系统上运行此软件

软件要求

• Adobe Photoshop：必须在本机安装（已使用 CC2017 至 2024 版本进行测试）
• Python：版本 3.10 或更高

安装

注意：请记住，此软件包只能在 Windows 系统上运行。

# Install using pip
pip install photoshop-mcp-server

# Or using uv
uv install photoshop-mcp-server

MCP 宿主配置

此服务旨在与各种 MCP 宿主配合使用。PS_VERSION 环境变量用于指定要连接的 Photoshop 版本（例如“2024”、“2023”、“2022”等）。

建议使用 uvx 作为命令来配置服务，这是官方标准格式。

标准配置（推荐）

将以下内容添加到 MCP 宿主配置中（适用于 Claude Desktop、Windsurf、Cline 和其他 MCP 宿主）：

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

配置选项

• PS_VERSION：指定要连接的 Photoshop 版本（例如“2024”、“2023”、“2022”等）
• command：使用 uvx 作为标准方式
• args：使用 ["photoshop-mcp-server"] 运行 Photoshop MCP 服务
  • 要显式指定 Python 版本，请使用 ["--python", "3.10", "photoshop-mcp-server"]（支持 3.10 至 3.14 的任意版本）

主要功能

可用资源

• photoshop://info - 获取 Photoshop 应用信息
• photoshop://document/info - 获取活动文档信息（名称、宽度、高度、分辨率、图层数量）。当 Photoshop 无法报告文档尺寸时，width/height 为 0.0，并会添加额外的 dimensions_unavailable: true 字段，标明尺寸不可读取，而非实际为零。photoshop_open_document 会报告相同的信号。
• photoshop://document/layers - 获取活动文档中的图层

可用工具

该服务提供各种用于控制 Photoshop 的工具：

• 文档工具：创建、打开和保存文档
• 图层工具：创建文本图层、纯色图层等
• 会话工具：获取 Photoshop 会话、活动文档和选区的信息
• 脚本工具：通过 photoshop_execute_jsx 运行任意 Photoshop JavaScript（JSX）

photoshop_execute_jsx

通用的扩展入口：它可以运行任意 Photoshop JavaScript（ExtendScript/JSX）代码片段，因此你可以访问上述专用工具未涵盖的 Photoshop API 部分（通道、路径、历史记录状态、滤镜、自定义自动化、批处理操作等）。

• 支持的脚本：当前运行的 Photoshop 版本接受的任何 JavaScript。Photoshop 的 ExtendScript 引擎基于 ECMAScript 3，因此请使用 ES3 语法（var，不要使用箭头函数、let/const）。系统会自动注入 JSON.stringify polyfill，因此即使引擎没有原生的 JSON 对象，JSON.stringify(...) 也能正常使用。
• 脚本类型：将脚本正文作为单个字符串传入。使用显式的 return 语句返回值，或将最后一个表达式作为结果。
• 返回值：成功时返回 { "success": true, "result": <script output> }，失败时返回 { "success": false, "error": <message> }。在 Photoshop 中抛出异常的脚本和完全无法连接的 Photoshop 实例都会报告 success: false，因此调用方无需检查载荷来区分两者。

示例：

// 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);

注意：脚本拥有与 Photoshop UI 相同的权限，因此可以修改或破坏活动文档。运行具有破坏性的自动化操作前，请先保存工作。

面向 AI 助手的示例提示词

在 MCP 主机中完成配置后，你可以在 AI 助手对话中使用 Photoshop MCP 服务。以下是一些示例提示词，可帮助你开始使用：

基本示例

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".

更高级的示例

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.

许可证

MIT

致谢

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