Penpot MCP server for AI agents

Penpot MCP Server enables AI-powered design workflow automation by connecting Claude AI and other LLMs to Penpot designs via Model Context Protocol. This integration allows AI assistants to understand, analyze, and interact with your design files programmatically, streamlining design tasks and enabling intelligent design analysis.

Installation

Prerequisites

Python 3.12+
Penpot account credentials

Installation Options

From PyPI

pip install penpot-mcp

Using uv (recommended)

# Install directly with uvx
uvx penpot-mcp

# For local development
uvx --from . penpot-mcp

# Or install in a project with uv
uv add penpot-mcp

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 .

Configuration

Create a .env file based on env.example with your Penpot credentials:

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

⚠️ CloudFlare Protection Notice: The Penpot cloud site uses CloudFlare protection that may occasionally block API requests. If you encounter authentication errors:

Open your web browser and navigate to https://design.penpot.app

Log in to your Penpot account

Complete any CloudFlare human verification challenges if prompted

Once verified, the API requests should work normally for a period of time

Usage

Running the MCP Server

# Using uvx
uvx penpot-mcp

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

# Using uv in a project
uv run penpot-mcp

# Using the entry point
penpot-mcp

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

Debugging the MCP Server

To debug the MCP server:

Enable debug mode in your .env file by setting DEBUG=true
Use the Penpot API CLI for testing:

# Test API connection with debug output
python -m penpot_mcp.api.penpot_api --debug list-projects

# Get details for a specific project
python -m penpot_mcp.api.penpot_api --debug get-project --id YOUR_PROJECT_ID

# List files in a project
python -m penpot_mcp.api.penpot_api --debug list-files --project-id YOUR_PROJECT_ID

# Get file details
python -m penpot_mcp.api.penpot_api --debug get-file --file-id YOUR_FILE_ID

Command-line Tools

The package includes utility command-line tools:

# Generate a tree visualization of a Penpot file
penpot-tree path/to/penpot_file.json

# Validate a Penpot file against the schema
penpot-validate path/to/penpot_file.json

MCP Monitoring & Testing

MCP CLI Monitor

# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server

# In another terminal, use mcp-cli to monitor and interact with your server
python -m mcp.cli monitor python -m penpot_mcp.server.mcp_server

# Or connect to an already running server on a specific port
python -m mcp.cli monitor --port 5000

MCP Inspector

# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server

# In another terminal, run the MCP Inspector (requires Node.js)
npx @modelcontextprotocol/inspector

Using the Client

# Run the example client
penpot-client

MCP Resources & Tools

Resources

server://info - Server status and information
penpot://schema - Penpot API schema as JSON
penpot://tree-schema - Penpot object tree schema as JSON
rendered-component://{component_id} - Rendered component images
penpot://cached-files - List of cached Penpot files

Tools

list_projects - List all Penpot projects
get_project_files - Get files for a specific project
get_file - Retrieve a Penpot file by its ID and cache it
export_object - Export a Penpot object as an image
get_object_tree - Get the object tree structure for a Penpot object
search_object - Search for objects within a Penpot file by name

AI Integration

Claude Desktop Integration

Add the following configuration to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Cursor IDE Integration

To configure Penpot MCP with Cursor:

Install the MCP server:
```
pip install penpot-mcp
```

Configure Cursor settings by adding to your Cursor configuration:

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

Alternative: Use environment variables by creating a .env file:

PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password

Start the MCP server:
```
penpot-mcp
```
Use in Cursor: Ask questions like:
- "Show me all projects in my Penpot account"
- "Analyze the design components in project X"
- "Export the main button component as an image"
- "What design patterns are used in this file?"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect