Content
# Penpot MCP Server 🎨🤖
<p align="center">
<img src="images/penpot-mcp.png" alt="Penpot MCP Logo" width="400"/>
</p>
<p align="center">
<strong>AI-Powered Design Workflow Automation</strong><br>
Connect Claude AI and other LLMs to Penpot designs via Model Context Protocol
</p>
<p align="center">
<a href="https://github.com/montevive/penpot-mcp/blob/main/LICENSE">
<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
</a>
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python Version">
</a>
<a href="https://pypi.org/project/penpot-mcp/">
<img src="https://img.shields.io/pypi/v/penpot-mcp" alt="PyPI version">
</a>
<a href="https://github.com/montevive/penpot-mcp/actions">
<img src="https://img.shields.io/github/workflow/status/montevive/penpot-mcp/CI" alt="Build Status">
</a>
</p>
---
## 🚀 What is Penpot MCP?
**Penpot MCP** is a revolutionary Model Context Protocol (MCP) server that bridges the gap between AI language models and [Penpot](https://penpot.app/), 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:
[](https://www.youtube.com/watch?v=vOMEh-ONN1k)
## ✨ 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](https://penpot.app/))
- **Claude Desktop or Cursor IDE** (Optional, for AI integration)
## Installation
### Prerequisites
- Python 3.12+
- Penpot account credentials
### Installation
#### Option 1: Install from PyPI
```bash
pip install penpot-mcp
```
#### Option 2: Using uv (recommended for modern Python development)
```bash
# 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
```bash
# 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](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
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](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):
```json
{
"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):
```bash
pip install penpot-mcp
```
2. **Configure Cursor settings** by adding the MCP server to your Cursor configuration. Open Cursor settings and add:
```json
{
"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. **Alternative: Use environment variables** by creating a `.env` file in your project root:
```bash
PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
```
4. **Start the MCP server** in your project:
```bash
# In your project directory
penpot-mcp
```
5. **Use 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
```
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:
```bash
# 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
```bash
# 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](LICENSE) file for details.
## Acknowledgments
- [Penpot](https://penpot.app/) - The open-source design and prototyping platform
- [Model Context Protocol](https://modelcontextprotocol.io) - The standardized protocol for AI model context
Connection Info
You Might Also Like
No recommendations available