Photoshop MCP Server

Photoshop MCP 服务

一个用于驱动 Adobe Photoshop 的 MCP 服务：管理文档、图像和画布大小、图层和组、选区、调整和滤镜、文字、导出和历史记录。它运行在安装了 Photoshop 的计算机上，并通过 Photoshop 自带的脚本接口 ExtendScript 与其通信。

需要在 macOS 或 Windows 上使用 Photoshop 2023 或更高版本，以及 Node.js 18 或更高版本。

安装

Claude Code：

claude mcp add photoshop -- npx -y adobe-mcp-photoshop

任何可读取 mcpServers 块的客户端（Claude Desktop、Cursor、Warp，……）：

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "adobe-mcp-photoshop"]
    }
  }
}

在 macOS 上，首次调用时会请求获得控制 Photoshop 的权限（系统设置 > 隐私与安全性 > 自动化）。

约定

• 位置和大小的单位为像素，以文档左上角为原点测量，y 值向下递增，无论使用何种标尺单位。
• 图层通过 target 选择：{ ids: [...] }、{ names: [...] } 或 { active: true }。Id 是 Photoshop 自有的图层 ID，可通过 list_layers 以及每个创建图层的工具获取。
• 颜色使用 "#RRGGBB"、"rgb(r,g,b)"、"cmyk(c,m,y,k)"、"gray(g)"、"hsb(h,s,b)" 或 "lab(L,a,b)" 格式。
• 调整、滤镜、填充和描边会更改像素图层；如果存在选区，则仅在选区内生效。
• 时间轴时间使用 { seconds, frames }，帧速率为时间轴的帧速率。
• 字体使用 PostScript 名称；可通过 list_fonts 查找。
• 文件必须位于主目录或 PHOTOSHOP_ALLOWED_DIRS 中的目录内。

工具

