Photoshop MCP

🚀 Photoshop MCP Server

这是一个模型上下文协议（MCP）服务器，它能让Claude和Cursor等AI助手以编程方式控制Adobe Photoshop。借助它，你可以在IDE中通过自然语言命令来创建设计、处理图像以及自动化Photoshop工作流程。

🎨 50多种工具 | 🖥️ 跨平台支持 | 📦 支持NPX | 🔧 ExtendScript API | ⏮️ 撤销/重做

🚀 快速开始

本项目是一个非官方、由社区维护的项目，与Adobe Inc.没有关联，也未得到其认可。

安装

使用NPX（推荐）

无需安装！只需配置你的MCP客户端：

npx @alisaitteke/photoshop-mcp

从源代码安装

git clone https://github.com/yourusername/photoshop-mcp.git
cd photoshop-mcp
npm install
npm run build

配置

对于Cursor

添加到你的Cursor设置（.cursor/config.json 或工作区设置）：

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "LOG_LEVEL": "1"
      }
    }
  }
}

对于Claude Desktop

添加到你的Claude Desktop配置（在macOS上为 ~/Library/Application Support/Claude/claude_desktop_config.json，在Windows上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "LOG_LEVEL": "1"
      }
    }
  }
}

环境变量

• PHOTOSHOP_PATH：（可选）指定自定义的Photoshop安装路径
• LOG_LEVEL：日志级别（0=调试，1=信息，2=警告，3=错误）

✨ 主要特性

• ✅ 跨平台支持：同时适用于Windows和macOS。
• ✅ 广泛的Photoshop版本支持：支持Photoshop 2012 - 2025+。
• ✅ ExtendScript API：通过AppleScript/COM自动化实现通用兼容性。
• ✅ 自动检测：自动查找系统上的Photoshop安装位置。
• ✅ 丰富的工具集：提供50多种工具，实现全面的Photoshop自动化。
• ✅ 文档管理：支持创建、打开、保存、关闭和裁剪文档。
• ✅ 图层操作：可创建、删除、复制、合并和变换图层。
• ✅ 图层属性设置：能设置图层的不透明度、混合模式、可见性和锁定状态。
• ✅ 文本格式化：可控制字体、字号、颜色和对齐方式。
• ✅ 图像放置：支持放置图像、打开文件并适配文档。
• ✅ 滤镜应用：提供高斯模糊、锐化、添加杂色、动感模糊等滤镜。
• ✅ 颜色调整：可进行亮度/对比度、色相/饱和度、自动色阶/对比度等调整。
• ✅ 选区和蒙版操作：支持矩形选区和图层蒙版。
• ✅ 历史记录控制：可进行撤销/重做操作并查看历史状态。
• ✅ 动作执行：可播放录制的动作和执行自定义脚本。
• ✅ 自动栅格化：在需要应用滤镜时自动转换图层。
• ✅ 上下文跟踪：每次操作后返回文档/图层状态，便于AI感知上下文。

📦 安装指南

使用NPX（推荐）

无需安装！只需配置你的MCP客户端：

npx @alisaitteke/photoshop-mcp

从源代码安装

git clone https://github.com/yourusername/photoshop-mcp.git
cd photoshop-mcp
npm install
npm run build

💻 使用示例

基础用法

创建一个简单的设计

// 1. 创建一个新文档
photoshop_create_document({
  width: 800,
  height: 600,
  colorMode: "RGB"
})

// 2. 创建一个背景图层
photoshop_create_layer({ name: "Background" })

// 3. 用颜色填充它
photoshop_fill_layer({
  red: 240,
  green: 240,
  blue: 255
})

// 4. 添加一个文本图层
photoshop_create_text_layer({
  text: "My Design",
  x: 400,
  y: 300,
  fontSize: 64
})

// 5. 保存结果
photoshop_save_document({
  path: "/Users/username/Desktop/design.psd",
  format: "PSD"
})

批量处理图像

// 1. 打开现有文档（手动步骤）
// 2. 调整图像大小
photoshop_resize_image({ width: 1920, height: 1080 })

