Penpot MCP Server

Integra modelos de lenguaje de IA con la plataforma de diseño Penpot para automatizar flujos de trabajo de diseño.

GitHub
241
Prueba este MCPPatrocinado

Documentación

Penpot MCP Server 🎨🤖

Penpot MCP Logo

Automatización de flujos de trabajo de diseño con IA
Conecta Claude AI y otros LLMs a diseños de Penpot mediante el Model Context Protocol

License: MIT Python Version PyPI version Build Status

🚀 ¿Qué es Penpot MCP?

Penpot MCP es un servidor revolucionario de Model Context Protocol (MCP) que salva la brecha entre los modelos de lenguaje de IA y Penpot, la plataforma de diseño y prototipado de código abierto. Esta integración permite que asistentes de IA como Claude (tanto en Claude Desktop como en el IDE Cursor) comprendan, analicen e interactúen con tus archivos de diseño de forma programática.

🎯 Beneficios clave

  • 🤖 Análisis de diseño nativo con IA: Permite que Claude AI analice tus diseños de UI/UX, proporcione comentarios y sugiera mejoras
  • ⚡ Flujos de trabajo de diseño automatizados: Optimiza tareas de diseño repetitivas con automatización impulsada por IA
  • 🔍 Búsqueda inteligente de diseño: Encuentra componentes y patrones de diseño en tus proyectos usando lenguaje natural
  • 📊 Gestión de sistemas de diseño: Documenta y mantiene automáticamente sistemas de diseño con asistencia de IA
  • 🎨 Integración multiplataforma: Funciona con cualquier asistente de IA compatible con MCP (Claude Desktop, Cursor IDE, etc.)

🎥 Video de demostración

Mira nuestro video de demostración para ver Penpot MCP en acción:

Penpot MCP Demo

✨ Características

🔌 Capacidades principales

  • Implementación del protocolo MCP: Cumplimiento total con los estándares del Model Context Protocol
  • Acceso a diseño en tiempo real: Integración directa con la API de Penpot para datos de diseño en vivo
  • Análisis de componentes: Análisis impulsado por IA de componentes y diseños de diseño
  • Automatización de exportación: Exportación programática de recursos de diseño en múltiples formatos
  • Validación de diseño: Verificación automatizada del cumplimiento del sistema de diseño

🛠️ Herramientas para desarrolladores

  • Utilidades de línea de comandos: Potentes herramientas CLI para análisis y validación de archivos de diseño
  • SDK de Python: Biblioteca integral de Python para integraciones personalizadas
  • API REST: Endpoints HTTP para integración de aplicaciones web
  • Arquitectura extensible: Sistema de complementos para flujos de trabajo de IA personalizados

🎨 Características de integración con IA

  • Integración con Claude Desktop y Cursor: Soporte nativo para el asistente de IA Claude tanto en Claude Desktop como en el IDE Cursor
  • Compartición de contexto de diseño: Proporciona contexto de diseño a los modelos de IA para mejores respuestas
  • Reconocimiento visual de componentes: La IA puede "ver" y comprender componentes de diseño
  • Consultas en lenguaje natural: Haz preguntas sobre tus diseños en lenguaje natural
  • Integración con IDE: Integración perfecta con entornos de desarrollo modernos

💡 Casos de uso

Para diseñadores

  • Automatización de revisión de diseño: Obtén comentarios instantáneos de IA sobre accesibilidad, usabilidad y principios de diseño
  • Documentación de componentes: Genera automáticamente documentación para sistemas de diseño
  • Verificaciones de consistencia de diseño: Asegura el cumplimiento de las pautas de marca en todos los proyectos
  • Organización de recursos: Etiquetado y categorización de componentes de diseño impulsado por IA

Para desarrolladores

  • Flujos de trabajo de diseño a código: Salva la brecha entre diseño y desarrollo con asistencia de IA
  • Integración de API: Acceso programático a datos de diseño para herramientas y flujos de trabajo personalizados
  • Pruebas automatizadas: Genera pruebas de regresión visual a partir de especificaciones de diseño
  • Sincronización del sistema de diseño: Mantén los tokens de diseño y los componentes de código sincronizados

Para equipos de producto

  • Analítica de diseño: Realiza un seguimiento de la adopción del sistema de diseño y el uso de componentes
  • Mejora de la colaboración: Revisiones de diseño y recopilación de comentarios impulsadas por IA
  • Optimización de flujos de trabajo: Automatiza operaciones de diseño repetitivas y aprobaciones
  • Integración entre herramientas: Conecta Penpot con otras herramientas en tu flujo de trabajo de diseño

🚀 Inicio rápido

Requisitos previos

  • Python 3.12+ (Se recomienda la última versión de Python para un rendimiento óptimo)
  • Cuenta de Penpot (Regístrate gratis)
  • Claude Desktop o Cursor IDE (Opcional, para integración con IA)

