Skip to content
Back to search

penpot-mcp

Penpot's official MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/penpot--penpot-mcp/badge.svg)](/listings/penpot--penpot-mcp)

HTML

<a href="/listings/penpot--penpot-mcp"><img src="/api/listings/penpot--penpot-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 244 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!IMPORTANT]
  2. > This repository has been archived on 2026-02-03.
  3. > Its contents have been fully integrated into the main Penpot repository:
  4. > https://github.com/penpot/penpot/tree/develop/mcp
  5. ![mcp-server-cover-github-1](https://github.com/user-attachments/assets/dcd14e63-fecd-424f-9a50-c1b1eafe2a4f)
  6. # Penpot's Official MCP Server
  7. Penpot integrates a LLM layer built on the Model Context Protocol (MCP) via Penpot's Plugin API to interact with a Penpot design file. Penpot's MCP server enables LLMs to perfom data queries, transformation and creation operations.
  8. Penpot's MCP Server is unlike any other you've seen. You get design-to- design, code-to-design and design-code supercharged workflows.
  9. [![Penpot MCP video playlist](https://github.com/user-attachments/assets/204f1d99-ce51-41dd-a5dd-1ef739f8f089)](https://www.youtube.com/playlist?list=PLgcCPfOv5v57SKMuw1NmS0-lkAXevpn10)
  10. ## Architecture
  11. The **Penpot MCP Server** exposes tools to AI clients (LLMs), which support the retrieval
  12. of design data as well as the modification and creation of design elements.
  13. The MCP server communicates with Penpot via the dedicated **Penpot MCP Plugin**,
  14. which connects to the MCP server via WebSocket.
  15. This enables the LLM to carry out tasks in the context of a design file by
  16. executing code that leverages the Penpot Plugin API.
  17. The LLM is free to write and execute arbitrary code snippets
  18. within the Penpot Plugin environment to accomplish its tasks.
  19. ![Architecture](resources/architecture.png)
  20. This repository thus contains not only the MCP server implementation itself
  21. but also the supporting Penpot MCP Plugin
  22. (see section [Repository Structure](#repository-structure) below).
  23. ## Demonstration
  24. [![Video](https://v32155.1blu.de/penpot/PenpotFest2025_thumbnail.png)](https://v32155.1blu.de/penpot/PenpotFest2025.mp4)
  25. ## Usage
  26. To use the Penpot MCP server, you must
  27. * run the MCP server and connect your AI client to it,
  28. * run the web server providing the Penpot MCP plugin, and
  29. * open the Penpot MCP plugin in Penpot and connect it to the MCP server.
  30. Follow the steps below to enable the integration.
  31. ### Prerequisites
  32. The project requires [Node.js](https://nodejs.org/) (tested with v22).
  33. Following the installation of Node.js, the tools `npm` and `npx` should be
  34. available in your terminal.
  35. ### 1. Build & Launch the MCP Server and the Plugin Server
  36. If it's your first execution, install the required dependencies:
  37. ```shell
  38. npm install
  39. ```
  40. Then build all components and start the two servers:
  41. ```shell
  42. npm run bootstrap
  43. ```
  44. This bootstrap command will:
  45. * install dependencies for all components (`npm run install:all`)
  46. * build all components (`npm run build:all`)
  47. * start all components (`npm run start:all`)
  48. ### 2. Load the Plugin in Penpot and Establish the Connection
  49. > [!NOTE]
  50. > **Browser Connectivity Restrictions**
  51. >
  52. > Starting with Chromium version 142, the private network access (PNA) restrictions have been hardened,
  53. > and when connecting to `localhost` from a web application served from a different origin
  54. > (such as https://design.penpot.app), the connection must explicitly be allowed.
  55. >
  56. > Most Chromium-based browsers (e.g. Chrome, Vivaldi) will display a popup requesting permission
  57. > to access the local network. Be sure to approve the request to allow the connection.
  58. >
  59. > Some browsers take additional security measures, and you may need to disable them.
  60. > For example, in Brave, disable the "Shield" for the Penpot website to allow local network access.
  61. >
  62. > If your browser refuses to connect to the locally served plugin, check its configuration or
  63. > try a different browser (e.g. Firefox) that does not enforce these restrictions.
  64. 1. Open Penpot in your browser
  65. 2. Navigate to a design file
  66. 3. Open the Plugins menu
  67. 4. Load the plugin using the development URL (`http://localhost:4400/manifest.json` by default)
  68. 5. Open the plugin UI
  69. 6. In the plugin UI, click "Connect to MCP server".
  70. The connection status should change from "Not connected" to "Connected to MCP server".
  71. (Check the browser's developer console for WebSocket connection logs.
  72. Check the MCP server terminal for WebSocket connection messages.)
  73. > [!IMPORTANT]
  74. > Do not close the plugin's UI while using the MCP server, as this will close the connection.
  75. ### 3. Connect an MCP Client
  76. By default, the server runs on port 4401 and provides:
  77. - **Modern Streamable HTTP endpoint**: `http://localhost:4401/mcp`
  78. - **Legacy SSE endpoint**: `http://localhost:4401/sse`
  79. These endpoints can be used directly by MCP clients that support them.
  80. Simply configure the client to connect the MCP server by providing the respective URL.
  81. When using a client that only supports stdio transport,
  82. a proxy like `mcp-remote` is required.
  83. #### Using a Proxy for stdio Transport
  84. The `mcp-remote` package can proxy stdio transport to HTTP/SSE,
  85. allowing clients that support only stdio to connect to the MCP server indirectly.
  86. 1. Install `mcp-remote` globally if you haven't already:
  87. npm install -g mcp-remote
  88. 2. Use `mcp-remote` to provide the launch command for your MCP client:
  89. npx -y mcp-remote http://localhost:4401/sse --allow-http
  90. #### Example: Claude Desktop
  91. For Windows and macOS, there is the official [Claude Desktop app](https://claude.ai/download), which you can use as an MCP client.
  92. For Linux, there is an [unofficial community version](https://github.com/aaddrick/claude-desktop-debian).
  93. Since Claude Desktop natively supports only stdio transport, you will need to use a proxy like `mcp-remote`.
  94. Install it as described above.
  95. To add the server to Claude Desktop's configuration, locate the configuration file (or find it via Menu / File / Settings / Developer):
  96. - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
  97. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  98. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  99. Add a `penpot` entry under `mcpServers` with the following content:
  100. ```json
  101. {
  102. "mcpServers": {
  103. "penpot": {
  104. "command": "npx",
  105. "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
  106. }
  107. }
  108. }
  109. ```
  110. After updating the configuration file, restart Claude Desktop completely for the changes to take effect.
  111. > [!IMPORTANT]
  112. > Be sure to fully quit the app for the changes to take effect; closing the window is *not* sufficient.
  113. > To fully terminate the app, choose Menu / File / Quit.
  114. After the restart, you should see the MCP server listed when clicking on the "Search and tools" icon at the bottom
  115. of the prompt input area.
  116. #### Example: Claude Code
  117. To add the Penpot MCP server to a Claude Code project, issue the command
  118. claude mcp add penpot -t http http://localhost:4401/mcp
  119. ## Repository Structure
  120. This repository is a monorepo containing four main components:
  121. 1. **Common Types** (`common/`):
  122. - Shared TypeScript definitions for request/response protocol
  123. - Ensures type safety across server and plugin components
  124. 2. **Penpot MCP Server** (`mcp-server/`):
  125. - Provides MCP tools to LLMs for Penpot interaction
  126. - Runs a WebSocket server accepting connections from the Penpot MCP plugin
  127. - Implements request/response correlation with unique task IDs
  128. - Handles task timeouts and proper error reporting
  129. 3. **Penpot MCP Plugin** (`penpot-plugin/`):
  130. - Connects to the MCP server via WebSocket
  131. - Executes tasks in Penpot using the Plugin API
  132. - Sends structured responses back to the server#
  133. 4. **Helper Scripts** (`python-scripts/`):
  134. - Python scripts that prepare data for the MCP server (development use)
  135. The core components are written in TypeScript, rendering interactions with the
  136. Penpot Plugin API both natural and type-safe.
  137. ## Configuration
  138. The Penpot MCP server can be configured using environment variables. All configuration
  139. options use the `PENPOT_MCP_` prefix for consistency.
  140. ### Server Configuration
  141. | Environment Variable | Description | Default |
  142. |------------------------------------|----------------------------------------------------------------------------|--------------|
  143. | `PENPOT_MCP_SERVER_LISTEN_ADDRESS` | Address on which the MCP server listens (binds to) | `localhost` |
  144. | `PENPOT_MCP_SERVER_PORT` | Port for the HTTP/SSE server | `4401` |
  145. | `PENPOT_MCP_WEBSOCKET_PORT` | Port for the WebSocket server (plugin connection) | `4402` |
  146. | `PENPOT_MCP_REPL_PORT` | Port for the REPL server (development/debugging) | `4403` |
  147. | `PENPOT_MCP_SERVER_ADDRESS` | Hostname or IP address via which clients can reach the MCP server | `localhost` |
  148. | `PENPOT_MCP_REMOTE_MODE` | Enable remote mode (disables file system access). Set to `true` to enable. | `false` |
  149. ### Logging Configuration
  150. | Environment Variable | Description | Default |
  151. |------------------------|------------------------------------------------------|----------|
  152. | `PENPOT_MCP_LOG_LEVEL` | Log level: `trace`, `debug`, `info`, `warn`, `error` | `info` |
  153. | `PENPOT_MCP_LOG_DIR` | Directory for log files | `logs` |
  154. ### Plugin Server Configuration
  155. | Environment Variable | Description | Default |
  156. |-------------------------------------------|-----------------------------------------------------------------------------------------|--------------|
  157. | `PENPOT_MCP_PLUGIN_SERVER_LISTEN_ADDRESS` | Address on which the plugin web server listens (single address or comma-separated list) | (local only) |
  158. ## Beyond Local Execution
  159. The above instructions describe how to run the MCP server and plugin server locally.
  160. We are working on enabling remote deployments of the MCP server, particularly
  161. in [multi-user mode](docs/multi-user-mode.md), where multiple Penpot users will
  162. be able to connect to the same MCP server instance.
  163. To run the server remotely (even for a single user),
  164. you may set the following environment variables to configure the two servers
  165. (MCP server & plugin server) appropriately:
  166. * `PENPOT_MCP_REMOTE_MODE=true`: This ensures that the MCP server is operating
  167. in remote mode, with local file system access disabled.
  168. * `PENPOT_MCP_SERVER_LISTEN_ADDRESS` and `PENPOT_MCP_PLUGIN_SERVER_LISTEN_ADDRESS`:
  169. Set these according to your requirements for remote connectivity.
  170. To bind all interfaces, use `0.0.0.0` (use caution in untrusted networks).
  171. * `PENPOT_MCP_SERVER_ADDRESS=<your-address>`: This sets the hostname or IP address
  172. where the MCP server can be reached. The Penpot MCP Plugin uses this to construct
  173. the WebSocket URL as `ws://<your-address>:<port>` (default port: `4402`).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.