343 lines
10 KiB
Markdown
343 lines
10 KiB
Markdown
# 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 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:
|
|
|
|
[](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 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](https://penpot.app/))
|
|
- **Claude Desktop** (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
|
|
```
|
|
|
|
## 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
|
|
|
|
## 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](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:
|
|
|
|
```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
|