Skip to main content
Glama
Figma Export MCP

Figma Export MCP

by jornobam

Figma Export MCP — пакет задания на разработку

Этот архив предназначен для передачи автономному Codex на Linux-сервере. Его задача — разработать production-ready MCP-сервер, который позволяет AI-агенту анализировать произвольно организованные Figma-файлы, согласовывать с пользователем правила отбора и именования, массово экспортировать изображения и загружать проверенный результат в один аккаунт Яндекс Диска.

Важное разграничение

  • Codex CLI используется только для разработки проекта.

  • Конечный продукт — MCP-сервер, а не пользовательская CLI-утилита.

  • Техническая команда запуска STDIO-процесса допустима и необходима для подключения MCP-клиента, но не считается пользовательским CLI.

  • MCP не должен содержать логику, привязанную к одному макету, бренду, сетке или примеру WABE.

Related MCP server: figmad-mcp

Как передать задание Codex

  1. Распакуйте архив в отдельный каталог на сервере.

  2. Перейдите в этот каталог.

  3. Убедитесь, что установлен и авторизован Codex CLI.

  4. Запустите:

    chmod +x scripts/start-development.sh
    ./scripts/start-development.sh

Скрипт передаст TASK.md в codex exec и разрешит изменения только внутри рабочей директории. Codex должен прочитать AGENTS.md и остальные документы до начала реализации.

Состав спецификации

  • TASK.md — исполняемое задание автономному разработчику.

  • AGENTS.md — постоянные правила разработки.

  • PRODUCT_SPEC.md — продуктовые требования и пользовательский сценарий.

  • ARCHITECTURE.md — рекомендуемая архитектура.

  • MCP_TOOLS.md — контракты инструментов MCP.

  • AGENT_WORKFLOW.md — обязательный диалоговый протокол.

  • EXPORT_PLAN_SCHEMA.md — модель универсального плана экспорта.

  • FIGMA_SELECTION_RULES.md — правила анализа дерева, строк и колонок.

  • YANDEX_DISK_WORKFLOW.md — доставка и проверка файлов.

  • SECURITY.md — работа с токенами, путями и внешними URL.

  • ACCEPTANCE_CRITERIA.md — критерии готовности.

  • TESTING_STRATEGY.md — необходимое покрытие тестами.

  • ROADMAP.md — рекомендуемый порядок реализации.

  • examples/ — сценарии, на которых проверяется универсальность.

Авторитетные источники

Перед реализацией разработчик должен повторно проверить актуальную документацию:

Не копируйте токены в репозиторий, issue, отчёты Codex или сообщения чата.

Реализация

В этом каталоге находится готовый универсальный STDIO MCP-сервер. Он работает на Node.js 20+, не изменяет Figma, сохраняет снимки/планы/состояние заданий атомарно и возобновляет частичные загрузки без повторной отправки проверенных файлов.

Установка и запуск

npm ci
npm run check
npm run build
FIGMA_TOKEN=... YANDEX_DISK_TOKEN=... npm start

На Windows используйте $env:FIGMA_TOKEN="..."; npm start, на PowerShell; на macOS/Linux — export FIGMA_TOKEN=.... Полный перечень переменных находится в .env.example. По умолчанию состояние хранится в %LOCALAPPDATA%/FigmaExportMCP/state, ~/Library/Application Support/figma-export-mcp или $XDG_STATE_HOME/figma-export-mcp.

По умолчанию FIGMA_AUTH_MODE=pat и FIGMA_TOKEN передаётся Figma через X-Figma-Token. Для уже полученного OAuth access token установите FIGMA_AUTH_MODE=oauth и FIGMA_OAUTH_ACCESS_TOKEN; запросы используют Authorization: Bearer. Регистрация OAuth app, браузерное согласие и обновление токена выполняются вне этого STDIO-сервера. План показывает изображения и все ZIP-архивы с точными путями; коллизии между ними блокируют подтверждение.

Подключение MCP-клиента

Готовый пример конфигурации Codex находится в examples/codex-mcp.json. Для Claude Desktop, Cursor и других клиентов используется тот же STDIO command: node /absolute/path/dist/stdio.js; секреты передаются только через env.

Проверки и troubleshooting

npm run check выполняет typecheck, lint, unit/integration tests, build и MCP smoke. npm run mcp:inspect проверяет MCP initialization, instructions, schemas и structured output без сети. Если Figma отвечает 429, клиент уважает Retry-After; 5xx повторяются с ограниченным backoff. Ошибка PLAN_NOT_CONFIRMED означает, что сначала нужно показать preview и подтвердить его digest. Ошибки сети Яндекс Диска безопасно возобновляются через retry_failed_items.

