Photoshop MCP 安装配置与 AI 修图实战教程

Photoshop 是修图与平面设计的行业标准工具，Photoshop MCP 服务器把它变成 AI Agent 可以直接操控的软件：Agent 通过 MCP 工具在你的 Photoshop 里打开图片、调整亮度对比度、做选区、加滤镜、加水印、批量导出，全程在你本机的 Photoshop 中完成，图层可撤销、结果可保存为 PSD 或 PNG。本教程以 ZCode 为 Agent 侧主线，选用 GitHub 上星数最高的社区方案 alisaitteke/photoshop-mcp，并提供打包好的网盘离线版——下载解压即可运行，无需访问 GitHub、无需 npm 安装与编译，从解压、ZCode 的 MCP 接入配置，到「调色、加水印、导出」与「一键网页优化导出」两个实测案例，带你走通完整的 AI 修图工作流，文末附 Python 技术栈的备选方案与常见问题排查。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• MCP概念详解与应用完整教程，理解 MCP 协议、客户端、服务器与传输方式的基本概念，本教程不再展开这些基础内容。
• Node.js和Npm安装与使用教程，网盘版服务器通过 node 命令运行，依赖 Node.js 运行时。
• Blender MCP安装配置与AI建模实战教程，同为「AI 操控本机桌面软件」的实战教程，ZCode 的 MCP 配置方法与之一脉相承。
• Penpot MCP安装配置与AI设计转代码实战教程，设计领域的另一款 MCP 实战，可对照理解设计类工具的 AI 化工作流。

资源下载

• photoshop-mcp 1.7.21 网盘离线版.zip，本教程主线方案的开箱即用包：已构建、已装好运行时依赖，解压后配置 ZCode 即可使用，推荐从此处下载。
• photoshop-mcp-server 0.1.11 网盘版.zip，第 6 章 Python 备选方案的源码网盘版（Windows / Python 3.10）：仓库源码 + 全量离线依赖，解压后一条命令完成安装。
• alisaitteke/photoshop-mcp 仓库（GitHub），主线方案的源码仓库与完整工具文档，网盘离线版的来源。
• @alisaitteke/photoshop-mcp（npm），npm 包页面，在线安装方式使用。
• loonghao/photoshop-python-api-mcp-server 仓库（GitHub），备选方案的源码仓库，Python 网盘版的来源。

1. Photoshop MCP 是什么

1.1 让 AI 接管修图软件

让大模型处理图片有两条路线。一条是「生成式」路线：AI 直接生成一张新图，风格内容都由模型决定，但对既有照片的精确控制很弱。另一条是「操控软件」路线：AI 驱动你已安装的 Photoshop 完成操作，亮度调多少、水印放在哪个坐标、导出什么格式，都由你在对话中说了算。

Photoshop MCP 走的是第二条路线，它带来三个实际的好处：

1.2 工作原理：脚本桥接通道

Photoshop 从很早的版本起就内置了完整的脚本引擎（ExtendScript），本教程主线方案的核心正是这条「脚本桥接」通道：MCP 服务器收到 Agent 的工具调用后，把操作翻译成 Photoshop 脚本交给 Photoshop 执行，再把执行结果回传给 Agent，整体链路如下：

与 Blender MCP、Penpot MCP 的「宿主程序 + 插件 + 本地服务器」三层模式相比，这个方案少了一个必须手动保持连接的插件环节：服务器进程由 Agent 侧按需拉起，脚本通道由 Photoshop 自身提供，使用前提只有一个——Photoshop 处于运行状态。对于较新版本的 Photoshop，该项目还提供可选的 UXP 插件，走本地 WebSocket 通道获得更强的实时能力；不装插件时脚本通道同样可用。

1.3 两个主流方案怎么选

GitHub 上可用的 Photoshop MCP 方案主要有两个，技术路线与定位差异明显：

两个方案在本机 Photoshop CS6（13.0）上均实测连通。追求开箱即用选主线方案，工具覆盖面大一个数量级；如果团队技术栈以 Python 为主、只需要文档和图层级别的轻量操作，备选方案更合适。

1.4 版本兼容性说明

主线方案官方声明支持 2012 年及以后的 Photoshop 版本，本教程的全部实测在 Photoshop CS6（版本号 13.0）上完成，属于支持区间的下限。这意味着你手头的老版本 Photoshop 大概率可以直接使用；同时注意两类功能边界：

• 生成式填充、天空替换等 Adobe 云端 AI 功能需要登录 Adobe 账号，且部分能力仅在新版本中提供，老版本调用会受限。
• 多步一键配方（16 个 recipe 工具）中个别步骤依赖新版特性，在老版本上个别配方的个别环节可能降级或报错，遇到时把配方拆成单步工具执行即可。

