AI导哈

图像编辑服务器

Photopea MCP Server是一个基于Photopea的终端图像编辑服务器，通过MCP协议连接AI代理，提供海报设计、照片编辑和图像转换功能。

  • by attalla1
  • TypeScript
  • 本地部署
  • 46 星标
  • 更新于
在 GitHub 查看 attalla1/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个工具）

工具 说明
photopea_create_document 使用指定的尺寸和设置创建新文档
photopea_open_file 从URL或本地文件路径打开图像
photopea_get_document_info 获取活动文档信息（名称、尺寸、分辨率、颜色模式）
photopea_resize_document 调整活动文档的大小（重新采样内容以适应）
photopea_close_document 关闭活动文档

图层（11个工具）

工具 说明
photopea_add_layer 添加新的空艺术层
photopea_add_fill_layer 添加纯色填充层
photopea_delete_layer 按名称或索引删除图层
photopea_select_layer 按名称或索引激活图层
photopea_set_layer_properties 设置不透明度、混合模式、可见性、名称或锁定状态
photopea_move_layer 按x/y偏移量平移图层
photopea_duplicate_layer 使用可选的新名称复制图层
photopea_reorder_layer 在堆栈中移动一个层（上、下、上、下）
photopea_group_layers 将命名图层分组到图层组中
photopea_ungroup_layers 取消图层组的分组
photopea_get_layers 获取JSON格式的完整层树

文本和形状（3个工具）

工具 说明
photopea_add_text 在指定坐标处添加文本图层
photopea_edit_text 编辑现有文本图层的内容或样式
photopea_add_shape 添加形状（矩形或椭圆形）

图像和效果（9个工具）

工具 说明
photopea_place_image 从URL或本地路径放置图像
photopea_apply_adjustment 应用亮度/对比度、色调/饱和度、级别或曲线
photopea_apply_filter 应用高斯模糊、锐化、去锐化蒙版、噪波或运动模糊
photopea_transform_layer 缩放、旋转或翻转图层
photopea_add_gradient 应用线性渐变填充
photopea_make_selection 创建矩形、椭圆形或完整选择
photopea_modify_selection 展开、收缩、细化或反转所选内容
photopea_fill_selection 用颜色填充当前选择
photopea_clear_selection 取消选择当前选择

导出和实用程序（6个工具）

工具 说明
photopea_export_image 导出为PNG、JPG、WebP、PSD或SVG
photopea_load_font 从URL加载自定义字体（TTF、OTF、WOFF2）
photopea_list_fonts 列出可用字体，并可选择搜索筛选器
photopea_run_script 执行任意Photopea JavaScript
photopea_undo 撤消一个或多个操作
photopea_redo 重做一个或多个操作

用法示例

安装后，让您的代理执行图像编辑任务：

制作海报：

创建一个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

命令

命令 描述
npm run build 将TypeScript编译为 dist/
npm run dev 带自动重新加载的观看模式
npm test 运行单元和集成测试
npm start 启动服务器

建筑

服务器有四个主要组件：

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）

许可证

麻省理工学院

相关 MCP