@echobt/figma-mcp

Complete fork of bilalba/fig-mcp — local MCP server for reading and rendering .fig files offline (no Figma API, no PAT, no rate limits).

Maintained at echobt/figma-mcp.

Why this fork

Upstream is a solid fig-kiwi parser + experimental SVG renderer. This fork hardens it for agent design-to-code workflows on large local archives (hundreds of MB, 100k+ nodes):

Verified against a large real file (TAOSCAN - Mockups.fig, ~391MB, 23 pages, ~229k nodes, 1219 images).

Install

npm install -g @echobt/figma-mcp
# or
npx @echobt/figma-mcp --help

Binaries (identical): figma-mcp, fig-mcp.

Quick start (Claude / Cursor / OpenCode)

# Claude Code
claude mcp add figma-mcp -- npx @echobt/figma-mcp

# Or pin a local path
claude mcp add figma-mcp -- node /path/to/figma-mcp/dist/index.js

Example prompts:

Parse /path/to/design.fig, list pages, then export a design spec for the Home frame and take a pixelPerfect screenshot to /tmp/home.png.

CLI

MCP tools

Document structure

Nodes

Content

Images & rendering

Agent copy (fork)

Debug

Agent guide (required reading)

Canonical rules + use cases: MCP_GUIDE.md, or call get_mcp_guide / read resource figma-mcp://guide.

Server initialize also sends short instructions pointing agents at that guide.

Agent workflow (recommended)

Golden rule: never invent SVG d paths or re-draw icons. Always use exported files.

1. get_mcp_guide — hard rules + UC catalog (once per session)

2. list_pages / get_tree_summary — map the file

3. find_nodes or get_node_by_id — pick a frame (session:local)

4. export_asset_pack with outputDir — dumps real assets + AGENTS.md policy

5. Read MANIFEST.json and open nodes/*/node.svg, vectors/*.svg, images/*

6. export_design_spec for exact text/CSS tokens

7. Implement with HTML/CSS + file references (img/src or copied SVG files)

8. Optional render_screen with trueGeometry: true (default) + outputPath for visual QA

get_vector also exports real baked geometry — prefer outputPath and open the file.

Node IDs look like 3779:22748 (from the web viewer or any tool that returns id / nodeId).

How it works

1. .fig files are ZIP archives (canvas.fig fig-kiwi binary, meta.json, thumbnail.png, images/).

2. Schema embedded in each file is decoded with kiwi.

3. Flat nodeChanges are rebuilt into a tree.

4. Images stay in the archive until requested (ImageStore).

5. Subtrees render to SVG → PNG via @resvg/resvg-js.

Develop

npm install
npm run build
npm test
FIG_MCP_TAOSCAN="/path/to/file.fig" npm run smoke:taoscan

Smoke writes evidence under /tmp/opencode/fig-mcp-work/qa-out/ when available.

Requirements

• Node.js 18+

Limitations

• .fig format is undocumented and may change

• Local files only (use official Figma MCP for cloud files)

• Vector export uses Figma baked fillGeometry/strokeGeometry (true path data from the file). Screenshots use that SVG via resvg — not hand-approximated icons. Complex blend modes / full BOOLEAN merge may still be incomplete.

• Agents must use export_asset_pack files, not recreated path strings.

• Very large files still keep the ZIP buffer in memory (images are lazy; canvas decode can still be multi‑GB on enormous docs)

License

MIT — see LICENSE.

Upstream credit: bilalba/fig-mcp by bilal; kiwi by Evan Wallace; MCP TypeScript SDK.