Usage
To use the Penpot MCP server, you must
- run the MCP server and connect your AI client to it,
- run the web server providing the Penpot MCP plugin, and
- open the Penpot MCP plugin in Penpot and connect it to the MCP server.
Follow the steps below to enable the integration.
Prerequisites
The project requires Node.js (tested with v22).
Following the installation of Node.js, the tools npm and npx should be
available in your terminal.
1. Build & Launch the MCP Server and the Plugin Server
If it's your first execution, install the required dependencies:
npm install
Then build all components and start the two servers:
npm run bootstrap
This bootstrap command will:
- install dependencies for all components (
npm run install:all)
- build all components (
npm run build:all)
- start all components (
npm run start:all)
2. Load the Plugin in Penpot and Establish the Connection
[!NOTE]
Browser Connectivity Restrictions
Starting with Chromium version 142, the private network access (PNA) restrictions have been hardened,
and when connecting to localhost from a web application served from a different origin
(such as https://design.penpot.app), the connection must explicitly be allowed.
Most Chromium-based browsers (e.g. Chrome, Vivaldi) will display a popup requesting permission
to access the local network. Be sure to approve the request to allow the connection.
Some browsers take additional security measures, and you may need to disable them.
For example, in Brave, disable the "Shield" for the Penpot website to allow local network access.
If your browser refuses to connect to the locally served plugin, check its configuration or
try a different browser (e.g. Firefox) that does not enforce these restrictions.
- Open Penpot in your browser
- Navigate to a design file
- Open the Plugins menu
- Load the plugin using the development URL (
http://localhost:4400/manifest.json by default)
- Open the plugin UI
- In the plugin UI, click "Connect to MCP server".
The connection status should change from "Not connected" to "Connected to MCP server".
(Check the browser's developer console for WebSocket connection logs.
Check the MCP server terminal for WebSocket connection messages.)
[!IMPORTANT]
Do not close the plugin's UI while using the MCP server, as this will close the connection.
3. Connect an MCP Client
By default, the server runs on port 4401 and provides:
- Modern Streamable HTTP endpoint:
http://localhost:4401/mcp
- Legacy SSE endpoint:
http://localhost:4401/sse
These endpoints can be used directly by MCP clients that support them.
Simply configure the client to connect the MCP server by providing the respective URL.
When using a client that only supports stdio transport,
a proxy like mcp-remote is required.
Using a Proxy for stdio Transport
The mcp-remote package can proxy stdio transport to HTTP/SSE,
allowing clients that support only stdio to connect to the MCP server indirectly.
-
Install mcp-remote globally if you haven't already:
npm install -g mcp-remote
-
Use mcp-remote to provide the launch command for your MCP client:
npx -y mcp-remote http://localhost:4401/sse --allow-http
Example: Claude Desktop
For Windows and macOS, there is the official Claude Desktop app, which you can use as an MCP client.
For Linux, there is an unofficial community version.
Since Claude Desktop natively supports only stdio transport, you will need to use a proxy like mcp-remote.
Install it as described above.
To add the server to Claude Desktop's configuration, locate the configuration file (or find it via Menu / File / Settings / Developer):
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Add a penpot entry under mcpServers with the following content:
{
"mcpServers": {
"penpot": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
}
}
}
After updating the configuration file, restart Claude Desktop completely for the changes to take effect.
[!IMPORTANT]
Be sure to fully quit the app for the changes to take effect; closing the window is not sufficient.
To fully terminate the app, choose Menu / File / Quit.
After the restart, you should see the MCP server listed when clicking on the "Search and tools" icon at the bottom
of the prompt input area.
Example: Claude Code
To add the Penpot MCP server to a Claude Code project, issue the command
claude mcp add penpot -t http http://localhost:4401/mcp