Zafiro.FigReader.Mcp 0.4.0

dotnet tool install --global Zafiro.FigReader.Mcp --version 0.4.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Zafiro.FigReader.Mcp --version 0.4.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Zafiro.FigReader.Mcp&version=0.4.0
                    
nuke :add-package Zafiro.FigReader.Mcp --version 0.4.0
                    

Zafiro.FigReader.Mcp

An offline MCP server that reads local Figma .fig files so an AI agent can inspect and reproduce a design — structure, layout, colors, typography, text and embedded images — without the Figma API, an account or a token. Think Framelink, but it parses the exported .fig binary directly instead of calling Figma's servers.

Why

The Figma REST API is free but requires a token and an internet round-trip, and Framelink-style tools stream large payloads. Zafiro.FigReader.Mcp works on a .fig you exported yourself (Figma → File → Save local copy…), fully offline, and returns compact, token-efficient JSON.

How it works

A .fig file is a ZIP containing canvas.fig (+ meta.json, thumbnail.png, images/, videos/). canvas.fig is Evan Wallace's Kiwi binary format:

"fig-kiwi" (8 bytes) | uint32 version | chunk0 | chunk1 | ...
chunk = uint32 length + payload
chunk0 = Kiwi binary schema (raw DEFLATE) — self-describing
chunk1.. = Kiwi message (raw DEFLATE or Zstandard) → root type "Message"

