Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/montevive--penpot-mcp/badge.svg)](/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

i

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)

  1. # Penpot MCP Server 🎨🤖
  2. <p align="center">
  3. <img src="images/penpot-mcp.png" alt="Penpot MCP Logo" width="400"/>
  4. </p>
  5. <p align="center">
  6. <strong>AI-Powered Design Workflow Automation</strong><br>
  7. Connect Claude AI and other LLMs to Penpot designs via Model Context Protocol
  8. </p>
  9. <p align="center">
  10. <a href="https://github.com/montevive/penpot-mcp/blob/main/LICENSE">
  11. <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
  12. </a>
  13. <a href="https://www.python.org/downloads/">
  14. <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python Version">
  15. </a>
  16. <a href="https://pypi.org/project/penpot-mcp/">
  17. <img src="https://img.shields.io/pypi/v/penpot-mcp" alt="PyPI version">
  18. </a>
  19. <a href="https://github.com/montevive/penpot-mcp/actions">
  20. <img src="https://img.shields.io/github/workflow/status/montevive/penpot-mcp/CI" alt="Build Status">
  21. </a>
  22. </p>
  23. ---
  24. ## 🚀 What is Penpot MCP?
  25. **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.
  26. ### 🎯 Key Benefits
  27. - **🤖 AI-Native Design Analysis**: Let Claude AI analyze your UI/UX designs, provide feedback, and suggest improvements
  28. - **⚡ Automated Design Workflows**: Streamline repetitive design tasks with AI-powered automation
  29. - **🔍 Intelligent Design Search**: Find design components and patterns across your projects using natural language
  30. - **📊 Design System Management**: Automatically document and maintain design systems with AI assistance
  31. - **🎨 Cross-Platform Integration**: Works with any MCP-compatible AI assistant (Claude Desktop, Cursor IDE, etc.)
  32. ## 🎥 Demo Video
  33. Check out our demo video to see Penpot MCP in action:
  34. [![Penpot MCP Demo](https://img.youtube.com/vi/vOMEh-ONN1k/0.jpg)](https://www.youtube.com/watch?v=vOMEh-ONN1k)
  35. ## ✨ Features
  36. ### 🔌 Core Capabilities
  37. - **MCP Protocol Implementation**: Full compliance with Model Context Protocol standards
  38. - **Real-time Design Access**: Direct integration with Penpot's API for live design data
  39. - **Component Analysis**: AI-powered analysis of design components and layouts
  40. - **Export Automation**: Programmatic export of design assets in multiple formats
  41. - **Design Validation**: Automated design system compliance checking
  42. ### 🛠️ Developer Tools
  43. - **Command-line Utilities**: Powerful CLI tools for design file analysis and validation
  44. - **Python SDK**: Comprehensive Python library for custom integrations
  45. - **REST API**: HTTP endpoints for web application integration
  46. - **Extensible Architecture**: Plugin system for custom AI workflows
  47. ### 🎨 AI Integration Features
  48. - **Claude Desktop & Cursor Integration**: Native support for Claude AI assistant in both Claude Desktop and Cursor IDE
  49. - **Design Context Sharing**: Provide design context to AI models for better responses
  50. - **Visual Component Recognition**: AI can "see" and understand design components
  51. - **Natural Language Queries**: Ask questions about your designs in plain English
  52. - **IDE Integration**: Seamless integration with modern development environments
  53. ## 💡 Use Cases
  54. ### For Designers
  55. - **Design Review Automation**: Get instant AI feedback on accessibility, usability, and design principles
  56. - **Component Documentation**: Automatically generate documentation for design systems
  57. - **Design Consistency Checks**: Ensure brand guidelines compliance across projects
  58. - **Asset Organization**: AI-powered tagging and categorization of design components
  59. ### For Developers
  60. - **Design-to-Code Workflows**: Bridge the gap between design and development with AI assistance
  61. - **API Integration**: Programmatic access to design data for custom tools and workflows
  62. - **Automated Testing**: Generate visual regression tests from design specifications
  63. - **Design System Sync**: Keep design tokens and code components in sync
  64. ### For Product Teams
  65. - **Design Analytics**: Track design system adoption and component usage
  66. - **Collaboration Enhancement**: AI-powered design reviews and feedback collection
  67. - **Workflow Optimization**: Automate repetitive design operations and approvals
  68. - **Cross-tool Integration**: Connect Penpot with other tools in your design workflow
  69. ## 🚀 Quick Start
  70. ### Prerequisites
  71. - **Python 3.12+** (Latest Python recommended for optimal performance)
  72. - **Penpot Account** ([Sign up free](https://penpot.app/))
  73. - **Claude Desktop or Cursor IDE** (Optional, for AI integration)
  74. ## Installation
  75. ### Prerequisites
  76. - Python 3.12+
  77. - Penpot account credentials
  78. ### Installation
  79. #### Option 1: Install from PyPI
  80. ```bash
  81. pip install penpot-mcp
  82. ```
  83. #### Option 2: Using uv (recommended for modern Python development)
  84. ```bash
  85. # Install directly with uvx (when published to PyPI)
  86. uvx penpot-mcp
  87. # For local development, use uvx with local path
  88. uvx --from . penpot-mcp
  89. # Or install in a project with uv
  90. uv add penpot-mcp
  91. ```
  92. #### Option 3: Install from source
  93. ```bash
  94. # Clone the repository
  95. git clone https://github.com/montevive/penpot-mcp.git
  96. cd penpot-mcp
  97. # Using uv (recommended)
  98. uv sync
  99. uv run penpot-mcp
  100. # Or using traditional pip
  101. python -m venv .venv
  102. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  103. pip install -e .
  104. ```
  105. ### Configuration
  106. Create a `.env` file based on `env.example` with your Penpot credentials:
  107. ```
  108. PENPOT_API_URL=https://design.penpot.app/api
  109. PENPOT_USERNAME=your_penpot_username
  110. PENPOT_PASSWORD=your_penpot_password
  111. PORT=5000
  112. DEBUG=true
  113. ```
  114. > **⚠️ 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:
  115. > 1. Open your web browser and navigate to [https://design.penpot.app](https://design.penpot.app)
  116. > 2. Log in to your Penpot account
  117. > 3. Complete any CloudFlare human verification challenges if prompted
  118. > 4. Once verified, the API requests should work normally for a period of time
  119. ## Usage
  120. ### Running the MCP Server
  121. ```bash
  122. # Using uvx (when published to PyPI)
  123. uvx penpot-mcp
  124. # Using uvx for local development
  125. uvx --from . penpot-mcp
  126. # Using uv in a project (recommended for local development)
  127. uv run penpot-mcp
  128. # Using the entry point (if installed)
  129. penpot-mcp
  130. # Or using the module directly
  131. python -m penpot_mcp.server.mcp_server
  132. ```
  133. ### Debugging the MCP Server
  134. To debug the MCP server, you can:
  135. 1. Enable debug mode in your `.env` file by setting `DEBUG=true`
  136. 2. Use the Penpot API CLI for testing API operations:
  137. ```bash
  138. # Test API connection with debug output
  139. python -m penpot_mcp.api.penpot_api --debug list-projects
  140. # Get details for a specific project
  141. python -m penpot_mcp.api.penpot_api --debug get-project --id YOUR_PROJECT_ID
  142. # List files in a project
  143. python -m penpot_mcp.api.penpot_api --debug list-files --project-id YOUR_PROJECT_ID
  144. # Get file details
  145. python -m penpot_mcp.api.penpot_api --debug get-file --file-id YOUR_FILE_ID
  146. ```
  147. ### Command-line Tools
  148. The package includes utility command-line tools:
  149. ```bash
  150. # Generate a tree visualization of a Penpot file
  151. penpot-tree path/to/penpot_file.json
  152. # Validate a Penpot file against the schema
  153. penpot-validate path/to/penpot_file.json
  154. ```
  155. ### MCP Monitoring & Testing
  156. #### MCP CLI Monitor
  157. ```bash
  158. # Start your MCP server in one terminal
  159. python -m penpot_mcp.server.mcp_server
  160. # In another terminal, use mcp-cli to monitor and interact with your server
  161. python -m mcp.cli monitor python -m penpot_mcp.server.mcp_server
  162. # Or connect to an already running server on a specific port
  163. python -m mcp.cli monitor --port 5000
  164. ```
  165. #### MCP Inspector
  166. ```bash
  167. # Start your MCP server in one terminal
  168. python -m penpot_mcp.server.mcp_server
  169. # In another terminal, run the MCP Inspector (requires Node.js)
  170. npx @modelcontextprotocol/inspector
  171. ```
  172. ### Using the Client
  173. ```bash
  174. # Run the example client
  175. penpot-client
  176. ```
  177. ## MCP Resources & Tools
  178. ### Resources
  179. - `server://info` - Server status and information
  180. - `penpot://schema` - Penpot API schema as JSON
  181. - `penpot://tree-schema` - Penpot object tree schema as JSON
  182. - `rendered-component://{component_id}` - Rendered component images
  183. - `penpot://cached-files` - List of cached Penpot files
  184. ### Tools
  185. - `list_projects` - List all Penpot projects
  186. - `get_project_files` - Get files for a specific project
  187. - `get_file` - Retrieve a Penpot file by its ID and cache it
  188. - `export_object` - Export a Penpot object as an image
  189. - `get_object_tree` - Get the object tree structure for a Penpot object
  190. - `search_object` - Search for objects within a Penpot file by name
  191. ## AI Integration
  192. 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.
  193. ### Claude Desktop Integration
  194. For detailed Claude Desktop setup instructions, see [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md).
  195. 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):
  196. ```json
  197. {
  198. "mcpServers": {
  199. "penpot": {
  200. "command": "uvx",
  201. "args": ["penpot-mcp"],
  202. "env": {
  203. "PENPOT_API_URL": "https://design.penpot.app/api",
  204. "PENPOT_USERNAME": "your_penpot_username",
  205. "PENPOT_PASSWORD": "your_penpot_password"
  206. }
  207. }
  208. }
  209. }
  210. ```
  211. ### Cursor IDE Integration
  212. Cursor IDE supports MCP servers through its AI integration features. To configure Penpot MCP with Cursor:
  213. 1. **Install the MCP server** (if not already installed):
  214. ```bash
  215. pip install penpot-mcp
  216. ```
  217. 2. **Configure Cursor settings** by adding the MCP server to your Cursor configuration. Open Cursor settings and add:
  218. ```json
  219. {
  220. "mcpServers": {
  221. "penpot": {
  222. "command": "uvx",
  223. "args": ["penpot-mcp"],
  224. "env": {
  225. "PENPOT_API_URL": "https://design.penpot.app/api",
  226. "PENPOT_USERNAME": "your_penpot_username",
  227. "PENPOT_PASSWORD": "your_penpot_password"
  228. }
  229. }
  230. }
  231. }
  232. ```
  233. 3. **Alternative: Use environment variables** by creating a `.env` file in your project root:
  234. ```bash
  235. PENPOT_API_URL=https://design.penpot.app/api
  236. PENPOT_USERNAME=your_penpot_username
  237. PENPOT_PASSWORD=your_penpot_password
  238. ```
  239. 4. **Start the MCP server** in your project:
  240. ```bash
  241. # In your project directory
  242. penpot-mcp
  243. ```
  244. 5. **Use in Cursor**: Once configured, you can interact with your Penpot designs directly in Cursor by asking questions like:
  245. - "Show me all projects in my Penpot account"
  246. - "Analyze the design components in project X"
  247. - "Export the main button component as an image"
  248. - "What design patterns are used in this file?"
  249. ### Key Integration Features
  250. Both Claude Desktop and Cursor integration provide:
  251. - **Direct access** to Penpot projects and files
  252. - **Visual component analysis** with AI-powered insights
  253. - **Design export capabilities** for assets and components
  254. - **Natural language queries** about your design files
  255. - **Real-time design feedback** and suggestions
  256. - **Design system documentation** generation
  257. ## Package Structure
  258. ```
  259. penpot_mcp/
  260. ├── api/ # Penpot API client
  261. ├── server/ # MCP server implementation
  262. │ ├── mcp_server.py # Main MCP server
  263. │ └── client.py # Client implementation
  264. ├── tools/ # Utility tools
  265. │ ├── cli/ # Command-line interfaces
  266. │ └── penpot_tree.py # Penpot object tree visualization
  267. ├── resources/ # Resource files and schemas
  268. └── utils/ # Helper utilities
  269. ```
  270. ## Development
  271. ### Testing
  272. The project uses pytest for testing:
  273. ```bash
  274. # Using uv (recommended)
  275. uv sync --extra dev
  276. uv run pytest
  277. # Run with coverage
  278. uv run pytest --cov=penpot_mcp tests/
  279. # Using traditional pip
  280. pip install -e ".[dev]"
  281. pytest
  282. pytest --cov=penpot_mcp tests/
  283. ```
  284. ### Linting
  285. ```bash
  286. # Using uv (recommended)
  287. uv sync --extra dev
  288. # Set up pre-commit hooks
  289. uv run pre-commit install
  290. # Run linting
  291. uv run python lint.py
  292. # Auto-fix linting issues
  293. uv run python lint.py --autofix
  294. # Using traditional pip
  295. pip install -r requirements-dev.txt
  296. pre-commit install
  297. ./lint.py
  298. ./lint.py --autofix
  299. ```
  300. ## Contributing
  301. Contributions are welcome! Please feel free to submit a Pull Request.
  302. 1. Fork the repository
  303. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  304. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  305. 4. Push to the branch (`git push origin feature/amazing-feature`)
  306. 5. Open a Pull Request
  307. Please make sure your code follows the project's coding standards and includes appropriate tests.
  308. ## License
  309. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  310. ## Acknowledgments
  311. - [Penpot](https://penpot.app/) - The open-source design and prototyping platform
  312. - [Model Context Protocol](https://modelcontextprotocol.io) - The standardized protocol for AI model context

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.