2. 环境准备

2.1 安装并启动 Photoshop

本机需要已安装可正常使用的 Photoshop。启动 Photoshop 并确认能新建或打开文档即可，不需要安装任何插件，正版订阅版或手头已有的老版本均可。

2.2 安装 Node.js

主线方案要求 Node.js 18 或更高版本。按 Node.js和Npm安装与使用教程完成安装后，在终端验证：

node --version

网盘离线版已经装好全部运行时依赖，全程只需要 node 这一个命令，不需要 npm 安装与编译。

2.3 确认 ZCode 环境

本教程的 Agent 侧使用 ZCode。确认本机已安装 ZCode 并能正常启动会话；ZCode 的 MCP 配置位于用户配置文件 C:\Users\<你的用户名>\.zcode\cli\config.json 的 mcp.servers 字段下，第 4 章将直接编辑该文件。

3. 部署 Photoshop MCP 服务器

3.1 下载并解压网盘离线版

从资源下载区的网盘链接下载 photoshop-mcp-1.7.21-网盘版.zip（约 16 MB），解压到一个不含中文与空格的目录，下文以 C:\photoshop-mcp 为例。解压后你将得到如下结构：

photoshop-mcp\
├── dist\            # 已构建好的服务器产物，启动入口在这里
│   └── index.js
├── node_modules\    # 已装好的运行时依赖，无需再安装
├── src\             # TypeScript 源码，想研究实现时阅读
├── web\dist\        # 内置聊天窗口的前端产物
├── package.json
└── README.zh-CN.md  # 中文说明文档

这个包在官方 1.7.21 版本源码基础上做了两件事：完成了 tsc 编译（省去构建环节），并把运行时依赖精简到 MCP 服务器运行所需的部分（体积从约 600 MB 降到 70 MB）。被精简的只有一个依赖 @anthropic-ai/claude-agent-sdk，它只影响内置聊天窗口的「Claude 账号登录」模式，本教程的 ZCode 接入方式完全不经过这条路径，实测 125 个工具全部正常。

3.2 手动验证服务器

启动 Photoshop 后，在终端执行以下命令确认服务器可以运行：

node C:\photoshop-mcp\dist\index.js

服务正常启动时的输出如下（本教程实测记录）：

[INFO] [PhotoshopMCPServer] Registered 125 tools and 23 prompts
[INFO] [PhotoshopMCPServer] MCP Server connected via stdio
[INFO] [UxpBridgeServer] UXP bridge listening on 127.0.0.1:38452

看到 Registered 125 tools and 23 prompts 说明服务器已就绪。这一步只是验证解压完整性，确认后按 Ctrl+C 停止即可——第 4 章配置完成后，ZCode 会在需要时自动拉起这个进程，不需要你常驻手动启动。

若终端提示找不到 node 命令，回到 2.2 节确认 Node.js 已安装并重新打开终端。

3.3 在线安装备选方案

如果你习惯 npm 生态、不需要离线包，也可以用官方 npm 包直接运行，效果完全相同：

npx -y @alisaitteke/photoshop-mcp

首次运行会自动从 npm 下载依赖包，国内网络下可能等待数十秒；后续启动使用本地缓存。第 4 章的 ZCode 配置二选一即可，二者的工具与用法没有任何差别。

3.4 认识 125 个工具

125 个工具按功能可以归纳为九类，日常修图的高频工具集中在文档、图层、调整与导出四类：

23 个预置提示词（prompts）是官方为常见修图任务写好的提示模板，Agent 侧可以直接引用，也可以完全用自己的自然语言描述需求。

4. 在 ZCode 中接入 Photoshop MCP

4.1 编写 MCP 配置

编辑 ZCode 的用户配置文件 C:\Users\<你的用户名>\.zcode\cli\config.json，在其 mcp.servers 对象中追加一个名为 photoshop 的服务器条目。网盘离线版的写法（把路径换成你的实际解压路径）：

{
  "mcp": {
    "servers": {
      "photoshop": {
        "type": "stdio",
        "command": "node",
        "args": ["C:/photoshop-mcp/dist/index.js"],
        "timeoutMs": 60000
      }
    }
  }
}

如果使用 3.3 节的在线安装方式，则把 command 与 args 换成 npm 包写法：

{
  "mcp": {
    "servers": {
      "photoshop": {
        "type": "stdio",
        "command": "npx.cmd",
        "args": ["-y", "@alisaitteke/photoshop-mcp"],
        "timeoutMs": 60000
      }
    }
  }
}

配置要点：

