DesignCorp Docs

Appearance

Figma MCP + Codex ​

Runbook подключения и использования Figma MCP в Codex.

Дата актуализации: 2026-03-24

Purpose ​

Зафиксировать единый рабочий процесс для:

  • логина в Figma remote MCP из codex;
  • чтения Figma-контекста из ссылок на файлы и узлы;
  • переноса live UI в Figma;
  • базовой работы с write-to-canvas flow;
  • быстрого восстановления после типовых ошибок авторизации.

Source of truth ​

  • Codex CLI локально: codex mcp list
  • Официальный remote server: https://mcp.figma.com/mcp

Если figma не отображается в codex mcp list, значит сервер не подключен в текущем Codex CLI независимо от того, что включено в UI-переключателях Apps.

Что это даёт ​

После подключения Figma MCP Codex может:

  • читать design context по ссылке на Figma frame/layer;
  • получать screenshot, metadata, variables и Code Connect mappings;
  • в поддерживаемых клиентах переносить live UI в Figma через generate_figma_design;
  • в поддерживаемых клиентах писать native Figma content через use_figma.

Prerequisites ​

  • установлен codex;
  • доступ к Figma-файлам под нужным аккаунтом;
  • для правки существующих Figma-файлов нужны соответствующие права в Figma;
  • для use_figma нужен Full seat;
  • для generate_figma_design в drafts достаточно базового доступа, но для правки существующего файла вне drafts нужен Full seat и edit permissions.

Первичное подключение ​

Добавить сервер:

bash
codex mcp add figma --url https://mcp.figma.com/mcp

После этого Codex запустит OAuth flow и выведет ссылку вида:

text
Authorize `figma` by opening this URL in your browser:
https://www.figma.com/oauth/mcp?...

Откройте ссылку в браузере и подтвердите доступ.

Повторный логин ​

Если сервер уже добавлен, но Auth неактивен:

bash
codex mcp login figma

Проверка статуса:

bash
codex mcp list

Ожидаемый результат:

text
Name   Url                        Status   Auth
figma  https://mcp.figma.com/mcp  enabled  OAuth

Важный нюанс для серверного Codex ​

Если codex запущен на сервере, а OAuth-ссылку вы открываете в браузере на своей локальной машине, Figma в конце редиректит на callback вида:

text
http://127.0.0.1:<port>/callback?code=...&state=...

Этот 127.0.0.1 относится к машине, где открыт браузер, а не к хосту, где слушает callback-сервер codex.

Следствие:

  • в браузере вы видите callback URL;
  • но серверный codex не получает callback автоматически.

В этом случае нужно выполнить callback на самом хосте с Codex:

bash
curl -i 'http://127.0.0.1:<port>/callback?code=...&state=...'

После этого codex mcp login figma или codex mcp add figma ... должен завершиться успешно.

Типовой рабочий сценарий ​

1. Прочитать существующий дизайн из Figma ​

Дайте Codex ссылку на frame/layer:

text
https://www.figma.com/design/<fileKey>/<name>?node-id=<id>

Основные инструменты:

  • get_design_context
  • get_screenshot
  • get_metadata
  • get_variable_defs
  • get_code_connect_map

Использовать, когда нужно:

  • понять структуру экрана;
  • снять визуальный референс;
  • получить UI-код как стартовую точку;
  • проверить токены и mapping на компоненты.

2. Перенести live UI сайта/HTML в Figma ​

Каноничный путь для HTML не в том, чтобы загружать сырой .html в Figma, а в том, чтобы открыть отрендеренный интерфейс и захватить его через generate_figma_design.

Типовой prompt:

text
Start a local server for my app and capture the UI in a new Figma file.

Или:

text
Start a local server for my app and capture the UI in <Figma file URL>.

Это подходит для:

  • локального сайта;
  • dev preview;
  • статического HTML, который можно отрендерить в браузере.

3. Писать native Figma content ​

Для write-to-canvas flow используйте Figma file URL или selection URL и просите Codex работать через use_figma.

Типовые задачи:

  • создать новую страницу;
  • собрать экран из existing components;
  • завести variables и заменить raw values;
  • достроить состояние экрана внутри текущего design system.

4. Реиспользовать design system ​

Для лучших результатов:

  • держите в Figma корректные variables и styles;
  • настраивайте Code Connect mappings;
  • используйте library search / component mappings вместо ручного дублирования.

Это особенно важно, если цель не просто screenshot fidelity, а переносимый editable design и code reuse.

Что проверять в первую очередь ​

Сервер подключен ​

bash
codex mcp list

Figma авторизована ​

В codex mcp list у figma должен быть Auth = OAuth.

Аккаунт и seat правильные ​

Если в клиенте доступен whoami, проверьте:

  • email;
  • plan;
  • seat;
  • доступ к нужному файлу.

Troubleshooting ​

Auth: Not logged in ​

Перелогинить:

bash
codex mcp login figma

invalid_grant ​

Обычно это означает, что OAuth code уже устарел или был использован некорректно.

Действия:

  1. Перезапустить codex mcp login figma.
  2. Открыть новую auth URL.
  3. Сразу передать свежий callback на хост с Codex.

В браузере открылся 127.0.0.1/callback, но логин не завершился ​

Это типичный remote-host сценарий.
Нужно выполнить callback URL на хосте, где работает codex, через curl.

Figma tools читают, но не пишут ​

Проверьте:

  • что подключён именно remote Figma MCP;
  • что у аккаунта есть нужный seat;
  • что клиент поддерживает use_figma и generate_figma_design;
  • что установлены Figma-related skills/plugins для данного клиента, если клиент этого требует.

Permission error на файл ​

Проверьте:

  • правильный аккаунт Figma;
  • принадлежность файла к доступному team/org;
  • право edit, если нужен write flow.

Минимальный smoke-check ​

bash
codex mcp list
codex mcp get figma

Далее в рабочей сессии:

  1. Дать Codex ссылку на Figma frame.
  2. Попросить снять screenshot или прочитать design context.
  3. Для write flow дать file URL и попросить создать маленький test frame или новый page.

Полезные официальные ссылки ​

  • Remote setup: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
  • Tools and prompts: https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
  • Write to canvas: https://developers.figma.com/docs/figma-mcp-server/write-to-canvas/
  • Code to canvas: https://developers.figma.com/docs/figma-mcp-server/code-to-canvas/
  • Plans / permissions: https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/

Internal note ​

Для DesignCorp этот runbook нужен как каноничная инструкция входа и работы с Figma MCP в Codex, чтобы не пересобирать flow заново по внешним docs при каждой новой машине, сессии или агенте.