Guddion Figma

Почему это вообще появилось

Я использую Claude Code как основной инструмент в работе с дизайном и фронтендом, и рано или поздно всегда упираюсь в официальный Figma Dev Mode MCP — он режет запросы лимитами, которые никак не настроить. Для разовой правки это терпимо, но когда нужно вытащить целую секцию с токенами, компонентами и layout за один присест, упираешься в стену ровно тогда, когда это важнее всего.

Решение оказалось простым: написать свой сервер, который говорит с Figma напрямую — по REST API через персональный токен и, отдельно, через плагин внутри самого Figma Desktop. Второй путь вообще не упирается ни в какой лимит, потому что читает документ прямо из памяти приложения, а не через HTTP.

Получилось два транспорта в одном MCP-сервере. Для разового запроса "дай мне вот этот фрейм" хватает REST. Для записи в файл, доступа к variables на Free-плане или частых тяжёлых запросов — подключаешь плагин.

Related MCP server: DSH Figma Bridge

Как это устроено

REST + Personal Access Token. Даёшь ссылку на фрейм — сервер достаёт из неё fileKey и nodeId, бьёт точечно по /files/:key/nodes?ids=, а не по всему файлу целиком. Это важно: Figma считает лимит по "стоимости" запроса в минуту, и дёрганье всего файла съедает его моментально, а точечные запросы по конкретной ноде почти не ощущаются даже на Free-плане.

Plugin Bridge. У плагина Figma нет сетевого доступа в главном потоке — это ограничение самой платформы, не моё решение. Сеть есть только в UI-iframe плагина. Поэтому мост состоит из трёх частей: локальный websocket-сервер ↔ невидимый UI плагина ↔ главный поток плагина, который и дёргает Plugin API. Через этот путь доступны вещи, которых нет в REST вообще — запись нод на холст и чтение Variables без Enterprise-плана.

MCP-клиент сам решает, какой инструмент вызвать: для чтения по ссылке обычно достаточно REST, а для записи или variables используются инструменты фазы 2.

Статус

Обе фазы написаны и проверены на реальном аккаунте и реальном открытом файле, не только на заглушках: REST-инструменты отдают настоящие ноды и стили, плагин создаёт настоящие объекты на холсте и возвращает реальные design tokens.

Установка

1. Сервер

npm install
cp .env.example .env

В .env нужен FIGMA_TOKEN — персональный токен из Figma: Settings → Security → Personal access tokens.

npm run build
npm start

Websocket для плагина по умолчанию поднимается на ws://localhost:9684. Если нужен другой порт — переменная FIGMA_BRIDGE_PORT в .env (и тогда же поправь порт в plugin/manifest.json, об этом ниже).

2. Подключение к MCP-клиенту

Сервер обычный stdio MCP, так что заводится в любом клиенте, который их поддерживает — не только в Claude.

Claude Code

claude mcp add guddion-figma -- node "<путь-к-проекту>/dist/server.js"

Cursor — добавить в .cursor/mcp.json (или в глобальный ~/.cursor/mcp.json):

{
  "mcpServers": {
    "guddion-figma": {
      "command": "node",
      "args": ["<путь-к-проекту>/dist/server.js"]
    }
  }
}

Codex CLI — добавить в ~/.codex/config.toml:

[mcp_servers.guddion-figma]
command = "node"
args = ["<путь-к-проекту>/dist/server.js"]

Во всех случаях <путь-к-проекту> — абсолютный путь до этого репозитория, а сервер должен быть собран (npm run build) до первого подключения. После добавления конфигурации клиент нужно перезапустить, чтобы он подхватил новый MCP-сервер.

Инструменты REST заработают сразу же. Инструменты плагина ответят ошибкой "plugin не подключён", пока не выполнен следующий шаг.

3. Плагин в Figma Desktop

Нужен только для записи и variables — для чтения по ссылке плагин не обязателен.

1. Figma Desktop → Plugins → Development → Import plugin from manifest…

2. Выбрать plugin/manifest.json из этого проекта.

3. Открыть нужный файл и запустить плагин Guddion Figma Bridge (Plugins → Development → Guddion Figma Bridge). У него нет видимого окна — он просто подключается к серверу на localhost:9684 и сидит там.

4. get_plugin_status должен вернуть connected: true и имя файла.

Порт в plugin/manifest.json зашит как конкретное число, потому что Figma не принимает wildcard по порту в манифесте (localhost:* считается невалидным URL). Поменял порт в .env — поправь то же число в манифесте и переимпортируй плагин.

Инструменты

REST — работает всегда, Figma Desktop не нужен

Plugin Bridge — нужен открытый файл и запущенный плагин

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

src/            — MCP-сервер, REST-клиент, резолвер ссылок, websocket-мост
plugin/         — код Figma-плагина (main thread + UI-iframe)

Лицензия

MIT — делай с этим что хочешь.