custom-figma-mcp

Un servidor MCP (Model Context Protocol) local y ligero que ofrece a los agentes de codificación de IA (como OpenCode) acceso estructurado y de solo lectura a archivos de Figma — jerarquías de archivos, propiedades de nodos e imágenes renderizadas — sin necesidad de la integración MCP alojada/remota de Figma.

Por qué existe esto

El servidor MCP remoto oficial de Figma está limitado por un ID de cliente en lista blanca, lo que no resulta práctico para desarrolladores individuales que configuran sus propias herramientas de agente. Este proyecto lo evita hablando directamente con la API REST pública de Figma mediante un token de acceso personal, expuesto al agente a través de una interfaz de herramientas MCP estándar sobre stdio.

Related MCP server: figma-mcp

Arquitectura

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

El servidor es un único proceso de Node.js que:

1. Se inicia y se registra a través de stdio usando @modelcontextprotocol/sdk.

2. Anuncia un conjunto fijo de herramientas al cliente MCP (OpenCode) mediante ListToolsRequestSchema.

3. Ejecuta las llamadas a herramientas mediante CallToolRequestSchema, actuando como proxy hacia la API REST de Figma con tu token de acceso personal adjunto como cabecera.

4. Devuelve JSON estructurado (o URLs de imagen) al agente que realiza la llamada.

Debido a que solo utiliza solicitudes GET con un token con alcance de solo lectura, no puede modificar, comentar ni eliminar nada en Figma: es estrictamente de solo lectura por diseño.

Herramientas expuestas

get_figma_file_structure

Devuelve la jerarquía de páginas/marcos de un archivo, con límite de profundidad para evitar volcar todo el árbol de nodos (que puede tener decenas de miles de nodos en archivos grandes).

Entrada:

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

Corresponde a: GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

Obtiene todas las propiedades de IDs de nodo específicos — configuración de auto-layout, valores de padding/espaciado, rellenos, trazos, tipografía, restricciones, propiedades de componentes, etc. Esta es la herramienta principal para una generación de código precisa.

Entrada:

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

Corresponde a: GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

Renderiza un nodo específico como PNG y devuelve una URL firmada temporal, útil para contrastar visualmente el código generado con el diseño.

Entrada:

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

Corresponde a: GET /v1/images/:fileKey?ids=104:15&scale=2

Por qué tres herramientas separadas (en lugar de una)

Los archivos de Figma pueden ser enormes: una sola llamada GET /files/:key sin límite de profundidad puede devolver megabytes de JSON profundamente anidado, lo que agota al instante la ventana de contexto de un LLM. Dividir la interfaz en tres herramientas específicas permite al agente:

1. Obtener primero un esquema ligero (get_figma_file_structure) para identificar los marcos/nodos relevantes.

2. Profundizar solo en los nodos específicos que necesita (get_figma_node_details).

3. Renderizar opcionalmente una imagen solo cuando se necesite confirmación visual (get_figma_node_image).

Esto refleja cómo un desarrollador humano inspeccionaría un diseño — primero echar un vistazo y luego acercarse — en lugar de ingerir el archivo completo de una vez.

Autenticación

La autenticación utiliza un token de acceso personal de Figma (PAT), con alcance file_content:read. El token se carga desde un archivo .env local (nunca se escribe directamente en el código) y se adjunta a cada solicitud saliente como cabecera X-Figma-Token. El token nunca sale de la máquina local, salvo en solicitudes directas a api.figma.com.

Manejo de errores

Todos los manejadores de herramientas están envueltos en try/catch. En caso de error (clave de archivo no válida, sin acceso, límite de peticiones, etc.), el servidor devuelve una respuesta de error compatible con MCP:

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

Esto permite que el agente que llama vea el motivo real del fallo en lugar de fallar en silencio.

Estructura del proyecto

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

Desarrollo local

Ejecuta el servidor directamente para depurarlo (se comunica a través de stdio, por lo que no verás los registros típicos de un servidor HTTP):

node index.js

En la práctica, no lo ejecutas manualmente: OpenCode lo lanza como subproceso basándose en el command definido en opencode.json.

Cómo ampliar este servidor

Para añadir una nueva herramienta:

1. Añade su esquema al array tools devuelto por ListToolsRequestSchema.

2. Añade una rama if (name === "...") correspondiente dentro del manejador de CallToolRequestSchema.

3. Asígnalo al endpoint REST de Figma correspondiente dentro de figmaApi (una instancia de axios preconfigurada con la URL base y la cabecera de autenticación).

Mantén las nuevas herramientas de solo lectura y con un alcance limitado — evita volcar respuestas completas y sin filtrar de la API siempre que sea posible, para mantener bajo el consumo de contexto del agente.