figma-rust-mcp

High-performance, bidirectional Model Context Protocol (MCP) server written in Rust connecting AI coding assistants directly to Figma Desktop.

Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Zed) to compile Figma designs into production code, extract design tokens, draw UI directly on canvas, and inspect hierarchy, styles, and assets — with zero external API keys needed.

⚡ Highlights

• Lossless Rust Tree Compression: Compact/minimal tree responses share identical style bundles when the complete JSON becomes smaller. Node IDs, hierarchy, text, geometry and state differences remain intact. Full detail bypasses Rust compression; no heuristic merging of screens or repeated items.

• Pure Rust Native Performance: Single native binary, no runtime or GC. Measure it on your machine with npm run bench or the plugin's Bench tab (see Benchmarks).

• Scoped In-Memory Index (figma_index): Indexes page roots first and loads frame descendants on demand. Search reports the indexed scope and completeness.

• Binary IPC & Chunk Streaming: Powered by MessagePack (rmp-serde) and progressive subtree chunking for instant transfers of massive design files.

• Revisioned Updates: Property patches update affected nodes; revision gaps trigger a fresh snapshot.

• Instant Design-to-Code (figma_to_code): Compiles Figma frames into clean, semantic components (React + Tailwind, React Native, Vue 3 + Tailwind, HTML, SwiftUI).

• Design Token Exporter (figma_get_tokens): Exports variables and styles to Tailwind config, CSS custom properties (:root & dark mode), TypeScript consts, or W3C DTCG Token Studio JSON.

• Batch Asset Extractor (figma_export_assets / figma_export_asset): Extracts SVG icons and raster images directly to project folders (outputPath) with auto-generated TypeScript barrel exports (index.ts) — zero chat token bloating.

• Sandboxed JS Drawing Engine (figma_write): Powered by Boa (pure Rust ECMAScript engine) with built-in asset resolvers and 7 icon packs (Ionicons, Lucide, Tabler, Bootstrap, Fluent, Phosphor).

• Multi-Tab / Multi-Session Support: Seamlessly connects to multiple open Figma files simultaneously.

• 100% Localhost Privacy: All communication stays strictly on 127.0.0.1:41730.

Related MCP server: Figma Dash MCP Server

🏛️ Architecture & Zero-Touch Connection

┌────────────────────────────────────────────────────────────────────────┐
│                      Terminal / Background Service                     │
│                       figma-rust-mcp (Pure Rust Engine)                     │
│  • MCP Streamable HTTP (/mcp) & legacy SSE (/sse, /message)             │
│  • Dynamic Runtime Server (/plugin/code.js, /plugin/ui.html)           │
│  • In-Memory Fast Index (Scoped Lookups & Incremental Diffs)           │
│  • Design-to-Code Compiler (React/Tailwind, Vue, RN, SwiftUI)          │
│  • Design Token Transformer (CSS, Tailwind, TypeScript, W3C DTCG)      │
│  • Sandboxed JS Runtime (Boa ECMAScript Engine)                        │
│  • Binary MessagePack & Progressive Subtree Chunk Receiver             │
└───────────────▲────────────────────────────────────────▲───────────────┘
                │ (ws://127.0.0.1:41730/ws)              │ (http://127.0.0.1:41730/mcp)
                │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / Streamable HTTP)
      ┌─────────┴─────────┐                    ┌─────────┴─────────┐
      │   Figma Desktop   │                    │ AI Assistant(s)   │
      │ (Thin Loader)     │                    │ Google Antigravity│
      │                   │                    │ Cursor / Windsurf │
      │ • Zero-Touch Sync │                    │ Claude Code / Zed │
      │ • Live Hot-Reload │                    └───────────────────┘
      │ • SVG/PNG Render  │
      └───────────────────┘

🔌 How the Zero-Touch Connection Works:

1. Permanent Thin Loader: You only import the Figma plugin once (~/.figma-rust-mcp/plugin/manifest.json).

2. Dynamic Runtime Streaming: Upon launch, the Thin Loader contacts http://127.0.0.1:41730/plugin/code.js to fetch and execute the latest runtime in memory.