区域	工具
文档	list_documents、get_document_info、create_document（设置像素长宽比，或创建画板）、open_document（打开 Photoshop 可读取的任何格式；可选择作为智能对象打开；PDF、EPS、Photoshop Raw 和 DICOM 支持各自的打开选项）、save_document（PSD、PSB、TIFF、PNG、JPEG、PDF、GIF、EPS、DCS 1.0 和 2.0、BMP、Targa、Pixar 或 Photoshop Raw，并可设置各格式的选项；也可保存副本）、duplicate_document、set_active_document、close_document、set_colors（前景色和背景色）
文件	manage_recent_files（列出、打开、清除）、close_documents（全部关闭）、go_to_bridge、get_document_metadata 和 set_document_metadata（文件信息和 XMP）、manage_document_notes（导入、清除、注释工具、注释面板）、set_file_handling_preferences（图像预览、最近使用的文件、历史记录日志）、place_file（置入嵌入对象或链接对象，并设置位置、缩放和旋转）
图像	resize_image（图像大小：像素、百分比、分辨率、重新采样）、resize_canvas（设置画布大小和锚点）、crop_image、trim_image、rotate_canvas（或翻转）、change_mode（颜色模式和位深度）、convert_profile、flatten_image（或合并可见图层）、reveal_all
图层	list_layers、create_layer（像素图层或组）、set_layer_properties（名称、不透明度、填充、混合模式、可见性、锁定）、set_active_layer、arrange_layers、group_layers、ungroup_layers、duplicate_layers、delete_layers、merge_layers、transform_layers（移动、缩放、旋转、翻转）、rasterize_layers、link_layers、convert_background_layer、layer_comps
选区	select_area（矩形、椭圆或多边形，并与当前选区组合）、select_all（全部、无、反选）、modify_selection（扩展、收缩、羽化、平滑、边框、扩大、选取相似）、transform_selection、fill_selection、stroke_selection、save_selection（保存到 Alpha 通道或从 Alpha 通道载入）、clipboard（复制、合并拷贝、剪切、清除、粘贴、贴入）
调整和滤镜	adjust_layers（亮度/对比度、色阶、曲线、曝光度、自然饱和度、色相/饱和度、色彩平衡、黑白、照片滤镜、通道混合器、渐变映射、可选颜色、阴影/高光、色调分离、阈值、去色、反相、均衡、自动色调、自动对比度、自动颜色）、apply_filter（模糊、锐化、高反差保留、杂色、中间值、蒙尘与划痕、最大值、最小值、扭曲、位移、云彩等）
调整和填充图层	create_adjustment_layer（创建任意调整类型，并设置其参数；可选择创建剪贴图层）、edit_adjustment_layer、create_fill_layer（纯色、渐变或图案）、edit_fill_layer
颜色	swap_colors（或重置为黑色和白色）、pick_color（支持各种颜色模式的数值和 Web 安全色）、sample_color（吸管工具和颜色取样器）、define_pattern、assign_profile、set_color_preferences（颜色设置、动态滑块、色域警告不透明度）、set_proof_view（校样设置、校样颜色、色域警告）
选区	select_area（矩形、椭圆或多边形，并与当前选区组合）、select_all（全部、无、反选）、modify_selection（扩展、收缩、羽化、平滑、边框、扩大、选取相似）、transform_selection、fill_selection、stroke_selection、save_selection（保存到 Alpha 通道或从 Alpha 通道载入）、clipboard（复制、合并拷贝、剪切、清除、粘贴、贴入、原位粘贴、贴到外部）
调整和滤镜	adjust_layers（亮度/对比度、色阶、曲线、色彩平衡、照片滤镜、阴影/高光、色调分离、阈值、去色、反相、均衡、自动色阶、自动对比度）、apply_filter（模糊、锐化、高反差保留、杂色、中间值、蒙尘与划痕、最大值、最小值、扭曲、位移、云彩等）
绘画和修饰	fill_contents（编辑 > 填充：前景色、背景色、黑色、50% 灰色、白色、图案、历史记录、内容识别，以及脚本图案“砖块填充”“交叉编织”“沿路径放置”“随机填充”和“对称填充”）、draw_gradient（带颜色和不透明度色标的经典渐变）、stroke_path（沿路径使用画笔、铅笔、橡皮擦、仿制图章、修复画笔、图案图章、减淡、加深等工具绘画）、fill_path、fill_at_point（油漆桶、魔棒橡皮擦）、set_tool_options（工具、画笔预设、大小、硬度、不透明度、流量、模式、压力按钮、平滑及其选项、混合器画笔湿润和混合、容差、连续、绘画光标）、set_brush_settings（画笔设置面板：笔尖形状、形状动态、散布、纹理、双重画笔、颜色动态、传递、画笔姿势和各复选框）、manage_brushes（导入、导出、定义画笔预设、新建、重命名、删除和重置预设）、set_clone_source_options（仿制源面板：源、重置变换、叠加选项）、retouch_selection（修补、内容识别移动）
调整和滤镜	adjust_layers（亮度/对比度、色阶、曲线、色彩平衡、照片滤镜、阴影/高光、色调分离、阈值、去色、反相、均衡、自动色阶、自动对比度、自动颜色校正选项、匹配颜色、替换颜色）、apply_filter（模糊、锐化、高反差保留、杂色、中间值、蒙尘与划痕、最大值、最小值、扭曲、位移、云彩、镜头校正、自适应广角、滤镜库等）
绘画和修饰	fill_contents（编辑 > 填充：前景色、背景色、黑色、50% 灰色、白色、图案、历史记录、内容识别）、draw_gradient（带颜色和不透明度色标的经典渐变）、stroke_path（沿路径使用画笔、铅笔、橡皮擦、仿制图章、修复画笔、减淡、加深等工具绘画）、fill_path、fill_at_point（油漆桶、魔棒橡皮擦）、set_tool_options（工具、画笔预设、大小、硬度、不透明度、流量、绘画光标）、manage_brushes（导入、导出、定义画笔预设）、retouch_selection（修补、内容识别移动）
文字	create_text_layer（点文本或段落文本）、set_text（文本、格式、位置、变形）、list_fonts
视频和动画	get_timeline、create_timeline（视频时间轴或帧动画，或进行转换）、set_timeline（时间轴面板、帧速率、播放头、动画选项）、run_timeline_command（移动和修剪、拆分、工作区域、关键帧、洋葱皮、视频图层帧）、edit_frame_animation（新建、删除、复制、粘贴、反转和补间帧；将帧转换为图层或将图层转换为帧）、add_video_layer、import_video_frames、set_clip_timing（入点和出点、时长）、add_video_transition、render_video
历史记录	list_history、undo（后退、前进或转到某个状态）、make_snapshot、edit_history（还原、删除或清除状态；从某个状态新建文档；设置历史记录画笔源；清理）、set_history_options（历史记录选项和历史记录日志）
自动化	list_action_sets、edit_actions（新建组、删除、清除、重置、载入或保存 .atn）、set_action_options（播放选项、按钮模式、工具录制）、run_action_batch（批处理）、create_droplet、run_automate_command（裁剪并拉直照片、适合图像、条件模式更改、镜头校正、删除所有空图层、拼合所有图层效果、拼合所有蒙版）、combine_images（将文件载入堆栈、Photomerge、合并到 HDR Pro、统计）、manage_script_events（脚本事件管理器）、manage_data_sets（导入、应用和导出变量数据组）
画板	get_artboards、create_artboard（新建、从图层创建、从组创建，或创建画板文档）、edit_artboards（大小、位置、背景、自动嵌套、复制、取消编组、参考线、画板和画框工具）、create_frame（从图层或组创建）、export_artboards（导出为文件或一个 PDF）
导出	export_image（存储为 Web 所用格式：PNG、PNG-8、JPEG、GIF；可选择调整大小）、export_layers（每个图层或组导出为一个文件）、quick_export（导出文档或所选图层）、export_layer_comps（导出为文件或一个 PDF）、export_paths_to_illustrator、make_pdf_presentation（多页 PDF 或幻灯片放映）、generate_image_assets（Generator 资源图层名称、默认图层、开启或关闭）
打印	get_print_options、set_print_options（打印机、份数、颜色处理和分色、打印空间、位置和缩放、标记、函数）、print_image（使用当前设置打印，或打印一份）、apply_trap
历史记录	list_history、undo（后退、前进或转到某个状态）、make_snapshot
应用程序	get_photoshop_info（版本、内存、系统信息、文件类型、功能检查）、get_photoshop_preferences、set_photoshop_preferences（常规、界面和颜色主题、文件处理、性能、光标、透明度、单位和标尺、参考线和网格、增效工具、文字、脚本对话框）、purge_photoshop_caches、run_photoshop_command（蜂鸣、置于前台、刷新、隐藏、帮助、帐户）、run_photoshop_menu_item、manage_script_options（保留各会话间的值）、quit_photoshop
界面	arrange_photoshop_windows（平铺、2 至 6 个窗口并排、选项卡、浮动、匹配缩放和位置）、set_zoom_and_screen_mode、toggle_view_extras（额外内容、显示项目、标尺、对齐、锁定）、show_photoshop_panels（显示或隐藏面板、“基本功能”工作区、直方图和信息面板选项）、select_view_tool、edit_photoshop_guides（添加、参考线版面、从形状创建、清除参考线或切片）
Camera Raw	open_raw_file（Camera Raw 设置和工作流程选项）、apply_camera_raw_settings（Camera Raw 滤镜：基本、曲线、细节、颜色混合器、颜色分级、光学、效果、蒙版）、apply_neural_filter（景深模糊、风格迁移、照片修复）、replace_sky、remove_background
生成式功能	generative_fill、generate_image、harmonize_layer（需要 Adobe 帐户和互联网连接；使用生成式积分）
实用工具	photoshop_status、play_action、execute_photoshop_code、help
help({ tool }) 可查看任意工具的参数说明。

