DOCSEARCHbyAlgolia
Submit Docs

Penpot Model Context Protocol (MCP) Server

repository·develop·Indexed 43 days ago

https://github.com/penpot/penpot-mcp

Official MCP server and plugin that enables LLMs to interact with Penpot design files. It supports design-to-code, code-to-design, and design-to-design workflows by allowing AI clients to retrieve, modify, and create design elements via the Penpot Plugin API.

Tokens
10.4K
Snippets
35
Records
47
Agent score
58%

What's inside Penpot MCP

  1. Understand Multi-User Mode limitations

    develop

    When using multi-user mode, tools that require reading from or writing to the local file system are not supported. This is because the server cannot access the individual client's file system in a remote deployment scenario. This limitation specifically affects:

    • Import tools
    • Export tools

  2. How Penpot's MCP architecture works

    develop

    Penpot's MCP integration uses a three-part architecture to allow LLMs to interact with design files:

    1. AI Client (LLM): Uses the Model Context Protocol to send requests to the MCP Server.
    2. Penpot MCP Server: Exposes tools to the LLM for retrieving, modifying, and creating design elements. It communicates with the plugin via WebSockets.
    3. Penpot MCP Plugin: A dedicated plugin running inside Penpot that connects to the MCP Server via WebSocket. It executes the actual tasks within the Penpot environment using the Penpot Plugin API.

    This setup allows the LLM to perform complex design-to-design, code-to-design, and design-to-code workflows by executing code within the plugin environment.

  4. Setup and build the Penpot MCP Plugin

    develop

    To set up the Penpot MCP Plugin for local development, follow these steps to install dependencies, build the project, and launch the development server.

    Note: The development server runs at http://localhost:4400.

    # Install dependencies
npm install

# Build the project
npm run build

# Start the local development server
npm run dev start

  5. Connect an MCP client to the Penpot MCP server

    develop

    The server runs on port 4401 and provides two endpoints:

    • Modern Streamable HTTP: http://localhost:4401/mcp
    • Legacy SSE: http://localhost:4401/sse

    Connecting via Claude Code

    To add the server to a Claude Code project, use:

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

    Connecting via Claude Desktop (using mcp-remote proxy)

    Claude Desktop only supports stdio transport, so you must use the mcp-remote proxy to connect to the SSE endpoint.

    1. Install the proxy globally:
      npm install -g mcp-remote
    2. Update your Claude Desktop configuration file:
      • Windows: %APPDATA%/Claude/claude_desktop_config.json
      • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • Linux: ~/.config/Claude/claude_desktop_config.json

    Add the following entry under mcpServers:

    {
    "mcpServers": {
        "penpot": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
        }
    }
}
    1. Restart Claude Desktop completely (File > Quit) for changes to take effect.
    ```shellnclaude mcp add penpot -t http http://localhost:4401/mcp

  6. Use the Penpot Plugin API REPL for testing

    develop

    The Penpot MCP Server includes a REPL (Read-Eval-Print Loop) interface specifically designed for testing Penpot Plugin API calls.

    To access the REPL, identify the URL reported in the terminal output when the server starts and connect to that address.

  8. Install and run the Penpot MCP Server

    develop

    To set up the Penpot MCP Server, follow these steps to install dependencies, build the project, and start the server:

    1. Install dependencies: Run npm install to fetch required packages.
    2. Build the project: Run npm run build to compile the TypeScript source.
    3. Run the server: Run npm start to launch the MCP server.

    Once started, the server will provide a URL that can be used to connect via an MCP client.

    npm install
npm run build
npm start

  9. Load the Penpot MCP plugin in Penpot

    develop

    Once the servers are running, you must connect the plugin to the MCP server within the Penpot application:

    1. Open Penpot in your browser and navigate to a design file.
    2. Open the Plugins menu.
    3. Load the plugin using the development URL: http://localhost:4400/manifest.json (default).
    4. Open the plugin UI.
    5. In the plugin UI, click "Connect to MCP server".

    The status should change from "Not connected" to "Connected to MCP server".

    Important Notes:

    • Do not close the plugin UI while using the MCP server, as this will terminate the connection.
    • Browser Connectivity: Chromium-based browsers (Chrome, Vivaldi) may require you to approve a popup for private network access to localhost. In Brave, you may need to disable "Shields" for the Penpot website to allow local network access.

  10. Run the MCP server and plugin in Multi-User Mode

    develop

    To test the multi-user mode, which allows multiple Penpot users to connect to a single MCP server instance simultaneously, use the bootstrap command. This command launches the MCP server with the --multi-user flag and builds/launches the Penpot MCP plugin server in multi-user mode.

    WARNING

    Multi-user mode is under development and not yet fully integrated. It is intended for testing purposes only.

    npm run bootstrap:multi-user

  11. Prepare API documentation for the MCP Server

    develop

    The prepare_api_docs.py script automates the collection of API documentation from the web into a single YAML file. This file is consumed by an MCP tool to provide on-demand API documentation to an LLM.

    Running this script generates the output file at ../mcp-server/data/api_types.yml.

    pixi run python prepare_api_docs.py

  12. Authenticate users in Multi-User Mode

    develop

    In multi-user mode, authentication is handled via a userToken passed in the connection URL.

    1. MCP Server Connection: The token must be provided as a query parameter in the URL used to connect to the MCP server (e.g., http://localhost:4401/mcp?userToken=USER_TOKEN).
    2. Plugin Connection: The same token must be provided when connecting the Penpot MCP plugin to the MCP server.

    Note: Currently, for testing purposes, the token is hard-coded in the plugin's source code. In future versions, Penpot is expected to generate this token and provide it to the plugin automatically.

    http://localhost:4401/mcp?userToken=USER_TOKEN