custom-figma-mcp

Лёгкий локальный MCP (Model Context Protocol) сервер, который предоставляет AI-агентам программирования (например, OpenCode) структурированный доступ только для чтения к файлам Figma — иерархии файлов, свойства узлов и отрисованные изображения — без необходимости в облачной/удалённой MCP-интеграции Figma.

Почему это существует

Официальный удалённый MCP-сервер Figma ограничен Client ID из списка разрешённых, что непрактично для отдельных разработчиков, настраивающих собственный агентский инструментарий. Этот проект обходит это, обращаясь напрямую к публичному REST API Figma с персональным токеном доступа, и предоставляет агенту стандартный интерфейс MCP-инструментов через stdio.

Related MCP server: ai-ready-ds-auditor

Архитектура

OpenCode (MCP client)
      │  stdio (JSON-RPC)
      ▼
custom-figma-mcp (this server)
      │  HTTPS + X-Figma-Token
      ▼
Figma REST API (api.figma.com/v1)

Сервер — это единый процес Node.js, который:

1. Запускается и регистрируется через stdio с помощью @modelcontextprotocol/sdk.

2. Предостявляет фиксированный набор инструментов MCP-клиенту (OpenCode) через ListToolsRequestSchema.

3. Выполняет вызовы инструментов через CallToolRequestSchema, проксируя их в REST API Figma с вашим персональным токеном доступа в заголовке.

4. Возвращает структурированный JSON (или URL-адреса изображений) вызывающему агенту.

Поскольку он всегда использует только GET-запросы с токеном, ограниченным чтением, он не может изменять, комментировать или удалять что-либо в Figma — по своей конструкции он строго только для чтения.

Предостявляемые инструменты

get_figma_file_structure

Возвращает иерархию страниц/фреймов файла с ограничением глубины, чтобы избежать выгрузки всего дерева узлов (которое в больших файлах может содержать десятки тысяч узлов).

Входные параметры:

{ "fileKey": "string", "depth": 2 }

Соотеветствует: GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

Получает полные свойства для конкретных идентификаторо в узлов — конфигурацию auto-layout, значения padding/gap, заливки, обводки, типоgraphику, огранicчения, свойства комponenтов и т. д. Это основний инструмент для точной генерации кода.

Входные параметры:

{ "fileKey": "string", "nodeIds": ["1:2", "104:15"] }

Соотеветствует: GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

Отрисовывает конкретный узел в виде PNG и возвращает временную подписанную ссылку, полезную для визуальной сверки сгенерированного кода с макетом.

Входные параметры:

{ "fileKey": "string", "nodeId": "104:15", "scale": 2 }

Соотеветствует: GET /v1/images/:fileKey?ids=104:15&scale=2

Почему три отдельных инструмента (вместо одного)

Файлы Figma могут быть огромными — один вызо GET /files/:key без ограничения глубины может вернуть мегабайты глубоко вложенного JSON, что мгновенно исчерпывает контекстное окно LLM. Разделение интерфейса на три целевых инструмента позволяет агенту:

1. Сначала получить лёгкий обзор (get_figma_file_structure), чтобы определить нужные фреймы/узлы.

2. Углубиться только в те узлы, которые ему нужны (get_figma_node_details).

3. При необходимости отрисовать изображение, только когда требуется визуальное подтверждение (get_figma_node_image).

Это повторяет подход живого разработчика при просмотре макета — сначала беглый осмотр, затем приближение — вместо загрузки всего файла сразу.

Аутентификация

Для аутентификации используется персональный токен доступа (PAT) Figma с областью file_content:read. Токен заглужается из локального файла .env (никогда не зашивается в код) и добавляется в каждый исходящий запрос в виде заголовка X-Figma-Token. Токен никогда не покидает локальную машину, за исключением запросов напрямую к api.figma.com.

Обработка ошибок

Все обрабочики инструментов обёрнуты в try/catch. При сбое (неверный ключ файла, отсуствие доступа, огранicчение частоты запросов и т. д.) сервер возвращает ответ об ошике, совместимый с MCP:

{
  "content": [{ "type": "text", "text": "Figma API Error: <details>" }],
  "isError": true
}

Это позволяет вызывающему агенту увидеть фактическую причину сбоя, а не молча падать.

Структура проекта

custom-figma-mcp/
├── index.js        # server entrypoint — tool definitions + handlers
├── package.json    # dependencies, "type": "module" for ESM imports
├── .env            # local only — holds FIGMA_PAT, never committed
└── .gitignore

Локальная разработка

Запустите сервер напрямую для отладки (он общается через stdio, поэому вы не увидите обычных логов HTTP-сервера):

node index.js

На практике вы не запускаете это вручную — OpenCode создаёт его как подпроцесс на основе command, определённого в opencode.json.

Расширение этого сервера

Чтобы добавить новый инструмент:

1. Добавьте его схему в массив tools, возвращаемый ListToolsRequestSchema.

2. Добавьте соотеветствующую ветвь if (name === "...") внутри обрабочика CallToolRequestSchema.

3. Сопоставьте его с соотеветствующим REST-эндпоинтом Figma в figmaApi (экземпляр axios, предварительно настроенный с базовым URL и заголовком аутентификации).

Делайте новые инструменты только для чтения и с огранicченной областью действия — по возмоности избегайте выгрузки полных нефильтрованных ответов API, чтобы снизить потребление контекста агентом.