figma-mcp-bridge

El agente genera el diseño, audita visualmente la salida renderizada, detecta defectos de maquetación y se autocorrige en tiempo real — cero intervención humana.

El problema

Los agentes de codificación son efectivamente ciegos dentro de Figma. La mayoría de los servidores MCP de Figma son de solo lectura — aplanan un diseño en texto para que un modelo pueda convertirlo en código, y el tráfico se detiene ahí. Los que pueden escribir están limitados por una licencia de Figma de pago con una cuota mensual de llamadas a herramientas, o exponen un vocabulario fijo de comandos (create_rectangle, set_fill) que se agota en el momento en que la tarea se vuelve específica.

Y ninguno responde la pregunta que realmente importa después de una escritura: ¿se veía bien? Un agente que dibuja una tarjeta, recibe {"ok": true} y continúa no tiene forma de notar que su texto se desbordó, que su contraste falló, o que su marco aterrizó encima del trabajo de otra persona.

Este puente cierra ese ciclo y añade las barreras de seguridad que un agente autónomo necesita para que se le confíe un archivo de diseño real.

En qué se diferencia

La versión corta: Framelink es la mejor opción si solo quieres convertir un diseño existente en código. El servidor oficial es la opción más segura si ya estás en un plan de pago de Figma y quieres Code Connect. Este puente es para el caso en que el agente está haciendo el diseño — donde necesita escribir libremente, revisar su propio trabajo y ser deshacible cuando se equivoca.

Cómo 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

El agente habla MCP estándar a través de stdio. El servidor posee un WebSocket RFC 6455 hecho a mano en :8765, al que se conecta el plugin de Figma — así los comandos llegan al lienzo sin latencia de sondeo, y los resultados (incluyendo PNGs base64 de varios megabytes) fluyen directamente de vuelta.

Inicio rápido

npx @kolganovr/figma-mcp-bridge

O, para leer el instalador antes de que toque tu máquina — es el mismo script de cualquier manera, solo se obtiene de forma diferente:

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

Ambos copian el servidor y el plugin en su lugar y registran el servidor MCP en cada configuración de cliente de IA que encuentren — Claude Desktop, Claude Code, Cursor, Windsurf, Antigravity. El paquete npm existe puramente para un primer comando más corto; no añade una sola dependencia de ejecución — dependencies está vacío en su package.json también, y no se necesita Python. node es el único runtime que este proyecto necesita, tanto para el instalador como para el servidor.

Luego, en Figma Desktop:

1. Plugins → Development → Import plugin from manifest… → elige figma-plugin/manifest.json
2. Presiona Ctrl + Alt + P (macOS: Cmd + Option + P) para lanzar Antigravity Bridge
3. El estado se vuelve verde — CONNECTED

Reinicia tu cliente de IA para que detecte las nuevas herramientas. Verifica en cualquier momento con:

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"

Lo que le da al agente

1. Escribe libremente, luego mira el resultado

capture: true devuelve un PNG de exactamente lo que la llamada acaba de crear o modificar — auto-enmarcado a los nodos cambiados, nunca a toda la página, y nunca secuestrando la selección del usuario.

// 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
}

El array warnings es un auto-lint barato sobre el subárbol tocado — desbordamiento de texto, bajo contraste, nodos de tamaño cero. Detecta los errores obvios sin gastar un viaje de ida y vuelta de captura de pantalla.

2. Deshacer cualquier cosa que hizo el agente

Cada escritura abre un punto de control automáticamente. Una llamada lo revierte — sin Ctrl+Z retrocediendo sobre el trabajo no relacionado del 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
}

Los nodos creados se rastrean automáticamente mediante un Proxy alrededor de figma.create*(). Las ediciones de propiedades se rastrean cuando se capturan. Las eliminaciones se informan honestamente como irrecuperables en lugar de perderse silenciosamente.

3. Lee el lienzo en vivo por ~700 tokens en lugar de ~5,000

El mismo pipeline de poda + Pseudo-JSX que impulsa las herramientas en la nube, apuntado a lo que esté abierto ahora mismo. Medido en un diseño realista de 6 tarjetas: 20 KB de JSON crudo de API → 2.7 KB (86% más pequeño).

<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 la respuesta: si la profundidad solicitada se excede, el servidor re-serializa el árbol ya obtenido de forma más superficial — sin un segundo viaje de ida y vuelta — y añade un comentario diciendo qué hizo y qué id buscar para más.

4. Enseña al sandbox nuevos trucos que sobreviven reinicios

Cada llamada a figma_execute_code es un ámbito de función nuevo, así que los helpers normalmente mueren al instante. bridge.define compila y almacena un módulo dentro del 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. Trabajos largos que no mueren en el tiempo de espera

Una generación que aún se está ejecutando después de 30s entrega un job_id en lugar de fallar mientras el plugin sigue trabajando. Consulta figma_job_status para progreso en vivo — el sandbox lo reporta a través de progress(step, of, note).

Referencia de herramientas

Las herramientas se sirven en niveles, para que la lista de esquemas enviada al modelo en cada turno sea proporcional a lo que realmente es utilizable:

Sin un token REST, un agente ve 13 herramientas en lugar de 23 — y nunca desperdicia una llamada en algo que solo devolvería REST_TOKEN_MISSING.

Notas de ingeniería

Las partes que fueron más difíciles de lo que parecen — y por qué el código tiene la forma que tiene.

Pruebas

Cinco suites sin dependencias, todas ejecutables con node básico:

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 genera el servidor real como un proceso hijo y le habla en NDJSON — el mismo transporte que usa un cliente MCP real — en lugar de importar internos.

Estructura del repositorio

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

Fuentes

1. Requisitos de asiento y cuota para el servidor oficial — Figma: Guía para el servidor MCP de Figma, Documentación para desarrolladores de Figma: Límites de tasa y acceso
2. Reducción de tokens medida en un fixture de diseño de 6 tarjetas que imita la salida REST real: 20,587 B crudos → 2,862 B Pseudo-JSX (86.1%) / 1,912 B árbol (90.7%). El fixture está verificado y asegurado — ejecuta node tests/optimizer.test.js para reproducir las cifras exactas.

La comparación refleja el comportamiento documentado públicamente a agosto de 2026. Las alternativas se desarrollan activamente — verifica las capacidades actuales antes de tomar una decisión basada solo en esta tabla.

Licencia

MIT · Construido por Roman Kolganov