Penpot MCP Server

Integra modelos de linguagem de IA com a plataforma de design Penpot para automatizar fluxos de trabalho de design.

GitHub
237
Experimente este MCPPatrocinado

Documentação

Penpot MCP Server 🎨🤖

Penpot MCP Logo

Automação de Fluxo de Trabalho de Design com IA
Conecte o Claude AI e outros LLMs aos designs do Penpot via Model Context Protocol

License: MIT Python Version PyPI version Build Status

🚀 O que é o Penpot MCP?

Penpot MCP é um servidor revolucionário de Model Context Protocol (MCP) que preenche a lacuna entre modelos de linguagem de IA e o Penpot, a plataforma open-source de design e prototipagem. Essa integração permite que assistentes de IA como o Claude (tanto no Claude Desktop quanto no Cursor IDE) entendam, analisem e interajam com seus arquivos de design programaticamente.

🎯 Principais Benefícios

  • 🤖 Análise de Design Nativa em IA: Deixe o Claude AI analisar seus designs de UI/UX, fornecer feedback e sugerir melhorias
  • ⚡ Fluxos de Trabalho de Design Automatizados: Otimize tarefas repetitivas de design com automação alimentada por IA
  • 🔍 Busca Inteligente de Design: Encontre componentes e padrões de design em seus projetos usando linguagem natural
  • 📊 Gerenciamento de Design System: Documente e mantenha design systems automaticamente com assistência de IA
  • 🎨 Integração Multiplataforma: Funciona com qualquer assistente de IA compatível com MCP (Claude Desktop, Cursor IDE, etc.)

🎥 Vídeo de Demonstração

Confira nosso vídeo de demonstração para ver o Penpot MCP em ação:

Penpot MCP Demo

✨ Recursos

🔌 Capacidades Principais

  • Implementação do Protocolo MCP: Conformidade total com os padrões do Model Context Protocol
  • Acesso a Design em Tempo Real: Integração direta com a API do Penpot para dados de design ao vivo
  • Análise de Componentes: Análise alimentada por IA de componentes e layouts de design
  • Automação de Exportação: Exportação programática de assets de design em múltiplos formatos
  • Validação de Design: Verificação automatizada de conformidade com o design system

🛠️ Ferramentas para Desenvolvedores

  • Utilitários de Linha de Comando: Ferramentas CLI poderosas para análise e validação de arquivos de design
  • SDK Python: Biblioteca Python abrangente para integrações personalizadas
  • API REST: Endpoints HTTP para integração com aplicações web
  • Arquitetura Extensível: Sistema de plugins para fluxos de trabalho de IA personalizados

🎨 Recursos de Integração com IA

  • Integração com Claude Desktop e Cursor: Suporte nativo para o assistente de IA Claude tanto no Claude Desktop quanto no Cursor IDE
  • Compartilhamento de Contexto de Design: Forneça contexto de design aos modelos de IA para respostas melhores
  • Reconhecimento Visual de Componentes: A IA pode "ver" e entender componentes de design
  • Consultas em Linguagem Natural: Faça perguntas sobre seus designs em linguagem natural
  • Integração com IDE: Integração perfeita com ambientes de desenvolvimento modernos

💡 Casos de Uso

Para Designers

  • Automação de Revisão de Design: Obtenha feedback instantâneo de IA sobre acessibilidade, usabilidade e princípios de design
  • Documentação de Componentes: Gere automaticamente documentação para design systems
  • Verificações de Consistência de Design: Garanta conformidade com as diretrizes da marca em todos os projetos
  • Organização de Assets: Marcação e categorização de componentes de design alimentadas por IA

Para Desenvolvedores

  • Fluxos de Trabalho de Design para Código: Preencha a lacuna entre design e desenvolvimento com assistência de IA
  • Integração de API: Acesso programático a dados de design para ferramentas e fluxos de trabalho personalizados
  • Testes Automatizados: Gere testes de regressão visual a partir de especificações de design
  • Sincronização de Design System: Mantenha design tokens e componentes de código sincronizados

Para Equipes de Produto

  • Análises de Design: Acompanhe a adoção do design system e o uso de componentes
  • Aprimoramento da Colaboração: Revisões de design e coleta de feedback alimentadas por IA
  • Otimização de Fluxos de Trabalho: Automatize operações e aprovações repetitivas de design
  • Integração entre Ferramentas: Conecte o Penpot a outras ferramentas do seu fluxo de trabalho de design

🚀 Início Rápido

