What is Penpot MCP?
Penpot MCP is Penpot's official Model Context Protocol server. It lets an AI client such as Cursor or another MCP client read a design file and change it by running code through Penpot's plugin API. You can use the hosted server from your Penpot account or run it locally with Node.js.
Penpot MCP is the official Model Context Protocol server for Penpot, the open-source design tool. It gives an AI client a way to inspect your open design file and to change it, so the agent works on your real components and styles.
The server exposes tools to the client. A Penpot plugin running in your open browser tab connects that file to the server over WebSocket. The agent then writes and runs code snippets through Penpot's plugin API.
The code is MPL-2.0. Development now lives in the mcp folder of the main Penpot repository, and the older penpot/penpot-mcp repository points there.
What it changes in your workflow
- Design system upkeep. Create spacing, type and colour tokens, rename layers to a scheme, organise components and audit styles for redundancy.
- Broad edits. Apply a palette update across a whole file or generate component variants.
- Design to code. Extract layout structure, inspect tokens and generate semantic, modular HTML and CSS from a design.
- Asset export. Pull out only the icons a file uses.
- New screens. Draft screens from an existing design system.
Because the agent reads your real file, it starts from your own tokens and components instead of inventing a style.
Who it is for
- Designers who maintain a design system in Penpot and want the dull maintenance done by an agent.
- Developers who want exact values from a file instead of guessing a hex code from a screenshot.
- Teams who prefer a hosted setup with nothing to install.
Who it is not for
- Anyone expecting a one-click Penpot to WordPress export. The server stops at the design.
- Setups that rely on a weak model. Penpot says weaker models, including most locally hosted ones, are unlikely to give usable results beyond simple tasks.
- Workflows where the Penpot tab cannot stay open, because the plugin runs inside it.
Hosted or local Penpot MCP
| Hosted | Local | |
|---|---|---|
| Install | None. Enable it in your Penpot account | Node.js 20 or later, then npx -y @penpot/mcp@latest |
| Auth | Personal MCP key inside the server URL | Plugin loaded from localhost, no key |
| Local files | No. import_image from local paths is unavailable | Yes |
| Best for | Working on designs only | Coding tasks that need files on disk |
Use it with UiChemy
Penpot MCP does not publish to WordPress, and UiChemy lists no Penpot import. The route that holds is code. Have the agent write a section as HTML and CSS, preview it at a URL, then bring that build into WordPress with UiChemy AI to WordPress. For the Figma side of the same idea, see Figma Make vs Lovable.
Pair the agent with the frontend-design skill if you want a design plan before it writes code. For the WordPress end, Lovable to Elementor walks through an import with UiChemy AI to WordPress.
Want the WordPress end of that route? Get Started with UiChemy.
Connect Penpot MCP to your AI client
npx -y @penpot/mcp@latestPick a route
Hosted needs no install. Local runs on your machine and can read local files.
Hosted: enable the server
In Penpot open Your account, Integrations, MCP Server and set the status to Enabled. Create your MCP key when asked. It is shown once, and only one key can exist per user.
Hosted: add the URL
Copy the server URL, which carries your key, then run
npx -y add-mcp -g -n penpot <URL>. In Claude Desktop, add the URL as a custom connector instead. Then open a file and use File, MCP Server, Connect.Local: start the servers
Install Node.js 20 or later, run
npx -y @penpot/mcp@latestand keep that terminal open.Local: load the plugin
In a design file go to Plugins, Load from URL, enter
http://localhost:4400/manifest.json, open the plugin and click Connect to MCP server until it says Connected.Connect your client
Point it at
http://localhost:4401/mcp. For Claude Code, runclaude mcp add penpot -t http http://localhost:4401/mcp. Claude Desktop only speaks stdio, so use the mcp-remote entry in the config above.Keep the tab awake
Keep the Penpot tab in the foreground. Browsers can freeze background tabs, and the server then reports that the tab looks suspended.
Client configuration
{
"mcpServers": {
"penpot": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:4401/mcp", "--allow-http"]
}
}
}Endpoints and ports
http://localhost:4401/mcpStreamable HTTP. The legacy /sse and /messages endpoints are no longer supported.http://localhost:4400/manifest.jsonLoad it from Plugins, Load from URL.https://<your-penpot-domain>/mcp/stream?userToken=YOUR_MCP_KEYCopy it from Your account, Integrations, MCP Server. Treat it like a password.PENPOT_MCP_SERVER_PORTEnvironment variable that changes port 4401.https://help.penpot.app/mcp/Penpot's MCP help page.What you can do with it
- Works on your real fileThe agent reads the components, styles and tokens you already built, so output follows your design system.
- Token and style maintenanceCreate spacing, type and colour tokens, apply them consistently and audit styles for duplicates.
- Bulk editsRename layers to a scheme, generate component variants and apply a palette change across a file.
- Design to codeExtract layout structure and generate semantic, modular HTML and CSS from a design.
- Asset exportExport assets, for example only the icons a file uses.
- Hosted or self-runUse the hosted server from your account, or run it locally with Node.js for access to local files.
- Fails fast on a sleeping tabIf the browser freezes the Penpot tab, the server reports it at once instead of waiting out a long timeout.
Tools it exposes
execute_code
Runs a code snippet inside Penpot's plugin environment. The general-purpose tool for reading, creating and restyling shapes, tokens and components.
high_level_overview
Gives the agent an overview of the open file so it can orient itself before it acts.
penpot_api_info
Returns reference information about Penpot's plugin API, so the model can look up what it may call.
export_shape
Exports a shape from the design. In hosted mode it is limited, with no export straight to a local file path.
import_image
Imports an image into the design from a local path. Local mode only.
Frequently asked questions
What is Penpot MCP?
Penpot MCP is Penpot's official Model Context Protocol server. An AI client such as Claude Code or Cursor connects to it, reads your open design file and edits it by running code through Penpot's plugin API. A Penpot plugin in your browser tab links the file to the server.
How do I install Penpot MCP?
Two routes. Hosted: enable MCP Server under Your account, Integrations, create your key, copy the server URL and add it to your client. Local: install Node.js 20 or later, run npx -y @penpot/mcp@latest, load the plugin from the local manifest on port 4400 and point your client at the local MCP endpoint on port 4401.
Is Penpot MCP hosted or local?
Both exist. The hosted server needs no install, uses a personal MCP key inside its URL and has no local file access. The local server runs on your machine, can read local files and suits coding tasks. Penpot's README points design-only work to the hosted route.
Which AI clients work with Penpot MCP?
Penpot's help page names Cursor and Claude Code, and any client that can connect to a remote or HTTP MCP server. Claude Desktop only speaks stdio, so the local server goes through the mcp-remote proxy, while the hosted server can be added as a custom connector.
Can Penpot MCP change my designs?
Yes. Once connected, the client can run write operations that change the focused Penpot page, including creating, renaming, moving, deleting and restyling. Start with read-only prompts, ask the agent to describe changes before applying them, and prefer small reversible steps. Work on a duplicate first.
Why does Penpot MCP say my tab is suspended?
The plugin runs inside your Penpot browser tab. If the browser freezes or unloads that tab, the server cannot run tasks and reports it. Focus the tab again and retry. In Chrome, add your Penpot site under Settings, Performance, Always keep these sites active.
Can I turn a Penpot design into a WordPress page?
Not directly. Penpot MCP stops at the design, and UiChemy lists no Penpot import. The route that holds is code: have the agent write HTML and CSS for a section, preview it at a URL, then bring it into WordPress with UiChemy AI to WordPress. Check the result against your design.
Which model should I use with Penpot MCP?
Penpot recommends the most capable model you have, ideally a frontier model with vision, since many design tasks need visual inspection. Most commercial models already support vision. Weaker models, including most locally hosted ones, are unlikely to give usable results beyond simple tasks.