figma-mcp

Figma → code that is actually checked against the design.

Most Figma-to-code tools stop at the moment of generation: they hand you JSX and walk away. Nobody ever renders the output and compares it to the frame, so the result stalls at "90% there" and you spend the afternoon nudging padding by eye.

This MCP server closes that loop. It converts a frame to self-contained HTML deterministically (no LLM, no hallucinated layout), then renders your code in Chromium, pixel-diffs it against the Figma reference, measures every element's box, and tells the agent exactly what is missing or misplaced. The agent edits, calls verify again, and repeats until the diff is at the anti-aliasing floor.

Those are real artifacts from npm run example, which runs the loop end to end with no API key. The generate callback in that demo is a scripted stand-in for an LLM, so it shows the loop mechanics honestly — the measuring is real, the "model" is not.

Why the verify step matters

A Figma node tree tells you what the designer declared. It does not tell you what a browser will do with your CSS. Those diverge constantly — a flex gap that collapses, a font that falls back, an absolute child that escapes its parent. The only way to know is to render it and look.

figma_verify gives the agent two independent signals per pass:

• Pixel diff — the overall mismatch ratio plus the worst regions, so it knows how wrong and where.

• Element bounding-box IoU — every IR node is tagged data-ir-id, measured in the live DOM, and matched against its Figma box. This is what turns "the bottom-left looks off" into "the CTA button is missing" or "the price label is 40px too low".

Related MCP server: figmad-mcp

Tools

Every tool returns file paths and numbers, never large blobs. A converted frame is often 100+ KB of HTML; pushing that through a tool result would burn the agent's context for nothing. The agent reads and edits the files directly.

Figma responses are cached per frame, so after the first figma_convert the whole loop runs offline and free — including when you are rate-limited.

Quick start

You need a Figma personal access token: Figma → Settings → Security → Personal access tokens, scope File content: read.

export FIGMA_TOKEN=figd_REPLACE_WITH_YOUR_TOKEN

Add it to Claude Code:

claude mcp add figma --env FIGMA_TOKEN=$FIGMA_TOKEN -- npx -y @mehmoodqureshi/figma-mcp

Or for any MCP host that reads a JSON config:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@mehmoodqureshi/figma-mcp"],
      "env": { "FIGMA_TOKEN": "figd_REPLACE_WITH_YOUR_TOKEN" }
    }
  }
}

Then, in the agent: copy a frame link out of Figma (right-click the frame → Copy link to selection) and say "convert this frame and verify it until it converges."

Windows

npx resolves to npx.cmd, which some MCP hosts cannot spawn directly. If the server fails to start, point at the shim explicitly:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@mehmoodqureshi/figma-mcp"]
}

The loop, concretely

figma_convert  →  generated.html, reference.png, ir.json   (deterministic, no LLM)
      ↓
figma_verify   →  "NOT CONVERGED — 4.93% of pixels differ.
                   Elements: 22/26 match — 1 missing, 3 misplaced.
                   MISSING: button 'Get started'
                   MISPLACED: h1 'Pricing plan' — 6px too high"
      ↓
  agent edits generated.html
      ↓
figma_verify   →  "CONVERGED — 0.31% of pixels differ (threshold 2.00%)."

The refine loop runs through the calling agent, not through an LLM inside the server. That means no ANTHROPIC_API_KEY, no second model billing, and the agent keeps full context on what it already tried. A headless refine loop (src/refine/) still exists for library use.

Configuration

See .env.example. Add .figma-cache/ to your project's .gitignore — a cached frame with embedded assets is tens of megabytes.

What it does not do

Being straight about the edges, because they are Figma's, not bugs:

• Design tokens resolve to literals unless you are on Enterprise. The Figma Variables REST API is Enterprise-only. Without it, colors and spacing come out as exact values rather than var(--color-surface). Everything else works.

• Component prop bindings need Code Connect. Components are matched by name and reported, but the API does not expose which instance prop drove which value.

• The diff has a floor. Anti-aliasing and font hinting keep the ratio around 0.5–1.5% even on a perfect match. threshold defaults to 2% for that reason — chasing 0 is chasing rendering noise.

• One frame at a time. No whole-file crawling, by design: it keeps token spend and Figma rate-limit pressure predictable.

Use it as a library

The verify loop is framework-agnostic and does not need the MCP layer:

import { verifyLoop } from '@mehmoodqureshi/figma-mcp';
import fs from 'node:fs';

const result = await verifyLoop({
  initialCode: firstPassHtml,
  referencePng: fs.readFileSync('frame.png'),
  ir,                                   // enables element-level IoU findings
  viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
  threshold: 0.02,
  maxIterations: 5,
  generate: async ({ code, correction }) => callYourModel({ code, correction }),
});

console.log(result.converged, result.diffRatio);
fs.writeFileSync('diff.png', result.bestDiffPng);

The loop keeps the best iteration seen, so a later regression never makes the result worse. To verify a React component on a dev server instead of an HTML string, pass render: () => renderUrl('http://localhost:3000/preview', viewport).

Develop

git clone https://github.com/Mehmoodqureshi/figma-mcp.git
cd figma-mcp
npm install          # also downloads Chromium via postinstall
npm test             # full chain against a mocked Figma API — no token, no network
npm run example      # the verify loop end to end; watch the diff ratio fall
npm run serve        # run the MCP server on stdio

example/ doubles as the test suite — npm test runs the full loadFrame → figmaToIR → generateHtml chain against a mocked Figma REST API, including rate-limit handling and rotation/mirror transforms. No token, no network, no browser, so it runs in CI on every push.

License

MIT © Mehmood Ur Rehman Qureshi