Photopea MCP Server

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

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]

Your agent sends editing commands through the MCP protocol. The server translates these into Photopea JavaScript API calls and executes them via a WebSocket bridge to the browser.

Note:A browser window will open automatically on the first tool call. This is expected -- Photopea runs entirely in the browser and the server needs it to perform image editing operations.

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

Then start a new Claude Code session and ask it to edit images. The Photopea editor will open in your browser automatically on the first tool call.

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

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS):

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

Add to Cursor MCP settings (.cursor/mcp.jsonin your project or~/.cursor/mcp.jsonglobally):

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

Add to.vscode/mcp.jsonin your project:

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

Add to Windsurf MCP settings (~/.windsurf/mcp.json):

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

Once installed, ask your agent to perform image editing tasks:

"Create a 1920x1080 document with a dark blue background, add the title 'Hello World' in white 72px Arial, and export it as a PNG to ~/Desktop/poster.png"

"Open ~/photos/portrait.jpg, increase the brightness by 30, apply a slight gaussian blur of 2px, and export as JPG to ~/Desktop/edited.jpg"

"Create a 1200x630 document, place ~/assets/background.png as the base layer, then place ~/assets/logo.png and move it to the top-right corner"

"Open ~/photos/sunset.jpg, apply hue/saturation with +20 saturation, apply an unsharp mask with amount 50 and radius 2, then export as PNG"

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

MCP Server(src/server.ts) -- Registers all 34 tools with the MCP SDK and connects via stdio transport.

WebSocket Bridge(src/bridge/websocket-server.ts) -- Manages the connection between the MCP server and the browser. Queues script execution requests and handles responses with timeouts.

Script Builder(src/bridge/script-builder.ts) -- Pure functions that translate tool parameters into Photopea JavaScript API calls. Each builder function generates a script string that Photopea can execute.

Browser Frontend(src/frontend/index.html) -- A single-page app that loads Photopea in an iframe, connects to the WebSocket bridge, and relays scripts to Photopea viapostMessage. Returns results back through the 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

- The MCP server binds to127.0.0.1(localhost only) and is not accessible from the network.
- Thephotopea_run_scripttool executes arbitrary JavaScript inside Photopea's sandboxed iframe. It is marked as destructive and requires user approval in MCP clients that support tool annotations.
- File operations (open_file,export_image,place_image) read and write files with the same permissions as the user running the server.

- Heavy scripts (e.g., gradients with many color steps) may cause the Photopea browser UI to become unresponsive. The operations still complete successfully in the background and exports will work as expected.
- Refreshing the browser page will discard all unsaved work. Export your documents before refreshing.
- Only one browser tab should be open at a time. Multiple tabs will conflict over the WebSocket connection.
- Thereorder_layertool may cause the Photopea UI to become unresponsive. To avoid this, create layers in the desired order rather than reordering after creation.

- Node.js >= 18
- A modern web browser (Chrome, Firefox, Edge, Safari)

API-first platform for image optimization and document design. Generate optimized images, PDFs, and documents at scale with our visual editor and REST API.

An AI-powered drawing application for your browser. Draw, save, and get AI-powered insights.

7 tools for interior design 3D visualization — room planner, AR furniture placement, material switcher, lighting design, virtual room tours with SceneView.

Generates O'RLY? (O'Reilly parody) book covers.

Generates O'RLY? (O'Reilly parody) book covers.

31 AI image processing tools — free local editing, AI background removal & upscaling, and paid product photo generation

MCP server plugin for Sweet Home 3D that lets AI assistants create walls, place furniture, apply textures, and render 3D interior designs — 42 tools, zero external dependencies.

A lightweight MCP (Model Context Protocol) server for Blender. It offers a natural language interface with Blender’s Python API, improving access to documentation, and allowing users to explore and understand complex setups.

The Lottie Creator MCP brings your AI assistant directly into your animation workflow — giving it full access to LottieFiles Creator so it can build and edit Lottie animations on your behalf through natural language.

AI Video, Image & Audio Generation with over 150 models