home / mcp / penpot mcp server

Penpot MCP Server

Penpot MCP server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "montevive-penpot-mcp": {
      "command": "uvx",
      "args": [
        "penpot-mcp"
      ],
      "env": {
        "PENPOT_API_URL": "https://design.penpot.app/api",
        "PENPOT_PASSWORD": "your_penpot_password",
        "PENPOT_USERNAME": "your_penpot_username"
      }
    }
  }
}

Penpot MCP Server lets you connect AI assistants to Penpot design data using the Model Context Protocol. You run a local MCP server that exposes Penpot project data to you and your AI tools, enabling real-time design access, component analysis, asset export, and design-system automation from natural language interactions.

How to use

You run the MCP server locally and connect it to your MCP client (such as Claude Desktop or Cursor IDE). The server provides direct access to Penpot projects and files, supports visual component recognition, and enables natural language queries about your designs.

Typical workflows include asking your AI to review accessibility or usability, export assets, generate design-system documentation, or surface pattern usage across projects. You enable your MCP client to communicate with the Penpot MCP Server via an MCP connection configuration, then issue natural language requests to your AI assistant which will query Penpot through the MCP server.

How to install

Prerequisites: you need Python 3.12 or newer, a Penpot account, and optionally Claude Desktop or Cursor IDE for AI integration.

Install options allow you to choose the method you prefer for running the MCP server.

# Option 1: Install from PyPI
pip install penpot-mcp

# Option 2: Using uv for modern Python development
uvx penpot-mcp
# For local development, use uvx with local path
uvx --from . penpot-mcp
# Or install in a project with uv
uv add penpot-mcp

# Option 3: Install from source
# Clone the repository
git clone https://github.com/montevive/penpot-mcp.git
cd penpot-mcp

# Using uv (recommended)
uv sync
uv run penpot-mcp

# Or using traditional pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Additional configuration and run details

Create a configuration file with your Penpot credentials or set environment variables to point the MCP server at your Penpot account.

PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=true

Running the MCP server

Start the MCP server using the chosen runtime. The examples assume you installed with uvx or pip and that your environment is prepared with Penpot credentials.

# Using uvx (when published to PyPI)
uvx penpot-mcp

# Using uvx for local development
uvx --from . penpot-mcp

# Using uv in a project (recommended for local development)
uv run penpot-mcp

# Using the entry point (if installed)
penpot-mcp

# Or using the module directly
python -m penpot_mcp.server.mcp_server

Troubleshooting and tips

If you encounter CloudFlare-driven blocks when authenticating with Penpot, complete any required verification in your browser to obtain valid API access tokens for the MCP server.

Usage with MCP clients

Configure your MCP client to connect to the local server or to a remote endpoint if you deploy it on a server. You can integrate with Claude Desktop or Cursor IDE by pointing the client at the MCP server and providing the necessary environment credentials.

Available tools

penpot_tree

Generate a tree visualization of a Penpot file to understand its object structure.

penpot_validate

Validate a Penpot file against the schema to ensure it conforms to the expected structure.

penpot_client

Run the example Penpot client to interact with the MCP server from a command line workflow.

mcp_monitor

Monitor and interact with your MCP server from the command line while it runs.

mcp_inspector

Open the MCP Inspector to visualize and test MCP interactions in a browser (requires Node.js).