用途
Photopea MCP Server 用于让 AI 智能体驱动 Photopea 完成图像编辑任务。Photopea 是一个免费、基于浏览器的 Photoshop 替代品。用户可以在终端中设计海报、编辑照片、变换图像，智能体通过 MCP 协议发送编辑命令，服务器将其翻译为 Photopea JavaScript API 调用，并通过 WebSocket 桥接到浏览器执行。
主要能力
服务器注册了 34 个工具，分为以下类别：
- 文档（5 个工具）
- 图层（11 个工具）
- 文本与形状（3 个工具）
- 图像与效果（9 个工具）
- 导出与实用工具（6 个工具）
典型任务示例：
- 创建海报：创建 1920x1080 文档，深蓝色背景，添加白色 72px Arial 标题“Hello World”，导出为 PNG 到 ~/Desktop/poster.png。
- 编辑照片：打开 ~/photos/portrait.jpg，亮度增加 30，应用 2px 高斯模糊，导出为 JPG 到 ~/Desktop/edited.jpg。
- 合成图像：创建 1200x630 文档，将 ~/assets/background.png 作为基础图层，再放置 ~/assets/logo.png 并移动到右上角。
- 批量调整：打开 ~/photos/sunset.jpg，应用色相/饱和度 +20 饱和度，应用 USM 锐化（数量 50，半径 2），导出为 PNG。
使用方式
安装方式：
- npx（推荐）
- 全局安装
集成到 MCP 客户端：
- Claude Desktop：添加到配置文件（macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）
- Cursor：添加到 MCP 设置（项目内 .cursor/mcp.json 或全局 ~/.cursor/mcp.json）
- VS Code（Copilot）：添加到项目内 .vscode/mcp.json
- Windsurf：添加到 MCP 设置（~/.windsurf/mcp.json）
安装后，启动新的 Claude Code 会话并要求编辑图像。首次调用工具时，Photopea 编辑器会在浏览器中自动打开。
架构组件
服务器包含四个主要组件：
- MCP Server（src/server.ts）：使用 MCP SDK 注册全部 34 个工具，通过 stdio 传输连接。
- WebSocket Bridge（src/bridge/websocket-server.ts）：管理 MCP 服务器与浏览器之间的连接，排队脚本执行请求并处理带超时的响应。
- Script Builder（src/bridge/script-builder.ts）：纯函数，将工具参数转换为 Photopea JavaScript API 调用，每个构建函数生成 Photopea 可执行的脚本字符串。
- Browser Frontend（src/frontend/index.html）：单页应用，在 iframe 中加载 Photopea，连接 WebSocket 桥接，通过 postMessage 将脚本转发给 Photopea，并通过 WebSocket 返回结果。
安全与限制
- MCP 服务器绑定到 127.0.0.1（仅本地），无法从网络访问。
- photopea_run_script 工具在 Photopea 的沙箱 iframe 内执行任意 JavaScript，被标记为破坏性操作，在支持工具注解的 MCP 客户端中需要用户批准。
- 文件操作（open_file、export_image、place_image）以运行服务器的用户权限读写文件。
已知限制：
- 重型脚本（例如包含许多颜色步骤的渐变）可能导致 Photopea 浏览器 UI 无响应。操作仍会在后台成功完成，导出将按预期工作。
- 刷新浏览器页面会丢弃所有未保存的工作。刷新前请导出文档。
- 一次只能打开一个浏览器标签页。多个标签页会争用 WebSocket 连接。
- reorder_layer 工具可能导致 Photopea UI 无响应。为避免此问题，请按所需顺序创建图层，而不是在创建后重新排序。
适用场景
适用于需要通过 AI 智能体自动化完成图像编辑、海报设计、照片调整、图像合成等任务的用户，尤其适合已使用 Claude Desktop、Cursor、VS Code（Copilot）、Windsurf 等 MCP 客户端的开发者或设计师。
环境要求
需要现代 Web 浏览器（Chrome、Firefox、Edge、Safari）。