• type: "stdio" 对应本地子进程传输，与 Blender MCP 的接入方式同类。如果配置文件中已有其他服务器条目，直接在同一个 servers 对象里并列追加即可。
• 网盘离线版的 args 路径使用正斜杠 /，指向解压目录下的 dist/index.js；两种方式按第 3 章的选择二选一。
• 在线安装方式在 Windows 下命令写 npx.cmd，macOS 与 Linux 下写 npx。
• timeoutMs 给服务器启动留出时间，避免初始化阶段超时。

保存配置后重启 ZCode，新会话开始时会自动连接该服务器。

4.2 验证连接

保持 Photoshop 处于运行状态，重启 ZCode 后打开新会话，在对话框输入：

请调用 Photoshop 工具检测连接状态，告诉我 Photoshop 是否在运行、当前打开了几个文档。

Agent 会调用 photoshop_ping 与 photoshop_get_state，会话中出现 mcp__photoshop__ 前缀的工具调用记录即代表接入成功。若提示连接失败或工具列表为空，先按 3.2 节手动启动确认服务器本身可用，再检查配置文件中的逗号与引号是否完整。

5. 实战：一句话完成修图工作流

5.1 准备练习素材

准备一张本地图片（JPG 或 PNG）放入一个练习目录，例如 C:\Users\<你的用户名>\Pictures\demo-photo.png。本章两个案例都基于这张图，教程示例图为一张 1200×800 的黄昏风景图。

5.2 案例一：调色、加水印与导出

在 ZCode 会话中输入（路径替换为你的实际路径）：

用 Photoshop 完成以下修图操作：打开 C:\Users\<你的用户名>\Pictures\demo-photo.png，
把亮度提高 15、对比度提高 20，再把饱和度提高 30，
然后在图片右下角添加文字水印 @eogee.com，
最后把结果导出为 PNG，保存到同目录下的 demo-edited.png。

Agent 会把它拆解为一串工具调用逐步执行，本教程实测的调用序列如下：

调整前后的对比效果：

整个过程中你可以在 Photoshop 界面实时看到每一步的变化；对结果不满意时，直接在 Photoshop 的历史记录面板回退，或者让 Agent 重新调整参数再导出一次。

5.3 案例二：一键网页优化导出

16 个一键配方把多步流程封装成单次调用。以网页导出为例，在 Photoshop 中打开图片后输入：

用 Photoshop 的网页优化配方，把当前打开的图片导出为适合网页使用的 JPEG。

Agent 调用 photoshop_recipe_prepare_for_web，本教程实测返回：自动按最长边 2048 像素约束尺寸、以 JPEG 质量 9 导出，输出文件保存在用户目录的 .photoshop-mcp\exports\ 文件夹下，并附带返回了下一步建议工具。其余配方（抠背景、人像增强、社交平台多尺寸导出、批量水印等）用法相同，直接用自然语言点名配方要做什么即可。

5.4 实用使用习惯

三个习惯能让 AI 修图工作流更稳定：

1. 先开软件再对话。Photoshop 处于运行状态是所有工具的前提，养成先启动 Photoshop 再打开 ZCode 会话的习惯。
2. 指明输入与输出路径。在提示词中写清源文件路径与导出路径，Agent 不需要猜测，结果直接落到你要的位置。
3. 大改动分步走。复杂需求拆成「先调色、确认效果，再加元素、确认效果，最后导出」的多轮对话，每一步都可控可撤销。

6. 备选方案：Python 路线的 photoshop-mcp-server

6.1 适用场景与差异

备选方案 loonghao/photoshop-python-api-mcp-server 基于 Windows COM 接口与 photoshop-python-api 库实现，适合 Python 技术栈的读者或只需要轻量操作的场景。与主线方案相比，它提供 9 个工具，覆盖文档创建/打开/保存、文本与纯色图层创建、会话信息读取，外加一个可执行任意 Photoshop 脚本的 photoshop_execute_jsx 兜底工具；仅支持 Windows，实测在 Photoshop CS6 上全部可用。

6.2 下载源码网盘版并安装

从资源下载区下载 photoshop-mcp-server 0.1.11 网盘版.zip（约 15 MB）并解压，包内是备选方案的完整仓库源码，wheels 目录已收齐由源码构建的项目包及其全部依赖的 Windows / Python 3.10 安装包。按 Python+FastAPI在Windows环境下创建一个基础后端服务教程的方式准备一个 Python 3.10 环境（如 conda create -n env python=3.10 并激活），在解压目录下执行离线安装：

python -m pip install --no-index --find-links wheels photoshop-mcp-server

--no-index 会禁用在线包源，全部依赖从包内的 wheels 目录获取，全程无需联网。安装完成后验证：

