Supports workflow automation for Penpot design files through GitHub Actions and CI integration. Enables automated testing and validation of design components.
Connects to Penpot's API for design file access, component analysis, export automation, and design validation. Enables browsing projects, analyzing design components, exporting assets, and validating design system compliance.
Provides a Python SDK for custom integrations with Penpot designs, enabling programmatic access to design files and components for workflow automation.
Penpot MCP Server 🎨🤖
🚀 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 (in both Claude Desktop and Cursor IDE) 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 Desktop, Cursor IDE, 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 & 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
Option 2: Using uv (recommended for modern Python development)
Option 3: Install from source
Configuration
Create a .env
file based on env.example
with your Penpot credentials:
Usage
Running the MCP Server
Debugging the MCP Server
To debug the MCP server, you can:
Enable debug mode in your
.env
file by settingDEBUG=true
Use the Penpot API CLI for testing API operations:
Command-line Tools
The package includes utility command-line tools:
MCP Monitoring & Testing
MCP CLI Monitor
MCP Inspector
Using the Client
MCP Resources & Tools
Resources
server://info
- Server status and informationpenpot://schema
- Penpot API schema as JSONpenpot://tree-schema
- Penpot object tree schema as JSONrendered-component://{component_id}
- Rendered component imagespenpot://cached-files
- List of cached Penpot files
Tools
list_projects
- List all Penpot projectsget_project_files
- Get files for a specific projectget_file
- Retrieve a Penpot file by its ID and cache itexport_object
- Export a Penpot object as an imageget_object_tree
- Get the object tree structure for a Penpot objectsearch_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):
Cursor IDE Integration
Cursor IDE supports MCP servers through its AI integration features. To configure Penpot MCP with Cursor:
Install the MCP server (if not already installed):
pip install penpot-mcpConfigure Cursor settings by adding the MCP server to your Cursor configuration. Open Cursor settings and add:
{ "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 in your project root:PENPOT_API_URL=https://design.penpot.app/api PENPOT_USERNAME=your_penpot_username PENPOT_PASSWORD=your_penpot_passwordStart the MCP server in your project:
# In your project directory penpot-mcpUse in Cursor: Once configured, you can interact with your Penpot designs directly 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?"
Key Integration Features
Both Claude Desktop and Cursor integration provide:
Direct access to Penpot projects and files
Visual component analysis with AI-powered insights
Design export capabilities for assets and components
Natural language queries about your design files
Real-time design feedback and suggestions
Design system documentation generation
Package Structure
Development
Testing
The project uses pytest for testing:
Linting
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add some amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Bridges AI language models with Penpot design platform, enabling AI assistants to analyze, search, and interact with design files programmatically for automated design workflows.
Related MCP Servers
- -securityAlicense-qualityProvides a bridge between large language models and the Metasploit Framework, enabling AI assistants to access and control penetration testing functionality through natural language.Last updated -302Apache 2.0
- AsecurityFlicenseAqualityA powerful AI-driven tool that helps developers create beautiful, modern UI components instantly through natural language descriptions.Last updated -43,508
- AsecurityAlicenseAqualityThis package enables AI assistants (Claude, GPT, etc.) to work directly with Buildable projects using the Model Context Protocol (MCP). AI assistants can get project context, manage tasks and track progress (for projects created at https://bldbl.dev).Last updated -7216MIT License
- -securityFlicense-qualityA bridge that provides AI assistants with access to WaniKani user data and functionality, enabling them to retrieve learning progress, identify difficult items, and offer personalized Japanese language learning assistance.Last updated -1