3. Live WebSocket Hot-Reload: The plugin connects to ws://127.0.0.1:41730/ws. When you upgrade figma-rust-mcp or restart the daemon, the plugin automatically detects the new server version and hot-reloads seamlessly — no need to re-import or restart the plugin in Figma.

4. Auto-Reconnect & Offline Buffer: If Figma is opened before the Rust service starts, the plugin displays a waiting screen and connects automatically the instant the service is up.

5. Port Range & Auto-Switch: The bridge uses ports 41730–41739. On start it reuses a running server of the same version, skips any port held by another app or a different figma-rust-mcp version, and starts on the first free port. The plugin scans the same range, so it follows automatically. MCP clients configured by URL point at 41730; the server prints a warning with the new port if it had to move.

🚀 Quick Start

1. One-command setup with NPX (No Rust toolchain needed)

npx -y figma-rust-mcp@latest --init

The setup detects installed Codex, Claude Code, Antigravity, Cursor, Windsurf, VS Code/Copilot, and Zed clients. Choose an action from the menu:

1) Quick setup — plugin + background service + detected agents
2) Install/update Figma plugin only
3) Start server in this terminal
4) Configure detected agents
5) Check background service
6) Upgrade package and refresh setup
7) Remove background service
0) Exit

Choose 1 for the recommended setup. It downloads the platform binary, installs the permanent plugin loader, starts the background service at login, then lets you select detected agents (a for all, or comma-separated numbers) and writes each client's MCP config while preserving existing servers. Restart or reload those clients afterward. Then import the manifest into Figma once: open Plugins → Development → Import plugin from manifest..., select ~/.figma-rust-mcp/plugin/manifest.json, and run Figma Rust MCP Bridge. Future updates are streamed to the plugin automatically.

The runner automatically downloads the precompiled native binary for macOS (Apple Silicon or Intel), Linux, or Windows. Use --configure as an alias for --init.

For scripts and direct use, the individual options remain available:

npx -y figma-rust-mcp@latest --setup-plugin      # install/update plugin
npx -y figma-rust-mcp@latest --install-service   # plugin + background service
npx -y figma-rust-mcp@latest --service-status
npx -y figma-rust-mcp@latest --upgrade
npx -y figma-rust-mcp@latest --alias
npx -y figma-rust-mcp@latest --uninstall-service

Run npx -y figma-rust-mcp@latest to launch the interactive server directly.

Windows background mode

Double-clicking figma-rust-mcp.exe starts the server in a detached process and closes its launcher console. From PowerShell or Command Prompt, use:

.\figma-rust-mcp.exe --background

The server keeps running after the terminal closes. Logs are appended to %LOCALAPPDATA%\figma-rust-mcp\logs\server.log. Use --server for the foreground terminal dashboard, or --stdio for an MCP client subprocess.

--install-service through the npm runner configures background startup at login. Re-run the installation command to update an existing Windows task. Removing the task disables future login startup; stop an already detached server through Task Manager (figma-rust-mcp.exe). The launcher console may appear briefly when opening the executable; the server itself does not retain a console window.

2. Build from Source (Optional)

If you prefer building directly with the Rust toolchain (cargo >= 1.80):

git clone https://github.com/BuiHung1612/figma-mcp.git
cd figma-rust-mcp
cargo build --release
./target/release/figma-rust-mcp

3. Configure Your MCP Client

The --init quick setup can add the local server to detected clients. To configure one manually, use the matching section below.

Codex and clients using Streamable HTTP (Recommended)

Use the /mcp endpoint. It accepts POST JSON-RPC requests directly:

[mcp_servers.figma-rust-mcp]
url = "http://127.0.0.1:41730/mcp"

For Codex CLI, the equivalent command is:

codex mcp add figma-rust-mcp --url http://127.0.0.1:41730/mcp

Google Antigravity (SSE Transport)

Add to your ~/.gemini/config/mcp_config.json or project .agents/mcp_config.json:

{
  "mcpServers": {
    "figma-rust-mcp": {
      "serverUrl": "http://127.0.0.1:41730/sse"
    }
  }
}

Claude Code / Cursor / Windsurf / VS Code / Zed

These clients can use the Streamable HTTP /mcp endpoint:

{
  "mcpServers": {
    "figma-rust-mcp": {
      "url": "http://127.0.0.1:41730/mcp"
    }
  }
}

For Zed, place the server entry under context_servers in settings.json. Alternatively, configure a stdio subprocess via NPX:

{
  "mcpServers": {
    "figma-rust-mcp": {
      "command": "npx",
      "args": ["-y", "figma-rust-mcp", "--stdio"]
    }
  }
}

6. Diagnose a stale Figma runtime

Check the runtime bundle currently served to Figma Desktop:

curl http://127.0.0.1:41730/plugin/version

The response includes version and runtimeHash. If the hash changes after an upgrade, the dynamic plugin runtime is refreshed automatically. Restart the Figma plugin only if the reported hash does not change.

🛠️ MCP Tools Reference

figma-rust-mcp provides 15 first-class MCP tools:

1. figma_status

Checks live bridge connection status, connected Figma tabs/files, in-memory index health, queue length, and latency statistics.

2. figma_inspect_node

Reads a specific node by ID or name through the canonical flat read_nodes response. Select fields explicitly to control the work performed.

3. figma_to_code

Compiles any Figma node (Frame, Component, Section, or selection) directly into clean, production-ready component code.

• framework: "react-tailwind" (default), "react-native", "vue-tailwind", "html", "swiftui".

• outputPath: Directly saves the generated component to your codebase (e.g. src/components/UserProfileCard.tsx).

• componentName: Custom component name override.

4. figma_get_tokens

Exports Figma Variables (Design Tokens), Color Styles, Typography Styles, and Elevation/Shadow Styles directly into frontend code.

• format: "tailwind" (tailwind.config.js theme.extend), "css" (:root CSS custom properties with light/dark theme modes), "typescript" (tokens.ts), "w3c" (W3C DTCG Token Studio JSON), or "json".

• outputPath: Writes directly to disk (e.g. src/styles/tokens.css or tailwind.config.js).

• collection / mode / prefix: Optional filters and naming prefixes.

Token exports use schema v2 and preserve full paint/effect stacks, alpha, gradient transforms, collection modes and raw alias values. CSS, Tailwind, TypeScript and JSON share one normalized model. The w3c output uses DTCG 2025.10 color, dimension, gradient-stop and shadow values, with Figma-specific geometry and unsupported values retained in $extensions.

Linear gradients on a node are projected using its actual dimensions. A diagonal gradient style has no target aspect ratio: use get_css on its consuming node. Radial/angular/diamond paints, unsupported blend modes and progressive blurs retain their raw data and report diagnostics recommending SVG instead of emitting approximate CSS. Unknown modes, unresolved aliases and sanitized name collisions fail explicitly. CSS exports include non-default modes under data-theme selectors; opacity/font-weight variables stay unitless.

The plugin UI badge is stamped from the build version and updated from the connected server handshake. Package/Cargo/tag mismatches fail the build pipeline. Run npm run build:plugin after changing plugin source, and npm run test:tokens for the token/contract/version regression suite. Existing background servers need a restart with the new binary to load the updated runtime.

5. figma_get_selection

Inspection of currently selected layers/frames, with shared-style compression when it reduces response size.

• detail: "compact" (default), "minimal", "full".

Compact/minimal get_selection and get_design responses may contain a root _compression object with version: 1 and a styles dictionary. For each node with styleRef, merge _compression.styles[node.styleRef] into that node and remove styleRef; remove root _compression to reconstruct the plugin payload exactly. Style references are dictionary lookups, not inherited CSS. Payloads with reserved-field collisions or no net byte savings stay inline. detail: "full" bypasses this Rust transformation and queries the plugin rather than a compact selection cache. Plugin detail, visibility, precision, depth and node budgets still determine the source payload; compression cannot restore fields omitted there. Code generation continues to consume inline styles.

