Penpot

You use this MCP server to give AI agents direct, programmatic access to your self-hosted Penpot instance. It enables reading, creating, modifying, and exporting design elements through MCP with a secure, centralized bridge between your AI tools and Penpot.

How to use

You connect your MCP client to the server over network transport. The server runs as a Docker container and exposes an MCP endpoint at a public or private URL. Once connected, you can ask your AI agent to list projects, create UI components, export frames as SVG or PNG, read color tokens, and apply changes to shapes or text. The server ensures changes originate from the Penpot RPC API so actions are tracked and reversible when supported.

How to install

Prerequisites you need before installation include Docker and Docker Compose, plus a self-hosted Penpot setup already running on your host or in the same network.

Additional setup and configuration

Enable access tokens in Penpot to allow API access tokens for secure authentication. Set environment variables for the MCP server and Penpot connectivity, and add the MCP service to your Penpot stack so both run together on the same network.

Configuration Reference

All configuration is provided via environment variables. The key options you will use include the Penpot base URL, a public URL for browser access, and database connection details. The MCP host and port define where the MCP service listens.

Enable Access Tokens

To enable API access tokens in Penpot, update the Penpot environment so the feature flag is active, then restart Penpot. After that, you can generate a token from Penpot’s Access Tokens interface and place it in the MCP server’s environment.

Penpot Docker Integration

The MCP server runs as a Docker container alongside Penpot. Add the MCP service to your existing docker-compose setup so it shares the same Docker network and can reach Penpot services. The MCP container exposes port 8787 on the host for HTTP MCP connections.

Development

For local development, you can run the MCP server outside of Docker if you prefer. Ensure you point PENPOT_DB_HOST and PENPOT_DB_PORT to your local database, and set PENPOT_BASE_URL to your local Penpot instance. Run the development server with the provided tooling and verify connectivity by performing a basic MCP initialization against the exposed endpoint.

Available tools

list_projects

List Penpot projects accessible to the connected account.

list_teams

List teams within Penpot and associated projects.

list_files

List files within a project or folder.

search_files

Search files by name or metadata.

create_file

Create a new file in Penpot from a given payload.

get_file_pages

Retrieve pages from a Penpot file for rendering or export.

rename_file

Rename an existing Penpot file.

duplicate_file

Duplicate an existing Penpot file.

get_shape_tree

Read the hierarchical shape tree of a design.

get_shape_details

Get detailed information about a specific shape.

get_shape_css

Generate CSS rules for a selected shape.

search_shapes

Search shapes by type, properties, or attributes.

get_design_tokens

Fetch design tokens from the design system.

get_colors_library

Retrieve color tokens and palettes.

get_typography_library

Retrieve typography tokens and font styles.

create_frame

Create a new frame in a Penpot project.

create_rectangle

Create a rectangle shape in the current canvas.

create_text

Create a text block in the design.

create_path

Create a custom path/shapes path.

set_fill

Update the fill color of a shape.

set_stroke

Update the stroke color or width of a shape.

set_layout

Adjust layout properties of a shape or group.

move_shape

Move a shape to a new position.

resize_shape

Resize a shape to new dimensions.

set_text_content

Edit the textual content of a text shape.

set_font

Change the font family of text.

set_font_size

Change the font size of text.

set_text_align

Set text alignment for a text shape.

export_frame_png

Export a frame as a PNG image.

export_frame_svg

Export a frame as an SVG image.

upload_media

Upload a media asset to Penpot.

list_media_assets

List media assets available in the project.

list_fonts

List available fonts in Penpot.

get_file_raw_data

Fetch raw underlying data for a file.

compare_revisions

Compare revisions of a file to identify changes.

create_snapshot

Create a design snapshot for versioning.

get_snapshots

List available design snapshots.

get_profile

Retrieve user or account profile information.

get_webhooks

List configured webhooks for events.

get_file_pages

Retrieve pages from a Penpot file.

create_comment

Create a comment on a design element.

reply_to_comment

Reply to an existing comment.

resolve_comment

Resolve or close a comment thread.

search_files

Search files within the Penpot workspace.