penpot-mcp
Penpot MCP server
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/montevive--penpot-mcp)HTML
<a href="/listings/montevive--penpot-mcp"><img src="/api/listings/montevive--penpot-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 421 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.