Instalación

Requisitos previos

  • Python 3.12+
  • Credenciales de cuenta de Penpot

Instalación

Opción 1: Instalar desde PyPI

pip install penpot-mcp

Opción 2: Usando uv (recomendado para desarrollo moderno de Python)

# 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

Opción 3: Instalar desde el código fuente

# 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 .

Configuración

Crea un archivo .env basado en env.example con tus credenciales de Penpot:

PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=true

⚠️ Aviso de protección CloudFlare: El sitio en la nube de Penpot (penpot.app) utiliza protección CloudFlare que ocasionalmente puede bloquear solicitudes de API. Si encuentras errores de autenticación o solicitudes bloqueadas:

  1. Abre tu navegador web y navega a https://design.penpot.app
  2. Inicia sesión en tu cuenta de Penpot
  3. Completa cualquier desafío de verificación humana de CloudFlare si se te solicita
  4. Una vez verificado, las solicitudes de API deberían funcionar normalmente durante un período de tiempo

Uso

Ejecutando el servidor MCP

# 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

Depuración del servidor MCP

Para depurar el servidor MCP, puedes:

  1. Habilitar el modo de depuración en tu archivo .env estableciendo DEBUG=true
  2. Usar la CLI de la API de Penpot para probar operaciones de API:
# 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

Herramientas de línea de comandos

El paquete incluye herramientas de utilidad de línea de comandos:

# 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

Monitoreo y pruebas de MCP

Monitor CLI de MCP

# 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

Inspector de MCP

# 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

Usando el cliente

# Run the example client
penpot-client

Recursos y herramientas de MCP

Recursos

  • server://info - Estado e información del servidor
  • penpot://schema - Esquema de la API de Penpot como JSON
  • penpot://tree-schema - Esquema del árbol de objetos de Penpot como JSON
  • rendered-component://{component_id} - Imágenes de componentes renderizados
  • penpot://cached-files - Lista de archivos de Penpot en caché

Herramientas

  • list_projects - Lista todos los proyectos de Penpot
  • get_project_files - Obtiene archivos para un proyecto específico
  • get_file - Recupera un archivo de Penpot por su ID y lo guarda en caché
  • export_object - Exporta un objeto de Penpot como imagen
  • get_object_tree - Obtiene la estructura del árbol de objetos para un objeto de Penpot
  • search_object - Busca objetos dentro de un archivo de Penpot por nombre

Integración con IA

El servidor Penpot MCP se puede integrar con asistentes de IA usando el Model Context Protocol. Admite tanto Claude Desktop como el IDE Cursor para una automatización perfecta del flujo de trabajo de diseño.

Integración con Claude Desktop

Para instrucciones detalladas de configuración de Claude Desktop, consulta CLAUDE_INTEGRATION.md.

Agrega la siguiente configuración a tu archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "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"
      }
    }
  }
}

Integración con Cursor IDE

Cursor IDE admite servidores MCP a través de sus funciones de integración de IA. Para configurar Penpot MCP con Cursor:

  1. Instala el servidor MCP (si aún no está instalado):

    pip install penpot-mcp

  2. Configura los ajustes de Cursor agregando el servidor MCP a tu configuración de Cursor. Abre los ajustes de Cursor y agrega:

    {
  "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. Alternativa: Usa variables de entorno creando un archivo .env en la raíz de tu proyecto:

    PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password

  4. Inicia el servidor MCP en tu proyecto:

    # In your project directory
penpot-mcp

  5. Úsalo en Cursor: Una vez configurado, puedes interactuar con tus diseños de Penpot directamente en Cursor haciendo preguntas como:

    • "Muéstrame todos los proyectos en mi cuenta de Penpot"
    • "Analiza los componentes de diseño en el proyecto X"
    • "Exporta el componente del botón principal como imagen"
    • "¿Qué patrones de diseño se usan en este archivo?"

Características clave de integración

Tanto la integración con Claude Desktop como con Cursor proporcionan:

  • Acceso directo a proyectos y archivos de Penpot
  • Análisis visual de componentes con información impulsada por IA
  • Capacidades de exportación de diseño para recursos y componentes
  • Consultas en lenguaje natural sobre tus archivos de diseño
  • Comentarios y sugerencias de diseño en tiempo real
  • Generación de documentación del sistema de diseño

Estructura del paquete

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

Desarrollo

Pruebas

El proyecto usa pytest para pruebas:

# 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

# 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

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
  4. Haz push a la rama (git push origin feature/amazing-feature)
  5. Abre un Pull Request

Asegúrate de que tu código siga los estándares de codificación del proyecto e incluya pruebas apropiadas.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

  • Penpot - La plataforma de diseño y prototipado de código abierto
  • Model Context Protocol - El protocolo estandarizado para el contexto de modelos de IA