🛠️ Developer Tools

• Command-line Utilities: Powerful CLI tools for design file analysis and validation
• Python SDK: Comprehensive Python library for custom integrations
• REST API: HTTP endpoints for web application integration
• Extensible Architecture: Plugin system for custom AI workflows

🎨 AI Integration Features

• Claude Desktop & Cursor Integration: Native support for Claude AI assistant in both Claude Desktop and Cursor IDE
• Design Context Sharing: Provide design context to AI models for better responses
• Visual Component Recognition: AI can "see" and understand design components
• Natural Language Queries: Ask questions about your designs in plain English
• IDE Integration: Seamless integration with modern development environments

💡 Use Cases

For Designers

• Design Review Automation: Get instant AI feedback on accessibility, usability, and design principles
• Component Documentation: Automatically generate documentation for design systems
• Design Consistency Checks: Ensure brand guidelines compliance across projects
• Asset Organization: AI-powered tagging and categorization of design components

For Developers

• Design-to-Code Workflows: Bridge the gap between design and development with AI assistance
• API Integration: Programmatic access to design data for custom tools and workflows
• Automated Testing: Generate visual regression tests from design specifications
• Design System Sync: Keep design tokens and code components in sync

For Product Teams

• Design Analytics: Track design system adoption and component usage
• Collaboration Enhancement: AI-powered design reviews and feedback collection
• Workflow Optimization: Automate repetitive design operations and approvals
• Cross-tool Integration: Connect Penpot with other tools in your design workflow

🚀 Quick Start

Prerequisites

• Python 3.12+ (Latest Python recommended for optimal performance)
• Penpot Account (Sign up free)
• Claude Desktop or Cursor IDE (Optional, for AI integration)

Installation

Prerequisites

• Python 3.12+
• Penpot account credentials

Installation

Option 1: Install from PyPI

pip install penpot-mcp

Option 2: Using uv (recommended for modern Python development)

# Install directly with uvx (when published to PyPI)
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 .

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 (penpot.app) uses CloudFlare protection that may occasionally block API requests. If you encounter authentication errors or blocked requests:

1. Open your web browser and navigate to https://design.penpot.app
2. Log in to your Penpot account
3. Complete any CloudFlare human verification challenges if prompted
4. Once verified, the API requests should work normally for a period of time

Usage

Running the MCP Server

# 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

Debugging the MCP Server

To debug the MCP server, you can:

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

# 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

The Penpot MCP server can be integrated with AI assistants using the Model Context Protocol. It supports both Claude Desktop and Cursor IDE for seamless design workflow automation.

Claude Desktop Integration

For detailed Claude Desktop setup instructions, see CLAUDE_INTEGRATION.md.

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

Cursor IDE supports MCP servers through its AI integration features. To configure Penpot MCP with Cursor:

1. Install the MCP server (if not already installed):

   pip install penpot-mcp
   

2. Configure Cursor settings by adding the MCP server to your Cursor configuration. Open Cursor settings and add:

   {