Для OAuth Figma достаточно file_content:read: check_connections не обращается к /v1/me, а доступ проверяется при inspect_figma_file. ZIP64 создаётся и загружается потоково, поэтому память процесса не растёт пропорционально суммарному размеру архива; дисковый предел задаётся FIGMA_EXPORT_MAX_TEMP_BYTES.

Для реальных read-only проверок предусмотрен opt-in скрипт LIVE_SMOKE_CONFIRM=YES npm run live:smoke; он не загружает и не удаляет данные.

Available Tools

12 tools
analyze_figma_layoutAnalyze Figma layoutC
Read-onlyIdempotent

Detects adaptive row/column geometry and reports heuristic evidence, confidence, anomalies and samples.

Inputs: snapshot_id (required), global, selector, tolerance, +2 more. Returns: ok, error, schema_version

check_connectionsCheck Figma, Yandex Disk and state-store connectionsA
Read-onlyIdempotent

Checks configuration and reachability without returning secrets.

Inputs: no named parameters. Returns: ok, error, schema_version

cleanup_jobClean local job workspaceA
DestructiveIdempotent

Deletes local temporary data only after verification, or after explicit risk confirmation for incomplete jobs.

Inputs: job_id (required), confirm_partial_cleanup. Returns: ok, error, schema_version

confirm_export_planConfirm a previewed export planA
Idempotent

Unlocks only the exact digest after explicit user approval; rejects unresolved clarifications and changed Figma versions.

Inputs: digest (required), plan_id (required), confirmation_summary (required). Returns: ok, error, schema_version

create_export_planCreate immutable draft export planC

Materializes selection, ordering, variables, names and paths. Never renders or uploads.

Inputs: destination (required), snapshot_id (required), export, naming, +9 more. Returns: ok, error, schema_version

execute_export_planExecute confirmed export planA
Idempotent

Starts an idempotent background export/upload/verify job and quickly returns its job ID.

Inputs: digest (required), plan_id (required), idempotency_key (required). Returns: ok, error, schema_version

get_export_statusGet export job statusB
Read-onlyIdempotent

Returns stage totals, safe errors, retry state, verified paths and paginated events.

Inputs: job_id (required), event_cursor, event_page_size. Returns: ok, error, schema_version

inspect_figma_fileInspect a Figma fileB
Read-onlyIdempotent

Creates or reuses a versioned normalized read-only snapshot and returns a compact summary.

Inputs: scope, node_id, refresh, file_key, +1 more. Returns: ok, error, schema_version

preview_export_planPreview exact export planA
Read-onlyIdempotent

Returns stable count/order/naming/destination/warnings plus a page of the manifest without bulk render.

Inputs: plan_id (required), cursor, page_size. Returns: ok, error, schema_version

query_nodesQuery normalized Figma nodesC
Read-onlyIdempotent

Applies declarative logical selectors without rendering and returns a paginated evidence set.

Inputs: snapshot_id (required), order, cursor, selector, +1 more. Returns: ok, error, schema_version

retry_failed_itemsRetry failed export itemsA
Idempotent

Retries only failed/retryable items and never reuploads verified items.

Inputs: job_id (required), idempotency_key (required). Returns: ok, error, schema_version

verify_yandex_uploadVerify Yandex Disk uploadA
Read-onlyIdempotent

Rechecks every expected path, size and comparable checksum without uploading.

Inputs: job_id (required). Returns: ok, error, schema_version

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, especially the phased export plan tools. The only mild ambiguity is among inspect_figma_file, analyze_figma_layout, and query_nodes, though their descriptions separate snapshotting, layout analysis, and node selection well enough.

    Naming Consistency5/5

    Tool names consistently follow a consistent verb_noun snake_case pattern (create, preview, confirm, execute, get, retry, verify, cleanup). Names read predictably and map directly to their actions. No naming convention clashes exist.

    Tool Count5/5

    Twelve tools is well-scoped for a focused export/export-verification workflow. Each tool occupies a meaningful stage from planning to cleanup without redundancy. The count feels intentional rather than padded.

    Completeness4/5

    The set covers the full lifecycle: connection checks, inspection, planning, preview, confirmation, execution, status, retry, verification, and cleanup. An explicit cancel/abort operation for running jobs is a minor gap, but agents can still manage the workflow through status, retry, and cleanup.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to interact with Figma to create, read, and manage designs using the Figma REST API and a dedicated plugin. It supports advanced features like UI generation from text, webpage reconstruction in Figma, and design token synchronization with codebases.
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to extract design systems, analyze components, and maintain design-code consistency from Figma files, providing intelligent component analysis and accessibility compliance.
      42 npm
      27
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Enables AI agents to read, inspect, and export Figma designs programmatically. Provides tools for listing components, styles, and exporting assets in various formats.
      5
      1
      -