custom-figma-mcp

Ein leichtgewichtiger lokaler MCP (Model Context Protocol)-Server, der KI-Codierungsagenten (wie OpenCode) strukturierten, schreibgeschützten Zugriff auf Figma-Dateien bietet — Dateihierarchien, Node-Eigenschaften und gerenderte Bilder — ohne Figmas gehostete/Remote-MCP-Integration zu benötigen.

Warum dieses Projekt existiert

Figmas offizieller Remote-MCP-Server ist an eine Client-ID auf der Zulassungsliste gebunden, was für einzelne Entwickler, die sich ihr eigenes Agenten-Tooling zusammenbauen, unpraktisch ist. Dieses Projekt umgeht das, indem es direkt mit Figmas öffentlicher REST-API über ein persönliches Zugriffstoken kommuniziert und dem Agenten über eine standardmäßige MCP-Tool-Schnittstelle über stdio bereitgestellt wird.

Related MCP server: ai-ready-ds-auditor

Architektur

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

Der Server ist ein einzelner Node.js-Prozess, der:

1. über stdio startet und sich mit @modelcontextprotocol/sdk registriert.

2. einen festen Satz von Tools über ListToolsRequestSchema beim MCP-Client (OpenCode) bekannt macht.

3. Tool-Aufrufe über CallToolRequestSchema ausführt und sie mit deinem persönlichen Zugriffstoken als Header an Figmas REST-API weiterleitet.

4. strukturiertes JSON (oder Bild-URLs) an den aufrufenden Agenten zurückgibt.

Da er ausschließlich GET-Anfragen mit einem auf Lesen beschränkten Token verwendet, kann er in Figma nichts ändern, kommentieren oder löschen — er ist von Grund auf strikt schreibgeschützt.

Bereitgestellte Tools

get_figma_file_structure

Gibt die Seiten-/Frame-Hierarchie einer Datei zurück, tiefenbegrenzt, um zu vermeiden, dass der gesamte Node-Baum ausgegeben wird (der bei großen Dateien Zehntausende von Nodes umfassen kann).

Eingabe:

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

Zugeordnet zu: GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

Ruft vollständige Eigenschaften für bestimmte Node-IDs ab — Auto-Layout-Konfiguration, Padding-/Gap-Werte, Füllungen, Konturen, Typografie, Constraints, Komponenteneigenschaften usw. Dies ist das primäre Tool für eine präzise Codegenerierung.

Eingabe:

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

Zugeordnet zu: GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

Rendert einen bestimmten Node als PNG und gibt eine temporäre signierte URL zurück, nützlich, um generierten Code visuell mit dem Design abzugleichen.

Eingabe:

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

Zugeordnet zu: GET /v1/images/:fileKey?ids=104:15&scale=2

Warum drei separate Tools (statt einem)

Figma-Dateien können enorm groß sein — ein einzelner GET /files/:key-Aufruf ohne Tiefenbegrenzung kann Megabytes an tief verschachteltem JSON zurückgeben, was das Kontextfenster eines LLM sofort sprengt. Die Aufteilung der Schnittstelle in drei gezielte Tools ermöglicht es dem Agenten:

1. Zuerst eine leichte Übersicht (get_figma_file_structure) abzurufen, um relevante Frames/Nodes zu identifizieren.

2. Nur in die spezifischen Nodes einzutauchen, die er benötigt (get_figma_node_details).

3. Optional nur dann ein Bild zu rendern, wenn eine visuelle Bestätigung erforderlich ist (get_figma_node_image).

Das spiegelt wider, wie ein menschlicher Entwickler ein Design untersuchen würde — zuerst überfliegen, dann hineinzoomen — anstatt die gesamte Datei auf einmal aufzunehmen.

Authentifizierung

Die Authentifizierung verwendet ein Personal Access Token (PAT) von Figma, beschränkt auf file_content:read. Das Token wird aus einer lokalen .env-Datei geladen (niemals hartcodiert) und bei jeder ausgehenden Anfrage als X-Figma-Token-Header angehängt. Das Token verlässt den lokalen Rechner nie, außer bei Anfragen direkt an api.figma.com.

Fehlerbehandlung

Alle Tool-Handler sind in try/catch eingebettet. Bei einem Fehler (ungültiger Datei-Key, fehlender Zugriff, Ratenbegrenzung usw.) gibt der Server eine MCP-konforme Fehlerantwort zurück:

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

Dadurch kann der aufrufende Agent den tatsächlichen Fehlergrund sehen, anstatt lautlos abzustürzen.

Projektstruktur

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

Lokale Entwicklung

Führe den Server direkt zum Debuggen aus (er kommuniziert über stdio, daher siehst du keine typischen HTTP-Server-Logs):

node index.js

In der Praxis führst du dies nicht manuell aus — OpenCode startet ihn als Unterprozess basierend auf dem in opencode.json definierten command.

Diesen Server erweitern

Um ein neues Tool hinzuzufügen:

1. Füge sein Schema zum tools-Array hinzu, das von ListToolsRequestSchema zurückgegeben wird.

2. Füge einen passenden if (name === "...")-Zweig innerhalb des CallToolRequestSchema-Handlers hinzu.

3. Ordne es dem entsprechenden Figma-REST-Endpunkt unter figmaApi zu (einer axios-Instanz, die mit der Basis-URL und dem Auth-Header vorkonfiguriert ist).

Halte neue Tools schreibgeschützt und in ihrem Umfang begrenzt — vermeide es, wo möglich, vollständige ungefilterte API-Antworten auszugeben, um den Kontextverbrauch des Agenten gering zu halten.