No token-reduction or AI-latency percentage is claimed without a tokenizer and end-to-end benchmark on real designs.

• depth: Tree depth limit or "full".

6. figma_export_asset

Exports any Figma node/layer directly into PNG, JPG, or SVG.

• outputPath: When specified (e.g. src/assets/logo.png), saves directly to disk and returns minimal JSON metadata instead of bloating context with large base64 strings.

• format: "png" (default), "jpg", "svg".

• scale: Scaling factor (default 2 for high-res).

7. figma_export_assets

Batch extracts all SVG icons and PNG images from a Figma frame/page directly into project directories.

• iconDir: Directory path for SVG icons (e.g. src/assets/icons).

• imageDir: Directory path for raster images (e.g. public/images).

• createBarrel: Automatically creates an index.ts barrel export file in iconDir.

8. figma_index

In-memory queries against pre-indexed Figma file structures (latency for your file: plugin Bench tab).

• operation:

  • "status": View index health and node counts.

  • "search_nodes": Search nodes by text name, query, and type (FRAME, TEXT, COMPONENT, INSTANCE).

  • "get_node": Instant node lookup by ID.

  • "search_components": Find component sets and variants.

  • "search_styles": Find paint, text, and effect styles.

  • "search_variables": Find design token variables by name or collection.

  • "refresh": Refresh page roots, or expand the frame specified by nodeId.

  • "subtree": Read/cache one nodeId, default depth 2 and 1000 nodes. Increase depth or maxNodes only for the section you need; check meta for truncation.

  • "typography": Rust-generated text/font table for one nodeId, with mixed-style runs preserved. Default limit 200 rows. Null font fields mean unknown/mixed, not a guessed default.

status includes per-tab dispatch cache hits/misses, bridge calls and total bridge wait time, plus process-wide tool call counts and total/average milliseconds. Node changes invalidate related subtrees; style changes, unknown events and global writes invalidate the whole cache. Detailed subtree data is loaded on demand. The initial index remains shallow.

For typography verification, call figma_verify_ui with a text nodeId and browser computedStyles (font-size in px, numeric font-weight, font-family). Mixed text accepts computedStyles.segments, an ordered array of CSS objects matching the Figma runs. Size checks preserve fractional pixels.

9. figma_read

Universal reader for advanced queries:

• Design-to-code: read_nodes, get_css, get_component_map, get_unmapped_components.

• Inspection & Hierarchy: read_nodes, get_selection, get_page_nodes, scan_design, search_nodes.

• Design Systems: get_styles, get_variables, get_local_components, get_tokens.

• Visuals & Canvas: screenshot, export_svg, export_image, get_viewport.

10. figma_write

Executes JavaScript draw commands inside the sandboxed VM to build or modify designs on the Figma canvas.

• Supports Auto-layout (layoutMode, itemSpacing, padding), typography, fills, strokes, corner radius, drop shadows, and component creation.

• Supports icon loading: figma.loadIcon("ionicons", "heart", { size: 24, fill: "#ff4757" }).

• Supports image insertion: figma.loadImage(url, { width: 300, height: 200 }).

• Supports Design Tokens: createVariableCollection, createVariable, addVariableMode, applyVariable.

• Supports Prototyping & Reactions: setReactions, getReactions, setScrollBehavior.

11. figma_rules

Audits the current Figma document and generates a complete design system rule sheet (color tokens, typography styles, variables, component catalog) from the in-memory cache.

12. figma_docs

Fetches built-in documentation, design rules, layout guidelines, and code examples for figma_write.

• section: "rules" | "layout" | "api" | "tokens" | "icons"

13. figma_verify_ui

Validates and compares actual rendered HTML/React UI styles and layout against Figma design specifications.

• Checks dimensions, padding, flex gap, colors, border-radius, and typography.

• Returns an exact match percentage (match_percentage), discrepancy breakdown, and actionable CSS/Tailwind fixes.

• nodeId / nodeName: Target Figma node spec.

• computedStyles: Key-value pairs of computed CSS properties from browser/component inspection.

• url / selector: Contextual target URL or CSS selector inspected.

