penpot-mcp-server/README.md

Penpot MCP Server 🎨🤖

AI-Powered Design Workflow Automation
Connect Claude AI and other LLMs to Penpot designs via Model Context Protocol

---

🚀 What is Penpot MCP?

Penpot MCP is a revolutionary Model Context Protocol (MCP) server that bridges the gap between AI language models and Penpot, the open-source design and prototyping platform. This integration enables AI assistants like Claude to understand, analyze, and interact with your design files programmatically.

🎯 Key Benefits

• 🤖 AI-Native Design Analysis: Let Claude AI analyze your UI/UX designs, provide feedback, and suggest improvements
• ⚡ Automated Design Workflows: Streamline repetitive design tasks with AI-powered automation
• 🔍 Intelligent Design Search: Find design components and patterns across your projects using natural language
• 📊 Design System Management: Automatically document and maintain design systems with AI assistance
• 🎨 Cross-Platform Integration: Works with any MCP-compatible AI assistant (Claude, ChatGPT, etc.)

🎥 Demo Video

Check out our demo video to see Penpot MCP in action:

✨ Features

🔌 Core Capabilities

• MCP Protocol Implementation: Full compliance with Model Context Protocol standards
• Real-time Design Access: Direct integration with Penpot's API for live design data
• Component Analysis: AI-powered analysis of design components and layouts
• Export Automation: Programmatic export of design assets in multiple formats
• Design Validation: Automated design system compliance checking

🛠️ 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 Integration: Native support for Claude AI assistant
• 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

💡 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 (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

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

Claude AI Integration

The Penpot MCP server can be integrated with Claude AI using the Model Context Protocol. For detailed instructions, see CLAUDE_INTEGRATION.md.

Key features of the Claude integration:

• Direct integration with Claude Desktop
• Access to Penpot projects and files
• Ability to view and analyze design components
• Export Penpot objects as images

Package Structure

penpot_mcp/
├── api/              # Penpot API client
├── server/           # MCP server implementation
│   ├── mcp_server.py # Main MCP server
│   └── client.py     # Client implementation
├── tools/            # Utility tools
│   ├── cli/          # Command-line interfaces
│   └── penpot_tree.py # Penpot object tree visualization
├── resources/        # Resource files and schemas
└── utils/            # Helper utilities

Development

Testing

The project uses pytest for testing:

# Using uv (recommended)
uv sync --extra dev
uv run pytest

# Run with coverage
uv run pytest --cov=penpot_mcp tests/

# Using traditional pip
pip install -e ".[dev]"
pytest
pytest --cov=penpot_mcp tests/

Linting

# Using uv (recommended)
uv sync --extra dev

# Set up pre-commit hooks
uv run pre-commit install

# Run linting
uv run python lint.py

# Auto-fix linting issues
uv run python lint.py --autofix

# Using traditional pip
pip install -r requirements-dev.txt
pre-commit install
./lint.py
./lint.py --autofix

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure your code follows the project's coding standards and includes appropriate tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Penpot - The open-source design and prototyping platform
• Model Context Protocol - The standardized protocol for AI model context