## Что это Penpot MCP Server — официальный MCP-сервер от команды Penpot, позволяющий AI-агентам (Claude Code, Claude Desktop и др.) создавать и изменять элементы дизайна в Penpot через промпты. - Репозиторий: https://github.com/penpot/penpot/tree/develop/mcp - Официальная страница: https://penpot.app/penpot-mcp-server - Дата выхода: декабрь 2025 ## Требования - Node.js v22+ (`node -v` для проверки, должен включать `corepack` и `npx`) - Penpot — облачный (penpot.app) или self-hosted (Docker) - Claude Code или Claude Desktop - Git Bash (рекомендуется для Windows) ## Установка ### Шаг 1 — Скачать и собрать > Репозиторий переехал из отдельного `penpot/penpot-mcp` в основной `penpot/penpot` (папка `/mcp`). ```bash git clone https://github.com/penpot/penpot.git --branch mcp-prod --depth 1 cd penpot/mcp ``` Первоначальная настройка: ```bash ./scripts/setup ``` Сборка и запуск всех компонентов: ```bash pnpm run bootstrap ``` > После запуска **не закрывать терминал** — MCP Server работает как процесс. Закрыл терминал — сервер остановился — Claude теряет связь с Penpot. Запустятся три сервиса: | Сервис | Порт | Назначение | |---|---|---| | Plugin Server | localhost:4400 | Отдаёт плагин в Penpot | | MCP Server | localhost:4401 | Сюда подключается Claude | | WebSocket | localhost:4402 | Связь с плагином в Penpot | ### Шаг 2 — Подключить плагин в Penpot > **Важно о выборе браузера:** Chromium 142+ ввёл ограничения Private Network Access (PNA), которые могут блокировать localhost-соединения. Браузер покажет всплывающее окно с запросом разрешения — нужно одобрить. В **Brave** нужно отключить Shield для сайта Penpot. **Firefox** не имеет ограничений PNA и работает без проблем — рекомендуется как запасной вариант при проблемах с Chromium. 1. Открыть файл дизайна в Penpot (в браузере) 2. Меню **Plugins** 3. Вставить URL: `http://localhost:4400/manifest.json` 4. Открыть плагин, нажать **"Connect to MCP server"** 5. Статус должен стать **"Connected to MCP server"** > Не закрывать окно плагина пока идёт работа через MCP. Закрытие окна разрывает соединение. ### Шаг 3 — Подключить к Claude Code MCP Server предоставляет два эндпоинта: - **HTTP/Streaming** (основной): `http://localhost:4401/mcp` - **Legacy SSE**: `http://localhost:4401/sse` Глобально (для всех проектов): ```bash claude mcp add penpot -t http http://localhost:4401/mcp -s user ``` Только для текущего проекта: ```bash claude mcp add penpot -t http http://localhost:4401/mcp -s project ``` ### Подключение к Claude Desktop Установить прокси для совместимости с stdio-транспортом: ```bash npm install -g mcp-remote ``` Добавить в `claude_desktop_config.json`: ```json { "mcpServers": { "penpot": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"] } } } ``` После изменения конфига полностью перезапустить Claude Desktop (File → Quit, а не просто закрыть окно). ## Использование ### Запуск Перед работой нужно запустить MCP Server (если не запущен): ```bash cd penpot/mcp pnpm run bootstrap ``` ### Пример промптов для Claude ``` "Создай фрейм Inventory 1920x1080 с тёмным фоном #1a1a2e" "Добавь сетку 9x4 из квадратов 34x34 с серой рамкой — это слоты инвентаря" "В правом нижнем углу добавь кнопку 200x48, оранжевый фон #FF5500, текст Купить белым" ``` ### Что может делать AI через MCP - Создавать фреймы, прямоугольники, текст, эллипсы, пути - Задавать размеры, позиции, цвета, заливки, обводки - Перемещать и удалять элементы - Читать структуру дизайна - Работать с библиотеками компонентов, цветов и типографики - Генерировать CSS и HTML/SVG из элементов дизайна - Экспортировать и импортировать изображения ## Конфигурация ### Переменные окружения сервера | Переменная | Назначение | По умолчанию | |---|---|---| | `PENPOT_MCP_SERVER_LISTEN_ADDRESS` | Адрес привязки | localhost | | `PENPOT_MCP_SERVER_PORT` | HTTP/SSE порт | 4401 | | `PENPOT_MCP_WEBSOCKET_PORT` | Порт соединения с плагином | 4402 | | `PENPOT_MCP_REPL_PORT` | Порт для отладки | 4403 | | `PENPOT_MCP_SERVER_ADDRESS` | Имя хоста, доступное клиенту | localhost | | `PENPOT_MCP_REMOTE_MODE` | Отключить доступ к файловой системе | false | ### Переменные логирования | Переменная | Назначение | По умолчанию | |---|---|---| | `PENPOT_MCP_LOG_LEVEL` | trace/debug/info/warn/error | info | | `PENPOT_MCP_LOG_DIR` | Директория лог-файлов | logs | ## Удалённый деплой Для запуска не на локальной машине: - Установить `PENPOT_MCP_REMOTE_MODE=true` — отключает доступ к локальной файловой системе - Настроить адреса через `PENPOT_MCP_SERVER_LISTEN_ADDRESS` и `PENPOT_MCP_PLUGIN_SERVER_LISTEN_ADDRESS` (использовать `0.0.0.0` осторожно в ненадёжных сетях) - Установить `PENPOT_MCP_SERVER_ADDRESS` на публично доступное имя хоста для WebSocket-соединений ## Управление процессом ### Проверить, запущен ли MCP Server ```bash lsof -i :4401 ``` Пустой ответ — не запущен. Если показывает процесс — работает. ### Найти все процессы Penpot MCP ```bash ps aux | grep penpot ``` ### Остановить все процессы ```bash pkill -f penpot ``` ## Архитектура ``` Claude Code / Claude Desktop (чат) | промпт v Claude (AI) -> вызов MCP-функций | v MCP Server (localhost:4401) -> HTTP/SSE | v WebSocket (localhost:4402) | v Penpot Plugin (в браузере) -> выполняет задачи через Plugin API | v Penpot (редактор) -> элементы появляются на холсте ``` ## Известные проблемы - **Нестабильное WebSocket-соединение** — плагин может отвалиться, нужно переподключить - **Chromium 142+** — новые ограничения Private Network Access (PNA). Браузер показывает всплывающее окно с запросом разрешения — нужно одобрить для работы localhost-соединений - **Brave** — может блокировать localhost-соединения, нужно отключить Shield для сайта Penpot - **Firefox** — не имеет ограничений PNA, можно использовать как запасной вариант при проблемах с Chromium ### Вечная загрузка (AI-агент не получает ответа) Частая проблема: Claude отправляет запрос через MCP и бесконечно ждёт ответа. Спиннер крутится, ничего не происходит. В таком случае простого переподключения плагина недостаточно — нужно перезапустить **всю цепочку**: 1. **Остановить MCP Server** — в терминале нажать `Ctrl+C` (или `pkill -f penpot`) 2. **Заново запустить MCP Server** — `cd penpot/mcp && pnpm run bootstrap` 3. **Переподключить плагин в Penpot** — в окне плагина нажать **"Connect to MCP server"** заново 4. **Создать новый чат Claude Code** — выйти из текущей сессии (`/exit` или `Ctrl+C`) и запустить `claude` заново > Claude Code не видит перезапуска MCP Server в рамках текущей сессии. Старая сессия продолжит висеть. Только новый чат подхватит переподключённый MCP. ## Ссылки - [GitHub: penpot/penpot/mcp](https://github.com/penpot/penpot/tree/develop/mcp) - [Официальная страница](https://penpot.app/penpot-mcp-server) - [Smashing Magazine: Penpot MCP](https://www.smashingmagazine.com/2026/01/penpot-experimenting-mcp-servers-ai-powered-design-workflows/) - [Penpot AI Whitepaper](https://penpot.app/blog/penpot-ai-whitepaper/)