attalla1/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 .
Demo
Prompt used in this demo: examples/album-cover-demo.md
How It Works
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.
Quick Start
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.
Installation
Claude Code
**npx (recommended):**
**Global install:**
Claude Desktop
Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Cursor
Add to Cursor MCP settings (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):
VS Code (Copilot)
Add to .vscode/mcp.json in your project:
Windsurf
Add to Windsurf MCP settings (~/.windsurf/mcp.json):
Available Tools
Document (5 tools)
| Tool | Description |
|------|-------------|
| photopea_create_document | Create a new document with specified dimensions and settings |
| photopea_open_file | Open an image from a URL or local file path |
| photopea_get_document_info | Get active document info (name, dimensions, resolution, color mode) |
| photopea_resize_document | Resize the active document (resamples content to fit) |
| photopea_close_document | Close the active document |
Layer (11 tools)
| Tool | Description |
|------|-------------|
| photopea_add_layer | Add a new empty art layer |
| photopea_add_fill_layer | Add a solid color fill layer |
| photopea_delete_layer | Delete a layer by name or index |
| photopea_select_layer | Make a layer active by name or index |
| photopea_set_layer_properties | Set opacity, blend mode, visibility, name, or lock state |
| photopea_move_layer | Translate a layer by x/y offset |
| photopea_duplicate_layer | Duplicate a layer with optional new name |
| photopea_reorder_layer | Move a layer in the stack (above, below, top, bottom) |
| photopea_group_layers | Group named layers into a layer group |
| photopea_ungroup_layers | Ungroup a layer group |
| photopea_get_layers | Get the full layer tree as JSON |
Text & Shape (3 tools)
| Tool | Description |
|------|-------------|
| photopea_add_text | Add a text layer at specified coordinates |
| photopea_edit_text | Edit content or style of an existing text layer |
| photopea_add_shape | Add a shape (rectangle or ellipse) |
Image & Effects (9 tools)
| Tool | Description |
|------|-------------|
| photopea_place_image | Place an image from URL or local path |
| photopea_apply_adjustment | Apply brightness/contrast, hue/saturation, levels, or curves |
| photopea_apply_filter | Apply gaussian blur, sharpen, unsharp mask, noise, or motion blur |
| photopea_transform_layer | Scale, rotate, or flip a layer |
| photopea_add_gradient | Apply a linear gradient fill |
| photopea_make_selection | Create a rectangular, elliptical, or full selection |
| photopea_modify_selection | Expand, contract, feather, or invert a selection |