Figma Local MCP

Локальный MCP для чтения, редактирования и создания макетов с нуля через Figma Plugin API. Версия 0.6.2: переносимый пакет и скилл с профилем shadcn/ui, правилами проекта и сценарием style guide → компоненты → экраны.

MCP-клиент → stdio → Node.js MCP → WebSocket 127.0.0.1:3055
                                        ↓
                            плагин в Figma Desktop
                                        ↓
                          Plugin API открытого файла

Сервер и плагин не вызывают Figma REST API, официальный Figma MCP или Figma AI. Токен Figma не нужен. Поэтому эти команды не создают запросов, учитываемых в квотах REST API и официального MCP. Это вывод из архитектуры, а не обещание неограниченного доступа к любым возможностям Figma. Синхронизация самого редактора с Figma продолжает работать обычным образом; лимиты AI-клиента также сохраняются.

Основания: лимиты официального MCP, лимиты REST API, доступ к документу из плагина.

Передача и установка

Скачайте/передайте ZIP из dist/. Он содержит собранный сервер, Figma-плагин, скилл и исходники. Получателю нужны Node.js 22+ и Figma Desktop; устанавливать npm-зависимости не требуется.

Установка из GitHub

Клон исходников предназначен для разработчиков и пользователей без доступа к SkillStore. Нужны Node.js 22+, npm и Python 3:

git clone https://github.com/lostpunk/figma-local-mcp.git
cd figma-local-mcp
npm ci
npm run release
node scripts/setup.mjs --codex

После setup импортируйте generated/figma-plugin/manifest.json в Figma Desktop и запустите плагин. Локальные ключи подключения создаются только на компьютере пользователя и не хранятся в GitHub.

Из распакованной папки выполните:

node scripts/setup.mjs --codex

Затем импортируйте generated/figma-plugin/manifest.json в Figma Desktop и запустите плагин. Он подключается автоматически, без ввода кода, и восстанавливает связь после перезапуска MCP. Держите его окно открытым. Установщик создаёт отдельный локальный ключ для каждого получателя; передавайте только ZIP из dist/.

• INSTALL.md — пошаговая инструкция для получателя и других MCP-клиентов.

• CUSTOMIZE.md — правила проекта, UI-библиотеки и доработка скилла.

• CONTRIBUTING.md — пересборка и распространение ZIP.

• SKILL.md — инструкции для агента.

Сам скилл не запускает MCP: setup регистрирует сервер и устанавливает скилл отдельно. Без Codex CLI команда node scripts/setup.mjs создаст конфигурации с корректными путями для вашего компьютера.

Related MCP server: Custom Figma MCP

Создание с нуля: от style guide до экрана

Начните с открытого пустого файла Figma Design и подключённого плагина. Один вызов create_style_guide с аргументами {"name":"My Product"} создаёт:

• фрейм с редактируемыми образцами: на новой странице My Product — Style guide, если бюджет позволяет, либо на существующей странице;

• коллекцию переменных: 10 цветов, 8 отступов и 6 радиусов;

• 5 текстовых стилей на Inter: H1, H2, Body, Label и Caption;

• привязки цветовых образцов к COLOR-переменным, промежутков и радиусов к FLOAT-переменным, текстовых образцов к TextStyle.

Это стартовый набор. Агент может передать свои массивы colors, typography, spacing, radii под конкретный продукт; каждый переданный массив заменяет соответствующий набор по умолчанию. Создание использует один режим переменных и не требует дополнительных режимов темы.

Команда возвращает pageId, frameId, collectionId, modeId и ID каждого токена/стиля. Затем:

1. Прочитайте get_document.capabilities: число страниц, источник сведений о тарифе и доступный бюджет. create_page возвращает существующую страницу с таким именем либо создаёт новую в пределах бюджета.

2. create_scene создаёт до 100 узлов за вызов. Временные ref и parentRef позволяют описать вложенные фреймы, текст и компоненты без промежуточных запросов.

3. В props передавайте fillVariableId, strokeVariableId, textStyleId и variableBindings, используя ID из style guide.

4. create_instance размещает экземпляры созданного компонента на экранах.

5. set_variable меняет цвет или числовой токен; связанные свойства слоёв обновляются средствами Figma.

6. set_selection открывает нужную страницу и фокусирует узлы, export_node возвращает изображение для проверки.

Пример запроса к агенту:

Используй только figma_local. В открытом пустом файле создай style guide для сервиса управления проектами: синий основной цвет, светлая тема, Inter, шкала отступов 4/8/12/16/24/32/48. Затем создай страницу Components с компонентом кнопки и страницу Screens с экраном входа. Привяжи цвета, отступы и текст к переменным и стилям. Используй экземпляр кнопки на экране и покажи PNG результата.

Подробный пример аргументов — examples/from-scratch.md.