Pré-requisitos

  • Python 3.12+ (Python mais recente recomendado para desempenho ideal)
  • Conta Penpot (Cadastre-se gratuitamente)
  • Claude Desktop ou Cursor IDE (Opcional, para integração com IA)

Instalação

Pré-requisitos

  • Python 3.12+
  • Credenciais da conta Penpot

Instalação

Opção 1: Instalar a partir do PyPI

pip install penpot-mcp

Opção 2: Usando uv (recomendado para desenvolvimento Python moderno)

# 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

Opção 3: Instalar a partir do código-fonte

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

Configuração

Crie um arquivo .env baseado em env.example com suas credenciais do 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 Proteção CloudFlare: O site cloud do Penpot (penpot.app) usa proteção CloudFlare que pode ocasionalmente bloquear solicitações de API. Se você encontrar erros de autenticação ou solicitações bloqueadas:

  1. Abra seu navegador e navegue até https://design.penpot.app
  2. Faça login na sua conta Penpot
  3. Complete quaisquer desafios de verificação humana do CloudFlare se solicitado
  4. Após a verificação, as solicitações de API devem funcionar normalmente por um período de tempo

Uso

Executando o 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

Depurando o Servidor MCP

Para depurar o servidor MCP, você pode:

  1. Ativar o modo de depuração no seu arquivo .env definindo DEBUG=true
  2. Usar a CLI da API Penpot para testar operações 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

Ferramentas de Linha de Comando

O pacote inclui ferramentas utilitárias de linha de comando:

# 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

Monitoramento e Testes do MCP

Monitor CLI do 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

Inspetor 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 o Cliente

# Run the example client
penpot-client

Recursos e Ferramentas do MCP

Recursos

  • server://info - Status e informações do servidor
  • penpot://schema - Esquema da API Penpot como JSON
  • penpot://tree-schema - Esquema da árvore de objetos do Penpot como JSON
  • rendered-component://{component_id} - Imagens de componentes renderizados
  • penpot://cached-files - Lista de arquivos Penpot em cache

Ferramentas

  • list_projects - Listar todos os projetos Penpot
  • get_project_files - Obter arquivos de um projeto específico
  • get_file - Recuperar um arquivo Penpot pelo ID e armazená-lo em cache
  • export_object - Exportar um objeto Penpot como imagem
  • get_object_tree - Obter a estrutura da árvore de objetos de um objeto Penpot
  • search_object - Buscar objetos dentro de um arquivo Penpot por nome

Integração com IA

O servidor Penpot MCP pode ser integrado a assistentes de IA usando o Model Context Protocol. Ele suporta tanto o Claude Desktop quanto o Cursor IDE para automação perfeita do fluxo de trabalho de design.

Integração com Claude Desktop

Para instruções detalhadas de configuração do Claude Desktop, consulte CLAUDE_INTEGRATION.md.

Adicione a seguinte configuração ao seu arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no 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"
      }
    }
  }
}

Integração com Cursor IDE

O Cursor IDE suporta servidores MCP por meio de seus recursos de integração com IA. Para configurar o Penpot MCP com o Cursor:

  1. Instale o servidor MCP (se ainda não estiver instalado):

    pip install penpot-mcp

  2. Configure as configurações do Cursor adicionando o servidor MCP à sua configuração do Cursor. Abra as configurações do Cursor e adicione:

    {
  "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: Use variáveis de ambiente criando um arquivo .env na raiz do seu projeto:

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

  4. Inicie o servidor MCP no seu projeto:

    # In your project directory
penpot-mcp

  5. Use no Cursor: Após a configuração, você pode interagir com seus designs Penpot diretamente no Cursor fazendo perguntas como:

    • "Mostre-me todos os projetos na minha conta Penpot"
    • "Analise os componentes de design no projeto X"
    • "Exporte o componente de botão principal como imagem"
    • "Quais padrões de design são usados neste arquivo?"

Principais Recursos de Integração

Tanto a integração com Claude Desktop quanto com Cursor fornecem:

  • Acesso direto a projetos e arquivos Penpot
  • Análise visual de componentes com insights alimentados por IA
  • Capacidades de exportação de design para assets e componentes
  • Consultas em linguagem natural sobre seus arquivos de design
  • Feedback de design em tempo real e sugestões
  • Geração de documentação do design system

Estrutura do Pacote

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

Desenvolvimento

Testes

O projeto usa pytest para testes:

# 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

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Certifique-se de que seu código segue os padrões de codificação do projeto e inclui testes apropriados.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

  • Penpot - A plataforma open-source de design e prototipagem
  • Model Context Protocol - O protocolo padronizado para contexto de modelos de IA