figma-mcp-bridge

O agente gera o design, audita visualmente a saída renderizada, detecta defeitos de layout e se autocorrige em tempo real — zero intervenção humana no processo.

O problema

Agentes de codificação são efetivamente cegos dentro do Figma. A maioria dos servidores MCP do Figma são somente leitura — eles achatam um design em texto para que um modelo possa transformá-lo em código, e o tráfego para por aí. Os que podem escrever estão ou atrás de uma licença Figma paga com cota mensal de chamadas de ferramentas, ou expõem um vocabulário fixo de comandos (create_rectangle, set_fill) que se esgota no momento em que a tarefa fica específica.

E nenhum deles responde à pergunta que realmente importa após uma escrita: ficou certo? Um agente que desenha um card, recebe de volta {"ok": true} e segue em frente não tem como perceber que seu texto transbordou, que o contraste falhou, ou que o frame caiu em cima do trabalho de outra pessoa.

Esta ponte fecha esse ciclo e adiciona as proteções de segurança que um agente autônomo precisa para ser confiável com um arquivo de design real.

Como é diferente

A versão curta: Framelink é a melhor escolha se você só quer transformar um design existente em código. O servidor oficial é a escolha mais segura se você já está em um plano Figma pago e quer Code Connect. Esta ponte é para o caso em que o agente está fazendo o design — onde ele precisa escrever livremente, verificar o próprio trabalho e ser desfeito quando errar.

Como funciona

flowchart LR
    subgraph AI ["🤖 Coding Agent"]
        LLM["Claude Code · Cursor<br/>Antigravity · Windsurf"]
    end

    subgraph Bridge ["⚡ MCP Server — Node.js, 0 deps"]
        Router["Tool Router<br/>+ Job Ledger<br/>+ Target Router"]
        Opt["Token Optimizer<br/>REST + LIVE"]
    end

    subgraph Figma ["🎨 Figma Desktop"]
        Plugin["Bridge Plugin<br/>Checkpoint Journal<br/>Component Index"]
        Canvas["Live Canvas"]
    end

    LLM -->|"stdio JSON-RPC"| Router
    Router <-->|"WebSocket :8765"| Plugin
    Plugin -->|"execute in sandbox"| Canvas
    Canvas -->|"export PNG"| Plugin
    Plugin -->|"raw node tree"| Opt
    Opt -.->|"86% smaller"| LLM
    Plugin ==>|"screenshot + warnings"| LLM

O agente fala MCP puro via stdio. O servidor possui um WebSocket RFC 6455 feito à mão na :8765, ao qual o plugin do Figma se conecta — então os comandos chegam ao canvas sem latência de polling, e os resultados (incluindo PNGs base64 de vários megabytes) voltam direto.

Início rápido

npx @kolganovr/figma-mcp-bridge

Ou, para ler o instalador antes que ele toque na sua máquina — é o mesmo script de qualquer forma, apenas buscado de forma diferente:

git clone https://github.com/kolganovr/figma-mcp-bridge.git
cd figma-mcp-bridge
node install.mjs

Ambos copiam o servidor e o plugin para o lugar certo e registram o servidor MCP em toda configuração de cliente de IA que encontrarem — Claude Desktop, Claude Code, Cursor, Windsurf, Antigravity. O pacote npm existe puramente para um primeiro comando mais curto; ele não adiciona uma única dependência de runtime — dependencies está vazio no package.json dele também, e nenhum Python é necessário. node é o único runtime que este projeto sempre precisa, tanto para o instalador quanto para o servidor.

Depois, no Figma Desktop:

1. Plugins → Development → Import plugin from manifest… → escolha figma-plugin/manifest.json
2. Pressione Ctrl + Alt + P (macOS: Cmd + Option + P) para iniciar o Antigravity Bridge
3. O status fica verde — CONNECTED

Reinicie seu cliente de IA para que ele carregue as novas ferramentas. Verifique a qualquer momento com:

npx @kolganovr/figma-mcp-bridge --doctor   # or: node install.mjs --doctor

npx @kolganovr/figma-mcp-bridge --token "your_figma_personal_access_token"
# or: node install.mjs --token "your_figma_personal_access_token"

O que isso dá ao agente

1. Escreva livremente e depois veja o resultado

capture: true retorna um PNG de exatamente o que a chamada acabou de criar ou modificar — com moldura automática para os nós alterados, nunca a página inteira, e nunca sequestrando a seleção do usuário.

// agent calls figma_execute_code
{ "code": "const f = figma.createFrame(); /* ... */ return f.id;", "capture": true }

// agent gets back — text + image in one response
{
  "ok": true,
  "created":  ["12:34"],
  "warnings": ["Text \"Total\" has ~3.1:1 contrast against its parent fill (WCAG AA wants 4.5:1)."],
  "checkpoint_id": "cp_mfk3p2a_7",
  "duration_ms": 840
}

O array warnings é uma auto-verificação barata sobre a subárvore tocada — transbordamento de texto, baixo contraste, nós de tamanho zero. Ele pega os erros óbvios sem gastar uma ida e volta de captura de tela.

2. Desfaça qualquer coisa que o agente fez

