Penpot MCP server for AI agents

Penpot MCP Server connects Claude AI and other Large Language Models (LLMs) to Penpot designs using the Model Context Protocol. This integration allows AI assistants to understand, analyze, and interact with your Penpot design files programmatically, enabling AI-powered design analysis, workflow automation, and intelligent design search capabilities.

Prerequisites

Python 3.12+
Penpot account credentials
Claude Desktop or Cursor IDE (optional, for AI integration)

Installation

Option 1: Install from PyPI

pip install penpot-mcp

Option 2: 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

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 .

Configuration

Create a .env file 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

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

# Using the module directly
python -m penpot_mcp.server.mcp_server

Debugging

Enable debug mode in your .env file with DEBUG=true and 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

Utility command-line tools are included:

# 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, 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
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

Available 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

Available 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 to your Claude Desktop config 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"
      }
    }
  }
}

Cursor IDE Integration

Install and 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"
      }
    }
  }
}

Alternatively, 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
```
Interact with your Penpot designs in Cursor by asking 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 add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.