smart-figma-mcp

Map Figma designs to your local component library — shadcn/ui, antd, mui, or Astryx — generate code, and write files.

BYOK · Variant-level mapping · Deterministic write · Zero external dependencies

Why smart-figma-mcp?

When you paste a Figma link into Cursor / Claude Code / Codex, AI doesn't know your project components. It generates raw <div> soup every time — wrong styles, no variants, garbage data-node-id attributes. Ask for a <Button variant="ghost-primary"> and you'll get a prop that doesn't exist.

smart-figma-mcp bridges this gap:

We don't compete on "read and suggest". We win on "write and land".

Related MCP server: Component MCP Server

Design-System Contract Engines

The core problem with AI-generated UI isn't layout — it's that the model

guesses at your component API. smart-figma-mcp resolves variants against a

real source of truth instead, and each supported library has its own engine:

Astryx: zero-hallucination mapping

Astryx is Meta's open-source design

system, built to be consumed by AI agents. It publishes its component API as

JSON, so smart-figma-mcp can validate props deterministically instead of

inferring them:

npm install @astryxdesign/core @stylexjs/stylex
npm install -D @astryxdesign/cli

{
  "name": "Button",
  "importPath": "@astryxdesign/core/Button",
  "variants": {
    "variant": ["primary", "secondary", "ghost", "destructive"],
    "size": ["sm", "md", "lg"],
    "elevation": ["none", "low", "med", "high"]
  },
  "requiredProps": ["label"]
}

That variants map is the shipped contract, not a scrape — so

variant="ghost-primary" is rejected because it genuinely isn't in the enum,

not because a heuristic guessed wrong.

Two properties worth knowing:

• Beta-contained. Astryx is v0.x and may break between minors. Contract

  reads are cached per CLI version, and any failure degrades to "no Astryx

  components" — it never breaks component scanning for your other libraries.

• Lazy by design. The 166-component index is enumerated once; props are

  fetched per component on demand rather than all up front.

Quick Start (5 minutes)

npx smart-figma-mcp

IDE Setup

smart-figma-mcp uses MCP (Model Context Protocol). Add this to your IDE's MCP config:

Cursor / Kiro / Windsurf — same JSON, different config paths:

{
  "mcpServers": {
    "smart-figma": {
      "command": "npx",
      "args": ["smart-figma-mcp"],
      "env": {
        "SMART_FIGMA_LICENSE": "<your-license-token>",
        "FIGMA_ACCESS_TOKEN": "<your-figma-personal-access-token>",
        "LLM_PROVIDER": "anthropic",
        "LLM_API_KEY": "sk-..."
      }
    }
  }
}

Codex CLI / IDE extension — config is TOML, not JSON. Add a
[mcp_servers.smart-figma] table to ~/.codex/config.toml (or
.codex/config.toml in a trusted project):

[mcp_servers.smart-figma]
command = "npx"
args = ["smart-figma-mcp"]
startup_timeout_sec = 30
# "writes" prompts before any tool that mutates the filesystem, which is what
# you want for save_component; "auto" trusts the server without prompting.
default_tools_approval_mode = "writes"

Codex spawns the command directly rather than through a shell, so command
takes the bare program name and everything else belongs in args — putting a
whole command line in command is the most common setup error. Secrets are
best passed by reference so they never land in the file:

[mcp_servers.smart-figma]
command = "npx"
args = ["smart-figma-mcp"]
env_vars = ["SMART_FIGMA_LICENSE", "FIGMA_ACCESS_TOKEN", "LLM_API_KEY"]

Or let the CLI write the block for you:

codex mcp add smart-figma --env SMART_FIGMA_LICENSE=<token> -- npx smart-figma-mcp
codex mcp list      # verify it registered

Two Codex-specific notes:

• Startup timeout. A cold npx downloads the package on first run, which
  can exceed the 10s default and surface as a handshake failure. The
  startup_timeout_sec = 30 above avoids it.