Повторное создание guide с тем же именем отклоняется, чтобы не размножать стили. Существующий набор можно прочитать через get_design_system и изменить его COLOR/FLOAT значения через set_variable. Эта версия не редактирует определения текстовых стилей, не создаёт наборы вариантов компонентов и не публикует библиотеки.

Образцы связаны с токенами, но их текстовые подписи с HEX/px отражают момент создания. После изменения токенов актуальные значения читайте через get_design_system; подписи при необходимости меняйте через update_node. Текущая страница после создания guide не переключается автоматически.

Создание ресурсов основано на Plugin API переменных и локальных текстовых стилях. Ограничения возможностей редактора, прав и тарифного плана сохраняются. Ни один новый инструмент не вызывает REST API или официальный MCP.

Инструменты

Для get_node и get_selection: depth от 0 до 6, maxNodes от 1 до 1000. По умолчанию 2 и 200. childrenTruncated показывает пропущенных потомков; selectionTruncated — пропущенные корни выделения. Текст длиннее 10 000 символов сокращается с charactersTruncated и полным characterCount. Значение figma.mixed возвращается как {"mixed":true}.

find_nodes возвращает nextOffset для следующего вызова с прежними фильтрами. complete: false означает, что нужно продолжить, даже если nodes пуст. maxVisited ограничивает новые просмотренные узлы после offset; сдвиг к offset тоже требует обхода. Изменения файла между страницами выдачи могут сдвигать результаты.

Свойства для создания и редактирования

• Геометрия: x, y, width, height, rotation, cornerRadius.

• Вид: name, visible, locked, opacity, fill, stroke, strokeWeight.

• Текст: characters, fontName: {family, style}, fontSize, textAlignHorizontal.

• Дополнительная типографика: textAutoResize, lineHeight: {unit: "PIXELS" | "PERCENT", value}.

• Стили и токены: textStyleId, fillVariableId, strokeVariableId, variableBindings.

• Auto layout: layoutMode, itemSpacing, paddingTop/Bottom/Left/Right, primaryAxisAlignItems, counterAxisAlignItems, primaryAxisSizingMode, counterAxisSizingMode, clipsContent.

fill и stroke принимают #RRGGBB или null для очистки. Они заменяют весь список заливок/обводок на один сплошной цвет. Свойства текста применяются ко всему текстовому узлу. Перед текстовыми изменениями загружаются шрифты. Свойства, недоступные для данного типа узла, приводят к ошибке. Ограничения экземпляров компонентов проверяет Figma.

textStyleId нельзя совмещать в одном вызове с fontName, fontSize или lineHeight; fillVariableId — с fill; strokeVariableId — со stroke. Выберите стиль/токен или явное значение. variableBindings — объект из полей width, height, itemSpacing, paddingTop/Bottom/Left/Right, topLeftRadius, topRightRadius, bottomLeftRadius, bottomRightRadius; значения — ID FLOAT-переменных либо null для снятия привязки. Привязки применяются после обычных свойств.

Пример аргументов create_node:

{
  "type": "FRAME",
  "props": {
    "name": "Card",
    "width": 320,
    "height": 180,
    "fill": "#FFFFFF",
    "cornerRadius": 16,
    "layoutMode": "VERTICAL",
    "itemSpacing": 12,
    "paddingTop": 24,
    "paddingLeft": 24
  }
}

Вернувшийся id можно передать как parentId при создании дочернего текста. parentId поддерживает PAGE, FRAME, COMPONENT и SECTION.

Ограничения

• Один процесс MCP и один подключённый файл одновременно. Параллельные MCP-клиенты на порту 3055 конфликтуют. Для отдельного экземпляра нужно согласованно изменить FIGMA_BRIDGE_PORT, WebSocket URL в plugin/ui.html и devAllowedDomains в manifest.

• Плагин работает в Figma Design. Он не открывает произвольные файлы по ссылке, не работает в фоне с закрытым редактором и не обходит права доступа или политику организации по плагинам.

• Нет Figma AI, Make, Code Connect, комментариев, REST-поиска файлов, публикации библиотек, градиентных заливок или произвольного исполнения JavaScript. Создание нового файла Figma по-прежнему выполняется пользователем; инструменты создают страницы внутри открытого файла.

• Image fill принимает PNG, JPEG, GIF и WebP. Локальный путь должен быть абсолютным, указывать на обычный файл до 8 MiB и проходить проверку сигнатуры; байты не уходят в сторонние сервисы. При необходимости WebP и нестандартные JPEG/PNG декодируются UI плагина и сохраняются в файле как PNG.

• Для style guide создаются только локальные COLOR/FLOAT переменные и TextStyle, без алиасов и дополнительных режимов. Ограничения режима или типа переменной в set_variable проверяются до записи.

• Изменения не являются транзакциями. При ошибке update_node часть свойств могла измениться; ошибка сообщает об этом. После успешных изменений вызывается commitUndo; отмена выполняется в Figma. Неудачно созданный узел удаляется.

