Log inSubmit server
Photopea MCP Server logo

Photopea MCP Server

by attalla1

Edits Photopea documents through MCP, covering layers, text, effects, selections, fonts, and local export.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Photopea MCP Server

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "attalla1-photopea-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "photopea-mcp-server"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 34 tools correctly (24d ago).

Overview

attalla1/photopea-mcp-server MCP server connects an AI agent to Photopea through a local stdio process, WebSocket bridge, and browser window. It exposes tools for creating or opening documents, managing layers, adding text and shapes, applying adjustments and filters, placing images, selecting pixels, loading fonts, and exporting files. Photopea opens automatically in the browser when the first tool runs. Reach for it when an agent needs structured image-editing operations or repeatable document workflows rather than manual editor interactions.

Use cases

  • Create posters with text, shapes, gradients, and exported image files
  • Edit local photographs with adjustments, filters, and transforms
  • Composite images from local paths or URLs into layered documents
  • Batch-process images through repeatable agent-directed edits
  • Load custom fonts and generate editable text layers

Key features

  • Create and open Photopea documents
  • Manage, group, reorder, and inspect layers
  • Add and edit text and vector shapes
  • Apply adjustments, filters, gradients, and transforms
  • Make and modify pixel selections
  • Export documents and load custom fonts

Tools34

What Photopea MCP Server lets your agent do. Expand a tool for its parameters.

Verified live~6.2k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

18/18 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · photopea-mcp-server (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars44Stargazers on the source repository.
npm downloads588Package downloads in the last 30 days.
Last commit6mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed34Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Photopea MCP Server works

What attalla1/photopea-mcp-server MCP server does

attalla1/photopea-mcp-server MCP server lets an MCP-compatible agent operate Photopea documents through structured tools. It supports blank-document creation and opening existing PSD, PNG, JPG, WebP, SVG, and other common image formats. Agents can inspect document metadata, resize canvases, close documents, and export the finished document to local files.

The server covers layer-oriented editing as well as basic composition. Layer tools can create, remove, select, duplicate, move, reorder, group, ungroup, and update layers. Text tools add or edit text layers, while shape tools create rectangle or ellipse vector layers. Images can be placed from a URL or local path.

Editing tools include adjustments for brightness and contrast, hue and saturation, levels, and curves; filters such as Gaussian blur, sharpen, unsharp mask, noise, and motion blur; layer transforms; gradients; rectangular, elliptical, and full-canvas selections; selection expansion, contraction, feathering, inversion, filling, and clearing. Font loading and font listing support text workflows.

How it works

The MCP server uses stdio to receive tool calls from the agent. It translates parameters into Photopea JavaScript API calls, sends those scripts through a WebSocket bridge, and communicates with Photopea in a browser through postMessage. A browser window opens automatically during the first tool call because Photopea runs inside the browser.

Most operations act on the active document or active layer. A typical workflow creates or opens a document, inspects its dimensions and layer tree, selects the target layer, performs edits, and exports the result. Destructive operations include document resizing, pixel adjustments, filters, transforms, and selection fills; the available undo and redo tools can help manage those changes.

Setup and configuration

The package can be launched without a global installation using:

Terminal
npx -y photopea-mcp-server

For Claude Code, the README provides:

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

Claude Desktop, Cursor, VS Code with Copilot, and Windsurf can run it as a stdio MCP server with npx and the -y photopea-mcp-server arguments. The repository also documents a development setup based on cloning the project, running npm install, building with npm run build, and starting the server.

Tools and capabilities

The attalla1/photopea-mcp-server MCP server organizes its 34 tools around documents, layers, text and shapes, image effects, export, and utilities. Layer inspection returns JSON containing names, types, indices, visibility, opacity, blend mode, and bounds; groups include nested children. Document inspection returns the name, dimensions, resolution, layer count, and color mode.

Export flattens the complete document and writes the selected PNG, JPG, WebP, PSD, or SVG format to the local filesystem. Custom TTF, OTF, and WOFF2 fonts can be loaded from a URL before creating or editing text. The server also exposes arbitrary Photopea JavaScript execution, undo, redo, and optional font search capabilities as documented by the project.

Limitations and notes

Photopea is browser-based, so a browser window and the WebSocket bridge are required for editing. Operations that rely on an active document or layer should be preceded by the relevant create, open, inspect, or select call. Several image operations modify pixel data directly, while export produces a flattened output rather than preserving the editable layer structure in the exported image formats. Document resizing scales all layer content and is described as destructive.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Photopea MCP Server

attalla1/photopea-mcp-server is an MCP server that connects AI agents to Photopea through a browser, stdio transport, and a WebSocket bridge. Its main tools create and open documents, manage layers, edit text and shapes, apply image effects, make selections, load fonts, and export files locally.

Run it with npx using `npx -y photopea-mcp-server`, then add that command to your MCP client configuration.

Yes, it works with Cursor as a stdio MCP server. Add a `photopea` entry using `npx` with arguments `-y` and `photopea-mcp-server` to `.cursor/mcp.json` in a project or to the global Cursor MCP configuration.

A browser window opens because Photopea runs in the browser and the server communicates with it through a WebSocket bridge and browser `postMessage`. The window is expected to appear on the first tool call.

Yes, its export tool saves the active document to the local filesystem as PNG, JPG, WebP, PSD, or SVG. Image exports flatten the document, so the editable layer structure is not retained in those flattened outputs.

Related MCP servers

All in Art & Culture All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewPhotopea MCP Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/attalla1-photopea-mcp-server?style=directory)](https://allmcps.com/mcp/attalla1-photopea-mcp-server)
HTML Embed
<a href="https://allmcps.com/mcp/attalla1-photopea-mcp-server"><img src="https://allmcps.com/api/badge/attalla1-photopea-mcp-server?style=directory" alt="Photopea MCP Server on AllMCPs" /></a>