Cada escrita abre um checkpoint automaticamente. Uma chamada o reverte — sem Ctrl+Z rolando para trás sobre o trabalho não relacionado do próprio humano.

// agent calls figma_rollback
{ "checkpoint_id": "last" }

// gets back
{
  "ok": true,
  "checkpoint_id": "cp_mfk3p2a_7",
  "label": "Generate checkout flow",
  "removed":  ["12:34", "12:35"],   // nodes the call created — deleted
  "restored": ["9:11"],             // nodes it modified — properties put back
  "missing":  []                    // ids that no longer exist
}

Nós criados são rastreados automaticamente via um Proxy em torno de figma.create*(). Edições de propriedades são rastreadas quando há snapshot. Exclusões são honestamente relatadas como irrecuperáveis em vez de perdidas silenciosamente.

3. Leia o canvas ao vivo por ~700 tokens em vez de ~5.000

O mesmo pipeline de poda + Pseudo-JSX que alimenta as ferramentas de nuvem, apontado para o que está aberto agora. Medido em um layout realista de 6 cards: 20 KB de JSON bruto da API → 2,7 KB (86% menor).

<Frame id="1:1" name="Landing" w="1440" h="900" row gap="20">
  <Frame id="2:0" name="Card" w="300" h="200" col gap="12" pad="20" bg="#FFFFFF" radius="16">
    <Icon id="3:0" name="ic_check" size="24" strokeWidth="2" />
    <Text id="4:0" color="#1A1A1F" font="Inter 18px">Feature 0</Text>
  </Frame>
</Frame>

budget_tokens limita a resposta: se a profundidade solicitada ultrapassar, o servidor re-serializa a árvore já buscada de forma mais rasa — sem segunda ida e volta — e anexa um comentário dizendo o que fez e qual id buscar para mais.

4. Ensine novos truques ao sandbox que sobrevivem a reinícios

Toda chamada de figma_execute_code é um escopo de função novo, então helpers normalmente morrem instantaneamente. bridge.define compila e armazena um módulo dentro do documento .fig:

// once
bridge.define("kit", `
  async function label(parent, text) { /* ... */ }
  module.exports = { label };
`);

// in any later call — including next week, after a Figma restart
const { label } = bridge.require("kit");

5. Trabalhos longos que não morrem no timeout

Uma geração ainda em execução após 30s devolve um job_id em vez de falhar enquanto o plugin continua trabalhando. Consulte figma_job_status para progresso ao vivo — o sandbox o reporta via progress(step, of, note).

Referência de ferramentas

As ferramentas são servidas em camadas, para que a lista de esquemas enviada ao modelo a cada turno permaneça proporcional ao que é realmente utilizável:

Sem um token REST, um agente vê 13 ferramentas em vez de 23 — e nunca desperdiça uma chamada em algo que só retornaria REST_TOKEN_MISSING.

Notas de engenharia

As partes que foram mais difíceis do que parecem — e por que o código tem o formato que tem.

Testes

Cinco suítes sem dependências, todas executáveis com node puro:

node tests/bridge-runtime.test.js   # sandbox runtime, module persistence, checkpoint/rollback
node tests/layout-packer.test.js    # row/grid packing, collision grid
node tests/optimizer.test.js        # jsx/tree/json serialization, budget truncation
node tests/mcp-protocol.test.js     # real server over stdio: initialize, tools/list, tiering
node tests/install.test.js          # config merge/reuse, token persistence, stale-file cleanup

mcp-protocol.test.js inicia o servidor real como um processo filho e fala NDJSON com ele — o mesmo transporte que um cliente MCP real usa — em vez de importar internos.

Estrutura do repositório

figma-mcp-bridge/
├── figma/                    # MCP server (Node.js, stdio + WebSocket)
│   ├── index.js              # protocol, tool router, job ledger, target router
│   ├── optimizer/            # AST pruner, style collapser, JSX/tree serializers
│   ├── instructions.md       # agent-facing protocol docs (served on `initialize`)
│   └── *.json                # per-tool schemas
├── figma-plugin/             # Figma Desktop plugin
│   ├── code.js               # sandbox executor, bridge runtime, checkpoints, capture
│   └── ui.html               # HUD — stream, settings, control (pause / undo)
├── tests/                    # 5 suites, 0 dependencies
├── install.mjs               # cross-platform installer, updater, doctor (Node only)
└── AGENTS.md                 # onboarding protocol for AI agents

Fontes

1. Requisitos de assento e cota para o servidor oficial — Figma: Guia para o servidor MCP do Figma, Figma Developer Docs: Limites de taxa e acesso
2. Redução de tokens medida em um fixture de layout de 6 cartões que imita a saída REST real: 20.587 B brutos → 2.862 B Pseudo-JSX (86,1%) / 1.912 B árvore (90,7%). O fixture está versionado e verificado — execute node tests/optimizer.test.js para reproduzir os números exatos.

A comparação reflete o comportamento documentado publicamente em agosto de 2026. Alternativas estão em desenvolvimento ativo — verifique as capacidades atuais antes de tomar uma decisão com base apenas nesta tabela.

Licença

MIT · Criado por Roman Kolganov