penpot

Penpot MCP is an MCP server that enables AI models to interact with Penpot design projects via the Model Context Protocol. It exposes a RESTful API and CLI utilities to analyze design files, export assets, and validate design systems, allowing Claude or other LLMs to query project data, inspect components, and automate design workflows. Core capabilities include real-time access to Penpot designs, component analysis, and automated export/validation of assets. The package also offers a Python SDK for custom integrations, an HTTP API for web apps, and a plugin-friendly architecture for extending AI-driven workflows. When running locally, you can start the MCP server with a Python command and then use the provided CLI tools to test API endpoints, generate design trees, or validate Penpot files. For debugging and monitoring, the MCP CLI and inspector tooling can help you verify API responses and inspect server state while developing AI prompts and workflows.

Prerequisites:

• Python 3.12+ installed on your system
• Git for cloning the repository (if installing from source)
• Penpot account credentials for API access

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 note: The Penpot cloud site may employ CloudFlare protection that can block API requests. If you encounter authentication errors, complete any verifications in your browser to re-authenticate temporarily.

Tips and troubleshooting:

• Ensure your PENPOT_API_URL, PENPOT_USERNAME, and PENPOT_PASSWORD are correct and have API access.
• If you run into authentication issues, enable DEBUG in your .env to get verbose logs.
• When running locally, port conflicts can occur; adjust PORT in your .env if needed.
• The MCP Inspector requires Node.js for the CLI; ensure Node.js is installed if you plan to use npx for inspection.
• For production deployments, consider mounting a persistent .env and using a process supervisor to keep the MCP server running (e.g., systemd, PM2).
• If using uvx, keep the package version in sync with your local development to avoid incompatibilities.