Photopea MCP Server

Photopea MCP Server

Design posters, edit photos, and transform images directly from your terminal. Powered by Photopea -- a free, browser-based alternative to Photoshop -- connected to your AI agent via MCP.

演示

Prompt used in this demo: examples/album-cover-demo.md

运作原理

graph LR
    A[Agent] |stdio| B[MCP Server]
    B |WebSocket| C[Browser]
    C |postMessage| D[Photopea]

您的代理通过MCP协议发送编辑命令。服务器将这些转换为Photopea JavaScript API调用，并通过到浏览器的WebSocket桥执行这些调用。

注： 浏览器窗口将在第一次调用工具时自动打开。这是意料之中的——Photopea完全在浏览器中运行，服务器需要它来执行图像编辑操作。

快速开始

claude mcp add -s user photopea -- npx -y photopea-mcp-server

然后启动一个新的Claude Code会话，并要求它编辑图像。Photopea编辑器将在第一次调用工具时自动在浏览器中打开。

安装

克劳德代码

npx（推荐）：

claude mcp add -s user photopea -- npx -y photopea-mcp-server

全局安装：

npm install -g photopea-mcp-server
claude mcp add -s user photopea -- photopea-mcp-server

克劳德桌面

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "photopea": {
      "command": "npx",
      "args": ["-y", "photopea-mcp-server"]
    }
  }
}

光标

添加到光标MCP设置(.cursor/mcp.json 在您的项目或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "photopea": {
      "command": "npx",
      "args": ["-y", "photopea-mcp-server"]
    }
  }
}

VS代码（副本）

添加 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "photopea": {
      "command": "npx",
      "args": ["-y", "photopea-mcp-server"]
    }
  }
}

帆板运动

添加到Windsurf MCP设置(~/.windsurf/mcp.json):

{
  "mcpServers": {
    "photopea": {
      "command": "npx",
      "args": ["-y", "photopea-mcp-server"]
    }
  }
}

可用工具

文档（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的色调/饱和度，应用数量为50、半径为2的反锐化蒙版，然后导出为PNG

发展

git clone https://github.com/attalla1/photopea-mcp-server.git
cd photopea-mcp-server
npm install
npm run build

命令

建筑

服务器有四个主要组件：

MCP服务器 (src/server.ts)--在MCP SDK中注册所有34个工具，并通过stdio传输进行连接。

WebSocket网桥 (src/bridge/websocket-server.ts)--管理MCP服务器和浏览器之间的连接。排队脚本执行请求并处理超时响应。

脚本生成器 (src/bridge/script-builder.ts)--将工具参数转换为Photopea JavaScript API调用的纯函数。每个构建器函数都会生成一个Photopea可以执行的脚本字符串。

浏览器前端 (src/frontend/index.html)--一个单页应用程序，在iframe中加载Photopea，连接到WebSocket桥，并通过以下方式将脚本中继到Photopea postMessage。通过WebSocket返回结果。

src/
  index.ts              # Entry point: HTTP server, browser launch, MCP startup
  server.ts             # MCP server initialization and tool registration
  bridge/
    websocket-server.ts # WebSocket bridge with request queue
    script-builder.ts   # Photopea JS code generators
    types.ts            # Protocol message types
  tools/
    document.ts         # Document operations (5 tools)
    layer.ts            # Layer operations (11 tools)
    text.ts             # Text and shape operations (3 tools)
    image.ts            # Image, adjustment, filter operations (9 tools)
    export.ts           # Export and utility operations (6 tools)
  utils/
    file-io.ts          # Local file read/write, URL fetching
    platform.ts         # Port discovery, browser launch
  frontend/
    index.html          # Browser UI with Photopea iframe

安全

• 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变得无响应。为了避免这种情况，请按照所需的顺序创建图层，而不是在创建后重新排序。

需求

• Node.js>=18
• 现代网络浏览器（Chrome、Firefox、Edge、Safari）

许可证

麻省理工学院