• IDE extension. Servers registered via config.toml work in the CLI; the
  VS Code extension has a known issue where it does not always pick them up
  (openai/codex#6465). If tools
  are missing in the extension but /mcp lists them in the TUI, this is why.

Claude Code — use shell env variables instead of inline env:

{
  "mcpServers": {
    "smart-figma": {
      "command": "npx",
      "args": ["smart-figma-mcp"]
    }
  }
}

export SMART_FIGMA_LICENSE="<your-license-token>"
export FIGMA_ACCESS_TOKEN="<your-figma-personal-access-token>"

Tools

Modes

Free Tier (Hacker)

• Pure digital compilation (PURE_DIGITAL path)

• No LLM call, zero token consumption

• Auto Layout nodes → Tailwind/CSS output

• Good for: well-structured Figma files with Auto Layout

BYOK (Bring Your Own Key)

• $9/month or $19 lifetime (early bird)

• Plug your own API key (OpenAI / Anthropic / DeepSeek / Zhipu)

• Usage is attributed to your key; the server makes no LLM calls (code generation runs on your host LLM — already your subscription)

• Semantic + Visual compilation paths enabled

• All tools unlocked

Supported LLM Providers

Set LLM_PROVIDER + LLM_API_KEY to enable BYOK. The server reads only these two variables — provider-specific vars like OPENAI_API_KEY are not consumed.

Compilation Strategy

The compiler auto-detects node complexity with an additive score and routes accordingly:

In BYOK mode the server makes no LLM calls, so this column is always $0 — generation runs on your own host LLM. The costs above apply only to the Credits model.

Score terms: no Auto Layout +30, absolute-positioned child +15 each,

coordinate-flow child +5 each (capped at 50, +20 more beyond 10),

depth beyond 4 +8 per level.

Non-standard layouts don't fail — they return SUGGEST_AUTOLAYOUT, guiding you to fix at the Figma source.

Architecture

┌─────────────┐  JSON-RPC   ┌──────────────────────┐
│  Cursor /   │  over stdio  │  smart-figma-mcp     │
│  Claude Code│◄────────────►│                      │
│  Codex      │              │  ┌────────────────┐  │
└─────────────┘              │  │ Offline         │  │
                             │  │ Ed25519 License │  │
                             │  │ (zero network)  │  │
                             │  └────────────────┘  │
                             │  ┌────────────────┐  │
                             │  │ Variant Mapping │  │
                             │  │ + Compiler       │  │
                             │  └────────────────┘  │
                             │  ┌────────────────┐  │
                             │  │ Daemon (cache)  │  │
                             │  │ Unix Socket IPC │  │
                             │  └────────────────┘  │
                             └──────────────────────┘
                                     │
                              Figma REST API
                              (fetch_figma_node)

Engineering Notes

What follows is the reasoning behind the parts that are not obvious from the

tool list. If you only want to use it, skip this section.

~4,200 lines, no runtime dependencies

No runtime dependencies field in package.json — MCP over stdio plus fetch

and node:crypto are all that is required. This keeps install fast and avoids

the supply-chain surface a dependency tree would add.

Why a tiered compile strategy

A single strategy wastes money and produces bad output. compiler.js scores

every node and routes it by additive score (the table above). Two details in

that scoring are deliberate:

**Coordinate-flow children are counted separately from absolute-positioned

ones.** A child with x/y but no Auto Layout is a grid the compiler can

recover; a child tagged layoutPositioning === "ABSOLUTE" is an overlay it

cannot. Treating the two the same is what makes naive implementations fail on

real design files.

Depth is a hard limit, not a hint. MAX_DEPTH = 6; compileRecursive()

records a depthWarning and skips rather than recursing deeper. Unbounded

recursion on a pathological Figma tree is a real failure mode, and a skipped

subtree is visible in the output instead of silently truncating.

Degrade to advice, not to a guess. When a node is too complex to compile

reliably, the compiler returns SUGGEST_AUTOLAYOUT and points at the

figma_auto_layoutify plugin — a source-side fix. It does not emit code it

cannot stand behind. The free tier is PURE_DIGITAL only, which means the free

path is genuinely deterministic rather than quietly degraded.

Naming reflects what actually ran. The router reports PURE_DIGITAL /

SEMANTIC / VISUAL, while the recursive compiler emits PURE_DIGITAL /

COORDINATE_FLOW / LEAF. The first is a cost decision; the second is the

executed path. They line up in practice but are not the same vocabulary, and

MappingResult.strategy reflects the executed path.

Variant mapping without a config file

mapping.js resolves a Figma node to a local component by inspecting the

project's own component library (shadcn/ui, antd, mui, Astryx). Variants come

from Figma's own variant properties reconciled against the library's contract,

so adding a component to the project is enough — there is no mapping file to

maintain.

Three contract engines, one descriptor

All three supported paths end at the same shape — { name, importPath, variants } —

so mapToVariant() and everything downstream stays library-agnostic. Only the

way the contract is obtained differs:

• Source-derived (shadcn/ui). parseCVA() reads the cva() call out of

  the component's .tsx. It is a heuristic over source that happens to be

  reliable because shadcn has a fixed convention.

• Typed-declaration-derived (antd / mui). mui-antd-contract.js reads the

  library's shipped .d.ts and extracts the literal-union values from each

  <Component>Props type — it resolves named type aliases (type ButtonType = ...)

  and peels mui's OverridableStringUnion<T> wrapper (which otherwise decays to

  string and loses the literals). No cva, no node_modules source scan needed.

• Contract-derived (Astryx). astryx-contract.js shells out to

  @astryxdesign/cli and reads the component's props table directly. The enum

  values are the ones Meta ships, so nothing is inferred.

The interesting part is what the CLI actually hands back: a prop's type is a

raw TypeScript union of string literals, e.g.

"'primary' | 'secondary' | 'ghost' | 'destructive'". parseUnionValues()

turns that into the allowed set, and that set becomes the variants dimension.

A union that contains no literals (string | number) yields an empty set, which

mapToVariant() already handles by leaving that dimension unmapped — the