14. figma_match_components

Scans your local codebase directories (src/components, components/ui) to discover existing React/Vue components and matches them directly against Figma design layers, preventing duplicate component creation and ensuring reuse of existing design systems.

• projectDir: Base directory of your project (default: current directory ".").

• nodeId: Optional Figma node ID to check specific match against local components.

15. figma_prepare_design

All-In-One Multimodal Grounding Pack for AI: The ultimate single-call tool for code generation that eliminates missing UI elements and icon guesswork.

• Simultaneously extracts 100% of visible text elements (greeting, badges, timestamps, labels).

• Automatically exports all SVG vector icons into your local project directory (iconDir) and provides exact TypeScript import statements.

• Captures high-res visual canvas screenshots saved locally for immediate multimodal LLM inspection.

• Discovers existing components in your codebase for direct reuse.

• Generates an actionable Implementation Checklist ensuring complete design fidelity in 1 single shot.

• nodeId: Target Figma screen/frame ID.

• iconDir: Target directory for SVG icons (e.g. src/assets/icons or assets/images).

• projectDir: Base directory for component discovery.

Multiple tabs and frame tasks

Each plugin runtime has its own sessionId; tabs of the same file share a documentId. Use figma_status to discover tabs. With multiple connected tabs, pass an exact sessionId; the server rejects ambiguous routing.

For multiple agents editing one file, call figma_task with action: "start", sessionId and frameId, then pass the returned taskId on subsequent tools. Each task reserves a separate FRAME directly under a PAGE or SECTION, without shared component definitions. Writes stay inside that frame; global styles, variables, page and selection changes are blocked. A frame cannot be reserved twice, including across tabs of the same document. Release it with figma_task using action: "end" and taskId; restart tasks after a plugin reload.

Tools on one tab run sequentially, including every awaited operation in a figma_write call. Different tabs run independently. npm run test:sessions (Node >=22) checks real WebSocket/HTTP transport with a simulated plugin canvas; it does not replace validation in Figma Desktop.

Startup indexing and v4 migration

Version 4 requires both server and plugin runtime protocol 3. Update both and restart the plugin. Opening the bridge indexes only visible top-level nodes on the active page, plus local styles and variables. Selection expands the selected frame. Component catalogue discovery is deferred; request it with figma_index({ operation: "refresh", includeComponents: true }).

Search covers indexed scopes only. Inspect scope and complete in search responses; an empty result does not prove a layer is absent from the file. Refresh a specific frame to expand its scope:

figma_index({ operation: "refresh", nodeId: "123:456", expandInstances: true })
figma_read({ operation: "read_nodes", nodeId: "123:456",
  fields: ["geometry", "content", "text", "style", "layout", "tokens", "component"],
  limit: 200, expandInstances: true })
// Continue using the returned cursor; do not repeat or change traversal options.
figma_read({ operation: "read_nodes", cursor: nextCursor, limit: 200 })

read_nodes returns a flat envelope: { schemaVersion: 4, pageId, revision, scope, nodes, nextCursor, complete, totalRead, budgetReached }. Identity and topology are always included. Default fields are geometry and content; typography, paints, layout, variable/style references and component metadata are opt-in. Token fields contain references, not resolved CSS values. Page reads default to depth 0; frame reads default to full traversal (maximum 256 levels). Limit is 1?500 nodes per response; traversal stops at 50,000 visited nodes. complete describes the requested scope, including its depth and filters. Restart from the root if the page or document revision changes between cursor requests. Cursors are single-use and at most 16 traversals can remain open.

Instances are opaque by default: opaque: true and no descendant traversal. Set expandInstances: true to read the actual instance children and overrides. Hidden nodes require includeHidden: true. Expansion and visibility are separate options; no master component is substituted for an instance.

Breaking output changes: public get_design, get_design_context and get_node_detail aliases now return the same envelope as read_nodes. figma_inspect_node and index get_node, subtree, typography also return that envelope. Replace nested children consumers with nodes and parent/child IDs. Replace index maxNodes with limit and cursor pagination. Internal script helpers used for code generation retain their specialized formats.

