Photocraft MCP 服务器：安装、配置与工具

Photocraft MCP 服务器是什么？

Photocraft MCP 服务器是 PhotoCraft 自动化栈内置的 Model Context Protocol 端点。它通过标准输入输出（stdio）讲 MCP 协议，因此 Claude Code、Claude Desktop、Cursor、VS Code 这类 AI 客户端可以发现编辑命令、单条或成批执行、检查打开的文档并渲染预览——全程不需要人点界面。

服务器随 photocraft-cli 发布，它是开源 PhotoCraft 桌面编辑器的命令行伴侣。本站托管的是运行在浏览器里的 PhotoCraft 网页编辑器；MCP 服务器属于桌面发行版，网页版并不提供。本文内容对应本站跟踪的上游 v0.12.0 版本，并已于 2026 年 10 月对照上游官方文档核对。

你需要准备什么

• 一份包含 photocraft-cli 的 PhotoCraft 发行版安装（见下表）。
• 一个能注册 stdio 服务器的 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code 等均可。
• 一个存放图片的工作目录。服务器只会在你启动时授权的根目录内读写文件。

CLI 在哪里

系统	CLI 位置
Windows（MSI）	默认在 C:\Program Files\PhotoCraft\photocraft-cli.exe，不会加入 PATH
Linux（deb、rpm）	/usr/bin/photocraft-cli
macOS	releases 页面上单独的 photocraft-cli zip 包；.app 内只有桌面应用

把服务器加进 Claude Code

Claude Code 用一条命令注册 stdio 服务器。把允许 agent 读写的目录传进去。Windows（默认安装目录）：

claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root "C:\work\project" --automation-write-root "C:\work\project"

Linux（或已把 CLI 解压到 PATH 的 macOS）的注册命令更短：

claude mcp add photocraft -- photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project

重启客户端，然后让 agent 列出 Photocraft 工具。如果 command_list 能返回引擎命令，说明注册成功。

Claude Desktop、Cursor 与 VS Code

读取 JSON 配置的客户端使用相同的命令和参数。Cursor（~/.cursor/mcp.json）和 Claude Desktop（claude_desktop_config.json）示例：

{
  "mcpServers": {
    "photocraft": {
      "command": "/usr/bin/photocraft-cli",
      "args": [
        "mcp",
        "--automation-read-root",
        "/work/project",
        "--automation-write-root",
        "/work/project"
      ]
    }
  }
}

Windows 上把 command 指向完整的 photocraft-cli.exe 路径，路径保留引号。VS Code 在其 mcp.json 中接受同样的 mcpServers 配置块。保存文件，重启客户端并打开 MCP 面板：应能看到 photocraft 服务器及其工具列表。

Headless 模式与 bridge 模式

服务器有两种后端。Headless 模式（上面的配置）在 CLI 进程内启动一个私有引擎并自行做文件 I/O，不需要桌面窗口，适合脚本化批量处理。

Bridge 模式把每次工具调用转发给一个用 photocraft --control 启动的桌面应用：

photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /private/path/control.token

Bridge 模式额外提供下面列出的 UI 检查工具，并使用桌面进程上配置的根目录。想在 agent 工作时盯着同一份文档时选它。

核心工具

工具	作用	关键参数
command_list	发现引擎命令 id、参数文档与启用状态	filter、enabled_only
command_run	执行一条引擎命令	id、params、wait
command_batch	按顺序执行多步并记为一条历史；不是原子事务	steps、stop_on_error
doc_inspect	图层树、历史与选区；空会话返回 document: null	—
render_preview	当前文档的有界 PNG 预览	index、max_side（默认 1024，最大 2048）
ui_inspect、ui_screenshot	实时应用状态与窗口截图；仅 bridge 模式	—

旧的文档、会话与任务工具仍然列出，包括文档化的 doc_render_preview 拼写。没有隐藏的历史别名，每个工具都带标题与注解提示。

两个 MCP 资源以 JSON 暴露实时状态：photocraft://document 对应 doc_inspect，photocraft://commands 对应 command_list。资源读取不缓存，agent 可以在步骤之间复查状态，而不是信任过期副本。

示例提示词

• 列出 Photocraft 里调整尺寸与导出相关的命令，然后把授权目录里的每个 PNG 批量转换为长边 1600 像素。
• 检查打开的文档，描述图层结构，并渲染一张预览让我确认当前状态。
• 新建文档与时间线，渲染 PNG 序列并回报进度，超过一分钟就取消任务。

智能对象也可以脚本化：layer.smartObjects.editContents 和 layer.smartObjects.convertToLayers 通过 command_run 执行；嵌套内容由内向外保存，再 doc_save 父文档到授权路径。

视频导出（Render Video）在请求携带 progress token 时回报帧进度，取消时停在帧边界。已存在的文件名会被拒绝，因此取消或失败的任务不会覆盖先前的导出。

安全模型

stdio 传输不打开网络监听；客户端通过自己的管道与 CLI 通信。文件权限按启动授权：读根目录与写根目录是服务器仅能触碰的目录，省略某个根即完全去除该项权限，路径必须解析在授权根之内。Bridge 模式在任何控制调用前先对回环连接做 bearer token 认证。

两个限制需要知道：当前服务器不发 scoped session，也不区分可信工具与高影响工具——认证只证明持有 token，不等于仅限文档访问。不要在缺少外部策略边界的情况下把任一传输暴露给不可信的 broker、shell 包装、代理或远程服务。文件系统能力已实现；通用工具能力仍属上游的设计提案。

排错

• Windows 找不到 photocraft-cli —— MSI 安装不改 PATH，注册命令里用带引号的完整路径。
• macOS 装完没有 CLI —— .app 只含桌面编辑器，去 release 资产里另下 photocraft-cli 的 macOS zip。
• 工具调用返回 -32602 —— 参数名不认识。错误会在执行前指出问题键名，对照 command_list 输出检查拼写。
• 工具结果是 isError: true —— 命令本身失败。读返回信息，会话仍在服务。
• doc_inspect 返回 document: null —— 没有打开的文档，先新建或打开一个。
• 预览看起来过期 —— 预览渲染的是当前文档。确认 agent 编辑的就是它检查的那份，并重读实时资源；读取不缓存。

常见问题

能用 MCP 连本站的网页编辑器吗？ 不能。浏览器版本地运行在你的标签页里，没有 MCP 端点。服务器随桌面发行版发布。你可以在浏览器里试用编辑器，并在导出的文件旁并行使用 CLI。

需要桌面应用一直开着吗？ 只有 bridge 模式和 UI 工具需要。Headless 模式完全在 CLI 内运行。

本文对应哪个版本？ 上游 v0.12.0，即本站固定并托管的版本。更新的版本可能增改工具；以上游 MCP 官方文档为准。

收费吗？ PhotoCraft 是 MIT 与 Apache-2.0 双许可的开源项目，MCP 服务器随同一包发布。见源码与许可页。

相关指南：版本下载、功能总览与浏览器限制与教程。