parser fails closed rather than inventing values.

Beta dependencies are contained, not ignored

Astryx is v0.x and documents that breaking changes may land in any minor

release. Three decisions follow:

• Degrade, never throw. Every CLI call resolves to a tagged error. A missing

  or broken Astryx install reduces the component list to empty; it does not

  propagate into component scanning for the other libraries.

• Version-stamped cache. Contracts are cached under the CLI version that

  produced them, so an upgrade transparently invalidates rather than serving a

  stale enum that would produce wrong code.

• Distinguish missing states. The component command requires

  @astryxdesign/core to be present even if the CLI is installed — without it

  the call returns ERR_CORE_NOT_FOUND. probe_astryx reports

  cliInstalled / coreInstalled separately and returns the exact install

  command, instead of a generic failure the caller has to interpret.

If you use a different node runtime and the CLI cannot be spawned, set

ASTRYX_NODE_BIN to the interpreter to use.

Writing to the filesystem is the point

save_component is the only tool that mutates anything. Three guarantees:

• strips data-node-id before writing (Figma scaffolding, meaningless in code)

• updates the index.ts barrel export so the component is actually importable

• remember_mapping stores a user-confirmed mapping into a private asset

  library, so a known component resolves without re-derivation

check_mapping_health detects when a previously mapped component file has been

deleted or moved, so the library degrades visibly instead of silently producing

dead references.

Long-lived process, bounded memory

Compilation is CPU- and network-bound with low per-request cost, so a

per-invocation process would pay Node startup on every tool call. A daemon

holds the cache and is reached over a socket; daemon-client.js handles

reconnection so a dead daemon degrades to a cold compile instead of an error.

Entitlement without a network call

License validation is offline Ed25519 signature checking (license.js) against

keys/public.pem. The private key is never committed or published.

refresh_crl pulls a revocation list so a revoked token stops working without

shipping new code.

Disclosure: the license issuing tools (tools/keygen.js,

tools/issue-license.js, tools/batch-issue.js) and tools/quota-server.js

are in this repository and in the published npm tarball. They are the

operational side of a self-serve product, not secrets — the signing key is not

here. If that trade-off stops being right, the fix is to move entitlement

server-side, not to hide these files.

Verification status

npm test runs test/smoke.mjs on every push (.github/workflows/test.yml).

It is a smoke suite, not a full test pyramid: it exercises tool routing, tier

selection, and the write path end-to-end. Coverage of the LLM assembly path is

inherently bounded — it needs live Figma files and a provider key, so CI does

not exercise it. Treat the free-tier compile path as the tested surface.

The Astryx contract has its own suite (62 assertions across three files), and the typed-dts contract has a fourth suite:

test/astryx-contract-fixtures.mjs is a captured Astryx CLI response (166

components) rather than a hand-written mock, so the tests fail if the upstream

contract shape changes. Regenerate it when bumping the Astryx version.

FAQ

Q: Does it work without Figma API access?

A: Yes — you can pass figmaNode JSON directly to compile_figma_component. But fetch_figma_node needs FIGMA_ACCESS_TOKEN.

Q: How do I get a license?

A: Purchase from the payment link → receive your license token → paste in MCP config. License is validated offline (Ed25519, zero network calls).

Q: Can I share my license across devices?

A: Yes, up to 2 device fingerprints. Contact support for more.

Q: Does it work with Kiro + Figma Power?

A: Yes — smart-figma-mcp complements Kiro's built-in Figma Power. Figma Power reads designs; smart-figma-mcp deterministically writes code to your project. Use both side-by-side.

Q: Does BYOK mode still consume credits?

A: No — when using your own API key, credits are not deducted. Only the quotas service (if enabled) records usage counts. Note: the server does not call an LLM under BYOK either — code generation runs on your host LLM (Cursor / Claude Code / Codex), which is already covered by your own subscription.

Q: My Figma file has no Auto Layout — will it work?

A: The compiler returns SUGGEST_AUTOLAYOUT for complex non-layout nodes. We strongly recommend using our Auto Layoutify Figma plugin for best results.

Platform Support

Codex is supported via config.toml (TOML, not JSON) — see
IDE Setup for the exact block and two gotchas that produce
confusing failures: a cold npx exceeding the 10s startup timeout, and the IDE
extension not picking up servers that the CLI loads fine
(openai/codex#6465). The CLI is
the reliable path today.

Continue.dev and Cline are Limited because their MCP clients implement the
base protocol but have historically been inconsistent about long-running stdio
servers and tool-result streaming. The limitation is in their clients, not in
this server — if it works for you, it is worth reporting upstream.

Pricing

Buy License →

License

Source available, not open source. The code is published so it can be read,

studied, and evaluated — but you may not redistribute it, build a competing

product from it, or use it under an open source license. See

LICENSE for the granted rights and restrictions. Commercial

licensing is available separately via the

purchase page.

Questions about the license: https://github.com/drake-yuan/smart-figma-mcp/issues

Privacy Policy · Terms of Service