// 3. 保存为JPEG
photoshop_save_document({
  path: "/Users/username/Desktop/resized.jpg",
  format: "JPEG",
  quality: 12
})

// 4. 关闭文档
photoshop_close_document({ save: false })

使用Pexels MCP创建带有素材图片的设计

// 1. 在Pexels上搜索图片（使用Pexels MCP服务器）
// 注意：你需要配置Pexels MCP服务器
pexels_photos_search({
  query: "nature landscape",
  per_page: 5
})

// 2. 下载你想要的图片（手动或通过脚本）
// 3. 创建一个新的Photoshop文档
photoshop_create_document({
  width: 1920,
  height: 1080,
  colorMode: "RGB"
})

// 4. 放置下载的图片
photoshop_place_image({
  filePath: "/Users/username/Downloads/pexels-photo.jpg",
  x: 0,
  y: 0
})

// 5. 将图片适配到文档（新增！）
photoshop_fit_layer_to_document({
  fillDocument: true  // 填充整个画布
})

// 6. 添加文本覆盖
photoshop_create_text_layer({
  text: "Beautiful Nature",
  x: 960,
  y: 100,
  fontSize: 72
})

// 7. 保存最终设计
photoshop_save_document({
  path: "/Users/username/Desktop/nature-design.psd",
  format: "PSD"
})

📚 详细文档

可用工具

连接与信息

• photoshop_ping：测试与Photoshop的连接。

// 示例：检查Photoshop是否可访问
photoshop_ping()

• photoshop_get_version：获取Photoshop版本信息。

// 示例：获取版本详情
photoshop_get_version()

文档管理

• photoshop_create_document：创建一个新的Photoshop文档。

// 示例：创建一个1920x1080的RGB文档
photoshop_create_document({
  width: 1920,
  height: 1080,
  resolution: 72,
  colorMode: "RGB"
})

• photoshop_get_document_info：获取活动文档的信息。

// 示例：获取当前文档详情
photoshop_get_document_info()

• photoshop_save_document：保存活动文档。

// 示例：保存为JPEG
photoshop_save_document({
  path: "/Users/username/Desktop/output.jpg",
  format: "JPEG",
  quality: 10
})

• photoshop_close_document：关闭活动文档。

// 示例：不保存关闭
photoshop_close_document({ save: false })

图层操作

• photoshop_create_layer：创建一个新图层。

// 示例：创建一个命名图层
photoshop_create_layer({ name: "Background" })

• photoshop_delete_layer：删除活动图层。

// 示例：删除当前图层
photoshop_delete_layer()

• photoshop_create_text_layer：创建一个文本图层。

// 示例：创建一个文本图层
photoshop_create_text_layer({
  text: "Hello World",
  x: 200,
  y: 150,
  fontSize: 48
})

• photoshop_fill_layer：用纯色填充活动图层。

// 示例：用蓝色填充
photoshop_fill_layer({
  red: 0,
  green: 100,
  blue: 255
})

• photoshop_get_layers：获取活动文档中所有图层的列表。

// 示例：列出所有图层
photoshop_get_layers()

• photoshop_set_layer_opacity：设置活动图层的不透明度。

// 示例：将不透明度设置为75%
photoshop_set_layer_opacity({ opacity: 75 })

• photoshop_set_layer_blend_mode：设置活动图层的混合模式。

// 示例：将混合模式设置为正片叠底
photoshop_set_layer_blend_mode({ blendMode: "MULTIPLY" })

• photoshop_set_layer_visibility：显示或隐藏活动图层。

// 示例：隐藏图层
photoshop_set_layer_visibility({ visible: false })

• photoshop_set_layer_locked：锁定或解锁活动图层。

// 示例：锁定图层
photoshop_set_layer_locked({ locked: true })

• photoshop_rename_layer：重命名活动图层。

// 示例：重命名图层
photoshop_rename_layer({ name: "Hero Image" })

• photoshop_duplicate_layer：复制活动图层。

// 示例：复制图层并命名
photoshop_duplicate_layer({ newName: "Background Copy" })

• photoshop_merge_visible_layers：将所有可见图层合并为一个。