The message holds a flat list of nodeChanges (Figma's CRDT model); Zafiro.FigReader.Mcp rebuilds the node tree from each node's parentIndex (parent GUID + fractional position). The Kiwi decoder is a clean-room port of evanw/kiwi; Zstandard is handled by ZstdSharp.Port. No native dependencies.

Build & test

dotnet build -c Release
dotnet test # unit tests and synthetic file integration tests

Integration tests generate small fig-kiwi archives in temporary files. They cover document navigation, search, instance overrides and vector decoding without an external design export or environment variables.

Install

Published as a .NET tool on NuGet (requires the .NET 10 SDK/runtime):

# Install globally...
dotnet tool install -g Zafiro.FigReader.Mcp
# ...then run:
figreadermcp

# ...or run without installing:
dnx Zafiro.FigReader.Mcp

The server speaks MCP over stdio (logs go to stderr, so stdout stays clean for the protocol).

MCP client configuration

VS Code (.vscode/mcp.json)

{
  "servers": {
    "figma": {
      "type": "stdio",
      "command": "dnx",
      "args": ["Zafiro.FigReader.Mcp", "--yes"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "figma": {
      "command": "dnx",
      "args": ["Zafiro.FigReader.Mcp", "--yes"]
    }
  }
}

If you installed the tool globally you can instead use "command": "figreadermcp" with no args.

Build from source

dotnet build -c Release
dotnet src/Zafiro.FigReader.Mcp/bin/Release/net10.0/Zafiro.FigReader.Mcp.dll

(Avoid dotnet run for MCP: its first-run build output can corrupt the stdio protocol.)

Tools

Tool Purpose
load_file(path, forceReload?) Decode a .fig and return a summary (file name, pages, node-type histogram, blob count). Call first; result is cached and decoded again when the file changes on disk (forceReload=true forces it).
get_metadata(path?) meta.json + high-level counts.
get_node_tree(nodeId?, depth?, path?) Compact hierarchy (id, name, type, bounds, fills, strokes, auto-layout, text). INSTANCE nodes are expanded to the symbol content they render, with overrides applied (effective text, per-node visibility, icon instance-swaps as swappedTo).
get_node(nodeId, raw?, path?) Full detail for one node. For an INSTANCE, resolvedChildren lists the effective labels, icons (swappedTo) and visibility. Set raw=true for the unfiltered Kiwi object.
get_text(nodeId?, path?) All text content + typography under a subtree.
get_styles(path?) Colors actually used (with counts, after resolving bound variables) and distinct text styles.
get_vector(nodeId, geometry?, path?) Decode a node's vector geometry into SVG path(s) (with an F0/F1 fill-rule prefix, ready for an SVG d/Avalonia StreamGeometry). Pass geometry="strokeGeometry" for the stroke outline.
list_images(path?) Embedded image/video blob entries.
export_image(entry, outputDirectory, path?) Extract a blob to disk.
search_nodes(query, type?, limit?, nodeId?, path?) Find nodes by name, text, or instance overrides; optionally scoped to a subtree such as a page.

Node ids use the form sessionID:localID. Tools other than load_file default to the most recently loaded file when path is omitted.

Instances

Figma stores an INSTANCE as a reference to a SYMBOL plus a set of overrides, so instances carry no child nodes of their own. get_node_tree/get_node resolve that for you: they walk the referenced symbol and apply symbolOverrides (text, visibility, size, position, fills, typography, …), the layout Figma derived for the instance (derivedSymbolData) and componentPropAssignments (text component properties and instance-swaps — e.g. an icon). Nested instances are resolved recursively, so an icon inside a tab inside a tab-menu is surfaced as the actual component it renders.

A nested instance renders the component assigned to the instance-swap property it is bound to; otherwise the component set by a swap override (overriddenSymbolID); otherwise its own component. The swapped layer reports swappedTo/swappedToId. A swap to a component missing from the file keeps the original component and reports the missing id as unresolvedSwap.

Variables

Solid paints bound to a color variable report the variable's value, following alias chains and library variables (assetRef). Each variable is read in the first mode of its collection; explicit mode selection per frame is not modelled. A binding that cannot be resolved is reported as { "color": "<stored literal>", "unresolvedVariable": "<reference>" } instead of a plain hex color, and get_styles counts such usages in unresolvedVariableUsages.

Example

// Synthetic example of get_node_tree on a button symbol
{
  "id": "1:100", "name": "Example/Primary", "type": "SYMBOL",
  "width": 200, "height": 40, "fills": ["#0000FF"],
  "layout": { "mode": "HORIZONTAL", "gap": 8, "padding": [8,16,8,16],
              "primaryAlign": "CENTER", "counterAlign": "CENTER" },
  "children": [
    { "id": "1:101", "name": "Label", "type": "TEXT",
      "text": { "characters": "Example", "fontFamily": "Sans",
                "fontStyle": "Regular", "fontSize": 16, "color": "#FFFFFF" } }
  ]
}

Layout

src/Zafiro.FigReader.Core      Kiwi decoder, .fig container reader, document model, extraction
src/Zafiro.FigReader.Mcp    MCP stdio server + tools
tests/Zafiro.FigReader.Core.Tests

Limitations

  • The Kiwi schema is reverse-engineered; if Figma changes the format, extraction may need updates (the embedded schema keeps basic decoding working across versions).
  • Instance resolution covers property overrides, derived layout and text/instance-swap component properties; exotic property kinds (slots, exposed nested props) and named text styles are surfaced only partially.
  • Variables are resolved for paint colors only, in each collection's default mode.
  • Large files take a few seconds to decode on first load (then cached in memory).

License

MIT — see LICENSE.

The Kiwi binary decoder is a port of evanw/kiwi (MIT). Third-party licenses and attributions are listed in THIRD-PARTY-NOTICES.md.

"Figma" is a trademark of Figma, Inc. This project is not affiliated with, endorsed by, or sponsored by Figma, Inc.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.4.0 148 10/13/2026
0.3.0 109 10/13/2026
0.0.6 113 10/9/2026
0.0.5 119 10/3/2026
0.0.4 169 7/30/2026
0.0.3 184 6/22/2026
0.0.2 147 6/19/2026

# Changelog 0.4.0

## Changes (initial history)

- fix: resolve instance swaps on the bound layer (`68a8ad3`)
- feat: apply property overrides and derived layout in resolved instances (`350cbbe`)
- feat: resolve bound color variables (`75c2205`)
- fix: reload .fig files changed on disk (`349b484`)
- test: replace external design fixtures with synthetic coverage (`88807e9`)
- fix: set ContentRootPath to AppContext.BaseDirectory to avoid recursive inotify watches (`fe6aa7c`)
- feat: resolve instance overrides and decode vector geometry (`a1b34dd`)
- fix: improve figma search context (`ac68540`)
- Rename project to Zafiro.FigReader.Mcp (drop "Figma" from public identifiers) (`9e5b69a`)
- Initial commit: Zafiro.Figma.Mcp — offline Figma .fig MCP server (`4d1d22b`)