python -c "import photoshop_mcp_server.server; print('OK')"

6.3 配置 ZCode

编辑 config.json，在 mcp.servers 中追加如下条目（command 换成你 Python 3.10 环境的实际解释器路径，本教程实测使用 Miniconda 的 3.10 环境）：

{
  "mcp": {
    "servers": {
      "photoshop-py": {
        "type": "stdio",
        "command": "C:/Users/<你的用户名>/miniconda3/envs/<环境名>/python.exe",
        "args": ["-m", "photoshop_mcp_server.server"]
      }
    }
  }
}

如果本机装有多个版本的 Photoshop，可在条目中追加 env 字段，用环境变量 PS_VERSION 指定要连接的版本（如 "2024"）；本机只有一个版本时可以不填，服务器会自动连接当前注册的 Photoshop。保存后重启 ZCode 即可，验证方式与第 4 章相同。

习惯在线安装的读者也可以用 uvx --python 3.10 photoshop-mcp-server 直接运行（需先安装 uv），把配置中的 command 与 args 换成对应写法即可，效果与离线安装完全一致。

6.4 工具清单

9 个工具的清单如下，工具名均以 photoshop_ 开头：

配置方法与第 4 章相同，保存后重启 ZCode 即可在会话中调用。老版本 Photoshop 下，文档颜色模式等个别枚举值会显示为 Unknown，属于接口读取差异，不影响实际操作。

7. 常见问题与解答

问：调用工具时报 No active document 怎么办？

答：该报错说明 Photoshop 正在运行但没有任何打开的文档。多数编辑类工具需要作用在已打开的文档上，在提示词里明确「打开某个路径的图片」再描述后续操作即可；也可以先在 Photoshop 中手动打开文件再对话。

问：Photoshop 需要什么版本？老版本能用吗？

答：主线方案官方支持 2012 年及以后的版本，本教程在 Photoshop CS6（13.0）上完成全部实测。版本越新可用功能越多，生成式填充等云端 AI 能力需要 Adobe 账号且仅新版本提供。

问：ZCode 会话中看不到 photoshop 相关工具怎么办？

答：按顺序检查三处：Photoshop 是否已启动；配置文件中 mcp.servers 下的条目格式是否正确（离线版的 args 路径是否指向解压目录的 dist/index.js、逗号引号完整）；修改配置后是否重启了 ZCode。仍失败时按 3.2 节手动运行服务器，把终端报错作为排查线索。

问：网盘离线版和 GitHub 源码、npm 包是什么关系？

答：三者是同一个项目 alisaitteke/photoshop-mcp 1.7.21 版本的不同分发形态。网盘离线版在该版本源码基础上预先完成了编译与依赖安装，并移除了仅服务于内置聊天窗口的大体积依赖，让国内读者跳过 GitHub 访问与 npm 下载环节；功能、工具数量与在线安装方式完全一致。想跟进项目新版本时，从 GitHub 或 npm 获取官方最新包即可。

问：解压路径有什么要求？

答：建议解压到不含中文与空格的目录（如 C:\photoshop-mcp）。配置文件中 args 的路径用正斜杠书写，路径写错时 ZCode 连接服务器会失败，按 4.1 节的示例核对。

问：使用在线安装方式时首次调用等待很久是什么原因？

答：npx 首次运行需要下载 npm 包，耗时取决于网络状况，等待一次后包已缓存，后续启动明显变快。网络受限环境建议直接使用本教程的网盘离线版，或为 npm 配置国内镜像源。

问：AI 的操作会弄乱我的文件吗？

答：所有操作都在 Photoshop 内执行，历史记录面板可逐步撤销；只要不在提示词里要求覆盖保存原图，Agent 默认按你指定的路径另存导出。重要素材建议先备份再批量操作。

8. 总结

8.1 核心内容回顾

• Photoshop MCP 把本机 Photoshop 变成 AI Agent 可操控的软件，操作可撤销、结果可编辑，与生成式路线形成互补。
• 主线方案 alisaitteke/photoshop-mcp 提供 125 个工具与 23 个预置提示词，官方支持 2012 年及以后的 Photoshop 版本；本教程的网盘离线版下载解压即用，由 node 命令直接运行。
• ZCode 侧在 config.json 的 mcp.servers 中追加 stdio 条目即可接入，离线版 args 指向解压目录的 dist/index.js，在线方式命令写 npx.cmd。
• 使用前提是 Photoshop 处于运行状态；编辑类工具需要已有打开的文档。
• Python 技术栈读者可选用 photoshop-mcp-server 备选方案，Windows COM 通道，9 个轻量工具，源码网盘版解压后离线安装。