如何避免打扰你

• 不弹出对话框。 每个脚本运行时都会关闭 displayDialogs，因此命令会使用自身的设置，而不会等待你点击，并会在之后恢复原设置，即使脚本失败也一样。
• 单位会恢复原样。 脚本使用像素，并在之后恢复你的标尺和文字单位设置。
• 导出不会改动文档。 export_image 和 export_layers 会在临时副本上操作，并将其关闭。
• 超时会说明原因。 如果 Photoshop 在 PHOTOSHOP_SCRIPT_TIMEOUT_MS（默认 120 s）指定的时间内未响应，错误会提示 Photoshop 中可能打开了对话框。
• 脚本中不包含原始输入。 调用方传入的每个值都会经过验证，并作为字面值写入脚本。

配置

变量	用途
PHOTOSHOP_APP_NAME	macOS：指定要访问的某个副本，例如 Adobe Photoshop 2025。默认情况下，服务会通过 Photoshop 的 bundle id 进行访问。
PHOTOSHOP_ALLOWED_DIRS	打开、保存和导出文件时可用的额外目录（macOS 使用 : 分隔，Windows 使用 ; 分隔）。
PHOTOSHOP_SCRIPT_TIMEOUT_MS	等待 Photoshop 的时长。默认值为 120000。
PHOTOSHOP_BACKEND / PHOTOSHOP_TARGET	设置为 artcraft 或 photocraft，即可通过 loopback JSON-lines 将工具调用路由到 PhotoCraft。默认值为 auto（当 Adobe Photoshop 未运行且 PhotoCraft 正在端口 7878 上监听时，路由到 PhotoCraft）。
PHOTOCRAFT_CONTROL_PORT	PhotoCraft 控制通道的端口。默认值为 7878。
PHOTOCRAFT_CONTROL_TOKEN	如有需要，用于 PhotoCraft 身份验证的令牌。

开发

npm test         # definitions, argument parsing, protocol, and the static script audit
npm run audit    # the audit alone, with findings listed
npm run check    # syntax check

审计会使用示例参数对每个工具运行一次，并通过 stubbed executor 检查生成的每个脚本是否符合 Photoshop 的脚本对象模型（types-for-adobe，Photoshop 2015.5）。目前尚未在 Photoshop 本身中进行验证。