// 示例：合并可见图层
photoshop_merge_visible_layers()

• photoshop_flatten_image：将所有图层合并为一个背景图层。

// 示例：合并图像
photoshop_flatten_image()

• photoshop_rasterize_layer：将活动图层栅格化（将文本/智能对象转换为普通图层）。

// 示例：栅格化图层
photoshop_rasterize_layer()

图层排序

• photoshop_move_layer_to_position：相对于另一个图层移动活动图层。

// 示例：将图层移动到“Background”上方
photoshop_move_layer_to_position({
  targetLayerName: "Background",
  position: "ABOVE"
})

• photoshop_move_layer_to_top：将活动图层移动到图层堆栈的顶部。

// 示例：移动到顶部
photoshop_move_layer_to_top()

• photoshop_move_layer_to_bottom：将活动图层移动到图层堆栈的底部。

// 示例：移动到底部
photoshop_move_layer_to_bottom()

• photoshop_move_layer_up：将活动图层向上移动一个位置。

// 示例：向上移动
photoshop_move_layer_up()

• photoshop_move_layer_down：将活动图层向下移动一个位置。

// 示例：向下移动
photoshop_move_layer_down()

图层变换

• photoshop_fit_layer_to_document：缩放活动图层以适应文档画布，同时保持纵横比。

// 示例：将图层适配到画布内
photoshop_fit_layer_to_document({ fillDocument: false })

// 示例：填充整个画布（必要时裁剪）
photoshop_fit_layer_to_document({ fillDocument: true })

• photoshop_scale_layer：按百分比缩放活动图层。

// 示例：缩放至150%
photoshop_scale_layer({
  scalePercent: 150,
  centerAnchor: true
})

• photoshop_move_layer：按指定偏移量移动活动图层。

// 示例：将图层向右移动100px，向下移动50px
photoshop_move_layer({
  deltaX: 100,
  deltaY: 50
})

• photoshop_rotate_layer：旋转活动图层。

// 示例：顺时针旋转45度
photoshop_rotate_layer({ degrees: 45 })

滤镜

• photoshop_apply_gaussian_blur：对活动图层应用高斯模糊滤镜。

// 示例：应用10px模糊
photoshop_apply_gaussian_blur({ radius: 10 })

• photoshop_apply_sharpen：应用锐化滤镜。

// 示例：锐化图像
photoshop_apply_sharpen({
  amount: 100,
  radius: 1.5,
  threshold: 0
})

• photoshop_apply_noise：应用添加杂色滤镜。

// 示例：添加杂色
photoshop_apply_noise({
  amount: 10,
  distribution: "GAUSSIAN",
  monochromatic: false
})

• photoshop_apply_motion_blur：应用动感模糊滤镜。

// 示例：应用动感模糊
photoshop_apply_motion_blur({
  angle: 45,
  radius: 20
})

颜色调整

• photoshop_adjust_brightness_contrast：调整亮度和对比度。

// 示例：增加亮度和对比度
photoshop_adjust_brightness_contrast({
  brightness: 20,
  contrast: 15
})

• photoshop_adjust_hue_saturation：调整色相、饱和度和亮度。

// 示例：调整颜色
photoshop_adjust_hue_saturation({
  hue: 30,
  saturation: 20,
  lightness: 0
})

• photoshop_auto_levels：应用自动色阶调整。

// 示例：自动色阶
photoshop_auto_levels()

• photoshop_auto_contrast：应用自动对比度调整。

// 示例：自动对比度
photoshop_auto_contrast()

• photoshop_desaturate：将图层去饱和（转换为灰度）。

// 示例：去饱和
photoshop_desaturate()

• photoshop_invert：反转图层的颜色。

// 示例：反转颜色
photoshop_invert()

文本格式化

• photoshop_set_text_font：为活动文本图层设置字体和字号。

// 示例：更改字体
photoshop_set_text_font({
  fontName: "Helvetica",
  fontSize: 48
})

• photoshop_set_text_color：为活动文本图层设置颜色。

// 示例：将文本设置为蓝色
photoshop_set_text_color({
  red: 0,
  green: 100,
  blue: 255
})

