What is the penpot-mcp-server MCP server?
penpot-mcp-server is an MCP server for self-hosted Penpot. It runs as a Docker container beside Penpot and exposes 68 tools over streamable HTTP at localhost:8787/mcp, so an AI coding agent can read, create, modify, comment on and export designs.
penpot-mcp-server (ancrz/penpot-mcp-server) is an MCP server for self-hosted Penpot. It gives AI agents full programmatic access to a Penpot instance over the Model Context Protocol, so an agent can create UI components, layouts and prototypes directly in Penpot.
The server runs as a Docker container next to your Penpot stack and is written in Python 3.13 with FastMCP. Agents connect to it over streamable HTTP at localhost:8787/mcp.
How it reads and writes designs
- Reads go straight to PostgreSQL through asyncpg.
- Writes go through the Penpot RPC API using httpx.
- PNG and SVG exports use Penpot's exporter.
- Live canvas access goes through the browser plugin bridge over WebSocket.
What the 68 tools cover
Tools are grouped by job: projects and teams, file operations, shape reading, components and tokens, comments, media and fonts, snapshots, export, shape creation, shape modification, text operations and advanced analysis.
The design-to-code side is covered too: generate CSS from any shape, export to SVG or PNG, and extract design tokens. Batch operations such as renaming shapes and updating colors cover repetitive work.
Interactive mode with the browser plugin
A browser plugin connects the agent to the live Penpot canvas. The agent can query which shapes you currently have selected and run JavaScript through the Penpot Plugin API. The headless tools work without the plugin.
Who the penpot-mcp-server MCP server is for
Best for
- Teams that self-host Penpot with Docker Compose and want an AI agent working inside it.
- Design system maintenance, where an agent reads and writes components, colors and typographies.
- Design-to-code work that needs CSS from a shape, exported SVG or PNG, or extracted design tokens.
Connect Penpot MCP Server: 68 Tools for Self-Hosted Penpot to your AI client
git clone https://github.com/ancrz/penpot-mcp-server.git
cd penpot-mcp-server
chmod +x setup.sh
./setup.shMeet the prerequisites
You need self-hosted Penpot running via Docker Compose, Docker with Docker Compose v2, and access tokens enabled in your Penpot instance by adding enable-access-tokens to PENPOT_FLAGS.
Run the automated setup
The commands above clone the repository and run setup.sh, which guides you through configuration, builds the Docker image and starts the server.
Or set it up manually
Copy .env.example to .env and set PENPOT_ACCESS_TOKEN, PENPOT_DB_PASS and PENPOT_PUBLIC_URL. Add the penpot-mcp service from docker-compose.penpot.yml to your Penpot stack, then run
docker compose up -d --build penpot-mcp.Point your agent at the server
For Claude Code, add an entry named penpot with type http and url http://localhost:8787/mcp to ~/.claude.json or .mcp.json. Gemini CLI uses the httpUrl field and Antigravity uses serverUrl.
Endpoints and ports
http://localhost:8787/mcpStreamable HTTPcurl -s http://localhost:8787/Run it to confirm the server is uphttp://localhost:8787/plugin/manifest.jsonPaste into Penpot's Plugin ManagerWhat you can do with it
- 68 toolsTools cover projects, files, shapes, text, exports, comments and more, with a programmatic API for Penpot.
- Shape reading and CSSTools such as get_shape_tree, get_shape_details, get_shape_css and search_shapes read the structure of a design and generate CSS from any shape.
- Design tokens and librariesget_design_tokens, get_colors_library and get_typography_library read the components, colors and typographies of a design system.
- Shape creation and modificationcreate_rectangle, create_frame, create_text and create_path build shapes, while set_fill, set_stroke, set_layout, move_shape and resize_shape change them.
- Text operationsset_text_content, set_font, set_font_size and set_text_align edit text in a design.
- Commentscreate_comment, reply_to_comment and resolve_comment let an agent leave and close review comments on a design.
- Export and snapshotsexport_frame_png and export_frame_svg export frames, and create_snapshot and get_snapshots handle file snapshots.
- Live canvas bridgeThe browser plugin lets the agent read your current selection and run JavaScript through the Penpot Plugin API.
Tools it exposes
list_projects
Lists Penpot projects. Part of the Projects & Teams group with list_teams, list_files and search_files.
list_teams
Lists the teams in the Penpot instance.
create_file
Creates a file. The File Operations group also has get_file_pages, rename_file and duplicate_file.
get_shape_tree
Reads the shape tree of a design. Shape Reading also has get_shape_details, get_shape_css and search_shapes.
get_shape_css
Generates CSS from a shape.
get_design_tokens
Reads design tokens. The group also has get_colors_library and get_typography_library.
create_comment
Adds a comment to a design. reply_to_comment and resolve_comment complete the Comments group.
upload_media
Uploads media. The Media & Fonts group also has list_media_assets and list_fonts.
create_snapshot
Creates a snapshot of a file. get_snapshots is the other Snapshots tool.
export_frame_png
Exports a frame as PNG.
export_frame_svg
Exports a frame as SVG.
create_frame
Creates a frame. Shape Creation also has create_rectangle, create_text and create_path.
set_fill
Sets a shape fill. Shape Modification also has set_stroke, set_layout, move_shape and resize_shape.
set_text_content
Sets text content. Text Operations also has set_font, set_font_size and set_text_align.
compare_revisions
Compares revisions of a file. get_file_raw_data is the other Advanced Analysis tool.
Frequently asked questions
What is penpot-mcp-server?
It is an MCP server for self-hosted Penpot that gives an AI coding agent full programmatic access to a Penpot instance over the Model Context Protocol. It exposes 68 tools covering projects, shapes, text, exports and comments, and it runs as a Docker container beside your Penpot stack.
How do I install penpot-mcp-server?
Clone the ancrz/penpot-mcp-server repository, move into the folder, make setup.sh executable and run it. The script guides you through configuration, builds the Docker image and starts the server. You need self-hosted Penpot on Docker Compose, Docker Compose v2 and access tokens enabled.
How do I connect an AI agent to it?
The server speaks streamable HTTP at localhost:8787/mcp. In Claude Code, add an mcpServers entry named penpot with type http and that address as the url to ~/.claude.json or .mcp.json. Gemini CLI uses httpUrl in ~/.gemini/settings.json, and Antigravity uses serverUrl in its mcp_config.json.
Do I need the browser plugin?
No. The headless tools work without it. The plugin is only needed for live selection and script execution through the Penpot Plugin API. Load it in Penpot with Ctrl+Alt+P and paste the manifest address localhost:8787/plugin/manifest.json, and add enable-plugins-runtime to PENPOT_FLAGS. The server itself listens on localhost only.
How does it read and write Penpot data?
Reads go straight to PostgreSQL through asyncpg, and writes go through Penpot's RPC API using httpx. PNG and SVG exports use Penpot's exporter, and live canvas access runs over a WebSocket bridge. Credentials stay in the server's own .env file, so an env block in the client config has no effect.
Which browsers work with the plugin?
Firefox works out of the box. Chrome, Chromium and Vivaldi need a one-time approval for local network access, and Brave needs Shield disabled. After the plugin installs and its status indicator turns green, the AI agent has live access to the canvas.
What can I ask the agent to do?
Example prompts are listing your Penpot projects, creating a login form with email and password fields and a submit button, exporting the Login Card frame as SVG, asking which colors the design system defines, and adding a comment at a position in the file.