Penpot MCP Server: Archived LLM Bridge for Penpot Design Files

What the Penpot MCP Server Did and Its Current Status

Penpot MCP Server provided a bridge between large language models and an open Penpot design file. An LLM connected to the server could query design data, transform existing elements, and create new components using the Penpot Plugin API. The server acted as the intermediary, exposing tools through the Model Context Protocol and forwarding them to a plugin running inside Penpot.

The README includes a prominent notice: the repository was archived on 2026-02-03, and its contents were fully integrated into the main Penpot repository at https://github.com/penpot/penpot/tree/develop/mcp. The metadata for this repository shows Archived as no, but the README text itself is the authoritative statement, and it says archived.

The last push was on 2026-03-19, which is more than six months before this review. The repository has no GitHub releases and no active maintenance. The information below describes the architecture and setup as documented in this repository, but anyone starting a new integration should use the code in the main Penpot repository.

Architecture: Three Components Over WebSocket

The repository is a monorepo with four components. Common Types (common/) holds shared TypeScript definitions for the request-response protocol, ensuring type safety across the server and plugin. The Penpot MCP Server (mcp-server/) exposes MCP tools to LLMs, runs a WebSocket server that the Penpot plugin connects to, and handles request-response correlation using unique task IDs with timeouts.

The Penpot MCP Plugin (penpot-plugin/) runs inside Penpot as a regular plugin using the Penpot Plugin API. It connects to the MCP server over WebSocket and executes tool calls from the LLM by running code within the plugin environment. The README states that the LLM is free to write and execute arbitrary code snippets within the Penpot Plugin environment to accomplish its tasks. The fourth component is python-scripts/ (visible in the top-level entries), which is not described in the main README.

This architecture means the LLM never communicates with Penpot directly. All commands go through the MCP server, then over WebSocket to the plugin, which executes them inside the Penpot environment. The plugin UI must remain open for the connection to stay alive.

Installing and Starting the Servers

Node.js v22 is required. The README notes that npm and npx should be available after the Node.js install. For a first run:

npm install

Then build all components and start both servers in one command:

npm run bootstrap

The bootstrap command runs three steps in sequence: install:all installs dependencies for all components, build:all compiles them, and start:all starts both the MCP server and the plugin development server. After bootstrap, the MCP server listens on port 4401 and the plugin server on port 4400.

The MCP server exposes two transport endpoints. The streamable HTTP endpoint is at http://localhost:4401/mcp. The legacy SSE endpoint is at http://localhost:4401/sse. MCP clients that support HTTP or SSE can connect directly using these URLs.

Connecting Claude Desktop and Claude Code

Claude Desktop natively supports only stdio transport. To connect it to the Penpot MCP server, the README instructs installing mcp-remote as a proxy:

npm install -g mcp-remote

Then add a penpot entry to the Claude Desktop configuration file. On macOS, the file is at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "penpot": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
        }
    }
}

After updating the configuration file, Claude Desktop must be fully quit and restarted. The README notes that closing the window alone is not sufficient.

For Claude Code, the command is simpler:

claude mcp add penpot -t http http://localhost:4401/mcp

This registers the Penpot MCP server with Claude Code using the streamable HTTP transport.

Loading the Plugin in Penpot and Browser Restrictions

After the servers are running, the plugin must be loaded in Penpot. The steps are: open Penpot in a browser, navigate to a design file, open the Plugins menu, load the plugin using the development URL (http://localhost:4400/manifest.json by default), and open the plugin UI. Click Connect to MCP server in the plugin UI; the status changes from Not connected to Connected to MCP server.

The README flags a browser compatibility issue. Starting with Chromium version 142, private network access restrictions prevent web applications served from a remote origin from connecting to localhost. Chromium-based browsers display a popup requesting permission; it must be approved. Some browsers, such as Brave, take additional measures; the Brave Shield must be disabled for the Penpot website to allow local network access. Firefox does not enforce these restrictions according to the README.

The plugin UI must remain open for the entire session. Closing it closes the WebSocket connection and breaks the integration.

Limitations of This Repository

The primary limitation is the archived state. The repository no longer receives updates, and any bugs or incompatibilities with newer versions of Penpot, Node.js, or MCP clients will not be fixed here. The main Penpot repository at penpot/penpot carries the actively maintained version.

The architecture requires three running processes: the MCP server, the plugin dev server, and Penpot itself with the plugin loaded. On a developer's machine, this means managing three processes simultaneously. The plugin UI must remain open, which ties up a browser tab and requires that tab to stay in the foreground or at least not be suspended by the browser.

The LLM executing arbitrary code within the Penpot Plugin environment is a design choice that gives it broad capability but also means the model can make unintended changes. The README does not describe any safeguards, rollback mechanism, or confirmation step before the model executes a code snippet.

There is no multi-user mode described in the default bootstrap command (though build:all-multi-user is listed as a script in package.json, suggesting it exists). The default single-user setup ties the plugin to one Penpot session.

How Penpot MCP Compares to Using the Penpot Plugin API Directly

The Penpot Plugin API lets developers write plugins that run inside the Penpot environment and manipulate design files programmatically. A developer can write a plugin that creates specific components, applies styles, or queries element data without any LLM involvement. This is deterministic and predictable.

Penpot MCP Server wraps that same Plugin API behind an MCP interface, allowing an LLM to issue free-form design instructions that the model translates into API calls at runtime. The benefit is natural language interaction: a designer or developer can describe a layout goal and have the model implement it. The drawback is the non-determinism of the model's code generation and the operational complexity of keeping both the MCP server and the plugin connected.

Figma, a proprietary cloud-based design tool, follows a similar plugin architecture for programmatic design manipulation. Figma does not self-host. Penpot is open-source and can be self-hosted, which is the primary reason teams choose it over Figma. The MCP integration extends that distinction to LLM-driven design workflows that a self-hosted team can run entirely on their own infrastructure.

Editorial conclusion

The penpot/penpot-mcp repository is archived. Its contents are now at https://github.com/penpot/penpot/tree/develop/mcp. Designers and engineers building LLM-to-Penpot integrations should start from that location rather than this repository. The setup described here (npm run bootstrap, loading the plugin in Penpot, connecting an MCP client) still reflects the architecture, but the actively maintained version lives in the main Penpot repo. Teams evaluating Penpot with MCP tooling should verify that the integration instructions in the main repository match their Claude Desktop, Claude Code, or other MCP client version before investing setup time.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. penpot/penpot-mcp on GitHub
4. README