• photoshop_set_text_alignment：设置文本对齐方式。

// 示例：将文本居中对齐
photoshop_set_text_alignment({ alignment: "CENTER" })

• photoshop_update_text_content：更新活动文本图层的文本内容。

// 示例：更新文本
photoshop_update_text_content({ text: "New Text" })

选区和蒙版

• photoshop_select_rectangle：创建一个矩形选区。

// 示例：选择区域
photoshop_select_rectangle({
  left: 100,
  top: 100,
  right: 500,
  bottom: 400
})

• photoshop_select_all：选择整个文档。

// 示例：全选
photoshop_select_all()

• photoshop_deselect：清除所有选区。

// 示例：取消选择
photoshop_deselect()

• photoshop_invert_selection：反转当前选区。

// 示例：反转选区
photoshop_invert_selection()

• photoshop_create_layer_mask：根据当前选区创建一个图层蒙版。

// 示例：创建蒙版
photoshop_create_layer_mask()

• photoshop_delete_layer_mask：从活动图层中删除图层蒙版。

// 示例：删除蒙版
photoshop_delete_layer_mask()

• photoshop_apply_layer_mask：将图层蒙版应用（合并）到图层。

// 示例：应用蒙版
photoshop_apply_layer_mask()

历史记录与撤销/重做

• photoshop_undo：撤销上一个操作（相当于Ctrl/Cmd+Z）。

// 示例：撤销上一个操作
photoshop_undo()

// 示例：撤销上3个操作
photoshop_undo({ steps: 3 })

• photoshop_redo：重做之前撤销的操作（相当于Ctrl/Cmd+Shift+Z）。

// 示例：重做上一个撤销的操作
photoshop_redo()

// 示例：重做上2个撤销的操作
photoshop_redo({ steps: 2 })

• photoshop_get_history：获取活动文档的历史状态。

// 示例：查看历史记录
photoshop_get_history()

动作与自动化

• photoshop_play_action：播放动作面板中录制的动作。

// 示例：播放动作
photoshop_play_action({
  actionName: "My Action",
  actionSetName: "Default Actions"
})

• photoshop_execute_script：执行自定义ExtendScript代码（高级）。

// 示例：执行自定义代码
photoshop_execute_script({
  code: "app.beep();"
})

图像操作

• photoshop_resize_image：调整活动图像的大小。

// 示例：调整为Instagram帖子大小
photoshop_resize_image({
  width: 1080,
  height: 1080
})

• photoshop_crop_document：将文档裁剪到指定边界。

// 示例：裁剪文档
photoshop_crop_document({
  left: 100,
  top: 100,
  right: 1820,
  bottom: 980
})

• photoshop_place_image：将图像文件作为图层放置在活动文档中。

// 示例：在指定位置放置图像
photoshop_place_image({
  filePath: "/Users/username/Pictures/photo.jpg",
  x: 100,
  y: 200
})

• photoshop_open_image：将图像文件作为新文档打开。

// 示例：打开图像
photoshop_open_image({
  filePath: "/Users/username/Pictures/photo.jpg"
})

示例提示

以下是在配置此MCP服务器后，你可以与AI助手（Claude、Cursor等）一起使用的示例提示：

创建一个1920x1080的Photoshop文档，颜色模式为RGB。
添加一个浅蓝色背景图层，并用RGB(240, 248, 255)填充。
添加居中的文本“Welcome”，字体大小为64pt。
保存为welcome.psd到桌面。

在Pexels上搜索“mountain sunset”图片。
创建一个1920x1080的Photoshop文档。
放置下载的图片并使其填充整个画布。
应用3px的轻微高斯模糊。
将亮度增加15，对比度增加10。
在顶部居中添加白色文本“Adventure Awaits”，字体大小为72pt。
将文本不透明度设置为90%，混合模式设置为叠加。
以质量10保存为adventure.jpg。

在Photoshop中打开桌面上的photo.jpg。
应用自动色阶和自动对比度。
应用锐化滤镜，数量为120%，半径为1.5，阈值为0。
将饱和度增加15。
裁剪图像，各边缘去除100px。
以质量12保存为enhanced-photo.jpg。