Canvas traversal reads each child list once, yields after an 8ms slice, and streams chunks of up to 500 nodes. Snapshots commit atomically; frame refreshes preserve other indexed frames. Revisioned create/delete/property patches invalidate affected cached reads, while unrelated nodes remain queryable. Structural additions mark coverage incomplete until the scope is reread. Revision gaps request resynchronization. Page switches rebuild the shallow index without preloading every page. Exact-read caching evicts one least recently used entry when its 64-entry capacity is reached.

📏 Benchmarks

npm run bench builds the release binary and prints a JSON report from a fresh server: cold start, process startup, server RAM and MCP dispatch latency. A fresh server has no Figma session, so plugin and index measurements are explicitly skipped.

To measure real work, connect the Figma plugin and use the existing server:

# Server report, including its current index and plugin round trip
node scripts/bench.mjs --url http://127.0.0.1:41730

# Read all descendants of a frame, index that frame, and export it as a 1x PNG
node scripts/bench.mjs --url http://127.0.0.1:41730 \
  --target 'SESSION_ID=FRAME_ID' --samples 3 > benchmark.json

# Run the same workloads concurrently on two tabs
node scripts/bench.mjs --url http://127.0.0.1:41730 \
  --target 'FIRST_SESSION=FIRST_FRAME' --target 'SECOND_SESSION=SECOND_FRAME'

Find session IDs at GET /sessions and frame IDs in the plugin selection card. Use one frame per session and 1–10 samples per workload. Workloads read Figma content; they do not modify canvas nodes. Indexing updates the bridge's cache, and PNG export may briefly move the viewport before restoring it.

Reports contain each sample plus p50/p95/max. Reads use the normal cache, so the samples are not guaranteed cold reads. Truncated reads remain marked incomplete; failed workloads retain their error and the CLI exits with status 1. Real Figma results depend on your file; simulated integration tests only verify the path.

The plugin's existing Bench tab retains the basic POST /benchmark report. Use the CLI for the heavier frame and concurrent-tab workloads.

💻 Development & Testing

# Run server in debug mode
cargo run

# Build optimized release binary
cargo build --release

# Run automated MCP test suite
./scripts/test-rust-mcp.sh

# Rebuild Figma plugin bundle (if plugin-src/ is modified)
node scripts/build-plugin.js

📄 License

MIT © BuiHung1612 — Free to use, modify, and distribute. See LICENSE for details.

Bounded design specs

Use figma_read with operation: "get_spec" instead of loading a full frame into the model context:

{"operation":"get_spec","nodeId":"1467:84778","mode":"overview","sessionId":"<tab-id>"}

• overview defaults to depth 2, returning section IDs for discovery. It does not claim deep text coverage.

• Read each section with mode: "spec"; mode: "detail" reads one node at depth 0. fields can select geometry/layout or content/text independently.

• maxBytes defaults to 24000 raw node bytes per page. Continue nextCursor with the same sessionId, mode and optional byte budget. No records are dropped. A single large node, response metadata and resolved component references can exceed this target.

• Exact repeated style bundles use _compression.styles; repeated node properties use templates. Decode template references first, then style references. Identity, topology, copy, geometry, variants and mixed text remain reconstructable. This is property sharing, not heuristic merging of visually similar subtrees.

• coverage.subtreeComplete distinguishes a complete deep read from exhausted pagination at a shallow depth. Counts describe the returned page, not unread descendants.

• Pass outputPath on a fresh request to save all pages of the requested scope as raw JSON and return only coverage/path. A shallow overview export remains shallow. Raw data is also available through the existing session cache and node-ID reads.

• Existing read_nodes remains raw by default; detail: "compact" enables lossless shared-style compression. It also accepts maxBytes.

figma_prepare_design now follows expanded instance pagination for text and reports separate text/asset coverage. Default compact output omits the redundant colorPalette; use detail: "full" to retain it. Pass outputPath to save the grounding pack plus raw design records outside context. Asset export caps and failures are reported; exported icons do not imply all assets were inspected.