• При ошибке create_style_guide или create_scene выполняется очистка только ресурсов текущего вызова. Если очистка не удалась, ошибка перечисляет оставшиеся ресурсы. Таймаут транспорта не отменяет уже запущенную сборку: перед повтором проверьте файл.

• Таймаут команды — 30 секунд. После таймаута или разрыва связи результат отправленного изменения может быть неизвестен. Проверьте файл, прежде чем повторять команду: остановка соединения не отменяет уже запущенный Plugin API вызов.

• PNG ограничен до 4096 пикселей по большей стороне и 8 MiB; масштаб при необходимости уменьшается и возвращается в метаданных. SVG ограничен по длине 4 Mi символов.

Локальное соединение и данные

Bridge слушает только 127.0.0.1. Установщик сохраняет случайный локальный ключ длиной 32 байта в generated/pairing-key.json и в персональной копии UI. На macOS/Linux эти файлы доступны только владельцу (0600). Сервер проверяет ключ при каждом соединении. Без setup остаётся ручное сопряжение со случайным кодом на каждый запуск. Плагин не делает запросов к внешним доменам: в manifest разрешён только development WebSocket. Команды идут по списку известных операций, без eval, команд оболочки или передачи cookies Figma.

Содержимое макетов, прочитанное инструментами, возвращается MCP-клиенту и может попасть в контекст его AI-провайдера. Локальный bridge не означает локальную обработку моделью. Ключ подключения даёт доступ к сессии открытого файла. Каталог generated/ содержит персональный ключ и не включается в ZIP; не передавайте этот каталог другим людям.

Проверки

npm test

Проверены TypeScript-сборка и 42 автоматических теста: операции с узлами, style guide, переменные, импорт локальной картинки, порядок слоёв, ошибки, таймауты и защита подключения; запуск bundle без node_modules; генерация переносимых путей; установка/резервное копирование скилла; регистрация MCP с имитацией Codex CLI. Интеграционные тесты запускают настоящий MCP-клиент через stdio, настоящий WebSocket и собранный код плагина с имитацией Figma API; проходят путь от style guide до экземпляра компонента и изменения токена. Настройки реального Codex в тестах не изменяются.

Чтение, создание макета, компонентов, экземпляров и PNG-экспорт проверены в настоящем Figma Desktop. Автоподключение отдельно проверяется тестами UI и локального транспорта; эти тесты не заменяют проверку новой установки в редакторе.

Основные файлы: src/server.mjs — инструменты, src/design-schema.mjs — схемы guide/scene, src/bridge.mjs — локальное соединение, plugin/code.ts — узлы и свойства, plugin/design-system.ts — style guide, токены и сборка сцен, plugin/ui.html — подключение. После изменения TypeScript выполните npm run build и перезапустите плагин. Для появления новых инструментов перезапустите MCP-клиент. После setup плагин восстанавливает подключение автоматически; сборка обновляет его персональную копию в generated/figma-plugin/.

Тариф файла и ограничения страниц

Публичный Plugin API не сообщает тариф команды. Поэтому get_document.capabilities честно возвращает неизвестный тариф, подтверждённый пользователем тариф или ограничение, ранее полученное в ошибке Figma. figma.payments относится к оплате плагина и здесь не используется.

В окне Figma Local MCP Auto можно выбрать тариф команды текущего файла; настройка хранится отдельно в документе. При неизвестном тарифе действует предел безопасности в три страницы. При Starter — три страницы. Для подтверждённого Professional/Education/Organization/Enterprise искусственный предел снимается, но ограничения самого редактора остаются.

При исчерпанном бюджете create_page останавливается до вызова Figma API, а create_style_guide размещает фрейм справа от существующего контента. Можно явно указать pageId. Никаких пробных страниц для определения тарифа не создаётся. Повторный create_page с тем же именем возвращает существующую страницу.

См. правила скилла для лимитов и лимиты страниц Figma.

Установка одним скиллом

Передайте dist/figma-local-design-skill-0.6.2.zip. Получателю достаточно установить папку figma-local-design как скилл и написать агенту:

Используй $figma-local-design и установи всё необходимое для работы с Figma.

Скилл содержит установщик и проверяемый SHA256 пакет MCP. Агент развернёт его локально, зарегистрирует MCP и откроет manifest автоматического плагина. Нужны Node.js 22+ и Codex CLI для автоматической регистрации; npm и Python получателю не нужны. В Figma останется один раз импортировать manifest через меню Plugins → Development и запустить Figma Local MCP Auto.

По умолчанию отдельное скачивание не нужно: пакет вложен в скилл. Для размещённого вами релиза поддерживается HTTPS-загрузка runtime-payload.json.gz с обязательным SHA256. Публичный адрес релиза не настроен.