创建一个1200x800的文档。
添加一个名为“Background”的新图层，并用RGB(50, 50, 50)填充。
在位置(100, 100)放置logo.png。
将logo图层缩放至当前大小的50%。
将混合模式设置为滤色，不透明度设置为85%。
添加另一个图层，用RGB(255, 100, 50)填充。
将此图层的混合模式设置为正片叠底，不透明度设置为60%。
合并所有可见图层。
保存为composite.psd。

创建一个1080x1350的竖版文档（Instagram故事尺寸）。
添加一个图层，并用类似渐变的颜色RGB(120, 40, 200)填充。
在(540, 300)处添加文本“SUMMER”，字体大小为96pt。
将文本颜色更改为白色RGB(255, 255, 255)。
将文本对齐方式设置为居中。
在(540, 450)处添加另一个文本“2026”，字体大小为128pt，颜色为白色。
对背景图层应用2px的高斯模糊。
保存为summer-poster.png。

打开image1.jpg。
调整大小为1920x1080。
应用自动对比度。
应用轻微锐化（数量80%，半径1.0）。
以质量10保存为processed-1.jpg。
不保存更改关闭原始文档。

对image2.jpg和image3.jpg重复上述操作。

创建一个2000x2000的正方形文档。
放置abstract-pattern.jpg并使其填充文档。
复制该图层。
在复制的图层上，应用45度、半径50px的动感模糊。
将混合模式设置为叠加，不透明度设置为70%。
添加居中的白色文本“MOTION”，字体大小为120pt。
从(200, 200)到(1800, 1800)创建一个矩形选区。
反转选区并删除（以创建边框效果）。
合并图像。
保存为motion-art.jpg。

创建一个3000x2000、分辨率为300 DPI的文档用于打印。
放置hero-image.jpg并使其填充画布。
复制图像图层。
在复制的图层上，完全去饱和。
将混合模式设置为亮度，不透明度设置为50%。
创建一个名为“Overlay”的新图层。
用RGB(255, 150, 0)填充，并将混合模式设置为柔光，不透明度设置为30%。
在顶部中心(1500, 200)处添加文本“PORTFOLIO”，字体大小为96pt。
将文本颜色设置为白色。
在(1500, 320)处添加子文本“2026 Collection”，字体大小为36pt。
围绕文本区域创建一个矩形选区。
在覆盖图层上创建一个图层蒙版。
合并可见图层。
保存为portfolio-cover.psd。
以质量12导出为portfolio-cover.jpg。

打开my-photo.jpg。
播放“My Actions”集中的“Vintage Look”动作。
将亮度调整为-10以稍微变暗。
保存为vintage-photo.jpg。

执行以下自定义ExtendScript代码：
app.beep();
alert('Processing started!');

对活动图层应用15px的高斯模糊。
[等待结果]
实际上，模糊效果太强了。撤销该操作。
改为应用5px的高斯模糊。

获取历史状态以查看执行了哪些操作。
撤销最后3个操作。
重做1步以恢复一个操作。

🔧 技术细节

上下文跟踪

每个工具都会返回有关Photoshop当前状态的全面上下文信息，包括：

• 文档信息：名称、尺寸、分辨率、颜色模式、图层数量
• 活动图层信息：名称、类型、不透明度、混合模式、可见性、锁定状态
• 选区状态：是否有活动选区
• 操作结果：关于所做更改的具体细节

这使AI助手能够了解：

• 哪个文档处于活动状态
• 正在处理哪个图层
• 当前图层属性（不透明度、混合模式等）
• 文档尺寸和设置

示例响应：

{
  "applied": true,
  "filter": "Gaussian Blur",
  "radius": 10,
  "wasRasterized": true,
  "context": {
    "hasDocument": true,
    "document": {
      "name": "design.psd",
      "width": 1920,
      "height": 1080,
      "resolution": 72,
      "colorMode": "RGBColorMode",
      "layerCount": 3,
      "hasSelection": false
    },
    "activeLayer": {
      "name": "Background",
      "kind": "NORMAL",
      "opacity": 100,
      "blendMode": "NORMAL",
      "visible": true,
      "locked": false,
      "isBackground": false
    }
  }
}

此上下文有助于AI助手在多个命令中记住正在处理的文档和图层。

平台特定说明

Windows

• 使用COM自动化与Photoshop通信。
• 基于注册表自动检测安装路径。
• 支持32位和64位版本。

macOS

• 使用AppleScript/OSA与Photoshop通信。
• 基于Spotlight自动检测。
• 支持同时安装多个Photoshop版本。

支持的Photoshop版本

• 所有Photoshop版本（2012 - 2025+）：通过AppleScript（macOS）或COM（Windows）使用ExtendScript API。

重要提示：虽然Photoshop 2022+支持UXP用于插件，但通过AppleScript/COM进行的外部自动化只能使用ExtendScript。UXP是为内部插件设计的，无法从外部脚本调用。因此，此MCP服务器使用ExtendScript以确保在所有Photoshop版本上的最大兼容性。

架构

photoshop-mcp/
├── src/
│   ├── core/              # MCP服务器核心
│   │   ├── server.ts      # 主MCP服务器
│   │   ├── session.ts     # 会话管理
│   │   └── tool-registry.ts  # 工具注册系统
│   ├── platform/          # 特定平台的检测与执行
│   │   ├── detector.ts    # 主检测器
│   │   ├── connection.ts  # 连接管理器
│   │   ├── windows-detector.ts  # Windows注册表检测
│   │   ├── windows-executor.ts  # Windows COM自动化
│   │   ├── macos-detector.ts    # macOS Spotlight检测
│   │   └── macos-executor.ts    # macOS AppleScript执行
│   ├── api/              # Photoshop API抽象
│   │   ├── photoshop-api.ts    # API工厂
│   │   ├── batch-play.ts       # UXP batchPlay助手（旧版）
│   │   └── extendscript.ts     # ExtendScript代码片段库
│   ├── tools/            # MCP工具实现（42+工具）
│   │   ├── document-tools.ts        # 文档操作
│   │   ├── layer-tools.ts           # 图层创建/删除
│   │   ├── layer-properties-tools.ts # 不透明度、混合模式等
│   │   ├── layer-transform-tools.ts  # 缩放、旋转、移动
│   │   ├── image-tools.ts           # 调整大小、裁剪
│   │   ├── image-placement-tools.ts # 放置/打开图像
│   │   ├── filter-tools.ts          # 模糊、锐化、杂色
│   │   ├── adjustment-tools.ts      # 颜色调整
│   │   ├── text-tools.ts            # 文本格式化
│   │   ├── selection-tools.ts       # 选区和蒙版
│   │   └── action-tools.ts          # 动作和自定义脚本
│   └── utils/            # 实用工具
│       └── logger.ts     # 日志系统（基于标准错误输出）
└── examples/             # 配置示例
    ├── cursor-config.json
    └── claude-desktop-config.json

📄 许可证

本项目采用MIT许可证。

致谢

• 基于Model Context Protocol SDK构建。
• 受Adobe Photoshop脚本社区的启发。

贡献

欢迎贡献代码！请随时提交拉取请求。

故障排除

"未找到Photoshop"

1. 确保Photoshop安装在默认位置。
2. 或者设置 PHOTOSHOP_PATH 环境变量为自定义安装路径。

{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

"无法连接到Photoshop"

1. 确保Photoshop正在运行（如果未运行，服务器将尝试启动它）。
2. 检查Photoshop首选项中是否启用了脚本功能。
3. 在Windows上，验证COM自动化是否未被安全设置阻止。

"脚本执行超时"

• 某些操作在处理大型文档时可能需要更长时间。
• 默认超时时间为30秒。
• 对于复杂操作，考虑将其拆分为更小的步骤。

调试日志

通过设置 LOG_LEVEL=0 启用详细日志记录：

{
  "env": {
    "LOG_LEVEL": "0"
  }
}

开发

构建

npm run build

监听模式

npm run dev

代码检查与格式化

npm run lint
npm run format

快速开始示例

💡 常见用例