Figbridge

Figbridge

Figma ↔ code, in both directions. Free, open source, local, and built for the community.

Figbridge is a Figma plugin + local MCP server. Open the plugin on any file, toggle the Live bridge, and any MCP-capable agent (Claude Desktop, Claude Code, Cursor, Continue, Cline…) can read screens, tokens, and components, import a whole URL into Figma, audit the imported design, diff it back against the source, and emit a patch for the source repo — over 127.0.0.1.

┌──────────┐   postMessage   ┌──────────┐   HTTP + SSE    ┌───────────────┐     stdio     ┌──────────────┐
│  Figma   │ ──────────────▶ │  Plugin  │ ──────────────▶ │  MCP Server   │ ◀──────────── │  AI agent    │
│  Desktop │                  │   UI     │   :7331/push    │  (localhost)  │   tools/call  │  (Claude …)  │
└──────────┘                  └──────────┘                 └───────────────┘               └──────────────┘

Why

Figbridge is built for the community path: free, open source, local, and useful from website capture all the way back to source patches.

Figbridge:

• Free. MIT. Runs entirely on your machine.
• No account, no token. Uses your existing Figma desktop session.
• 54 MCP tools. Read, catalog, write-back, lint, map Figma components to code (Code Connect without a Dev seat), ship an agent handoff bundle, import a live URL into Figma, audit the imported design across 5 dimensions, round-trip changes back to a source repo as a patch, and run a closed visual-diff loop that brings a running app into line with its mockup.
• Import diagnostics before you wait. preflight_import flags bot pages, deep DOM, low-res images, SVG-heavy pages, and downloadable font assets before a full import.
• Hybrid fallback for hard pages. import_url({ hybridSnapshot: true }) can place a full-page screenshot reference under editable layers for video-heavy or generated sites where pixel fidelity matters.
• Chrome/Edge current-tab capture. Load chrome-extension/ unpacked to send visible viewports, full pages, selected elements, authenticated tabs, localhost, or staging pages directly to the local bridge.
• Offline agent bundle. get_agent_bundle produces a zip (hierarchy · tokens · components · AGENTS.md · CHANGES.md) an agent can ship from without a live MCP connection.
• Deterministic. No LLM rewrites. What you select is what you get.
• Live. Toggle "Live bridge" and every selection change auto-pushes; agents pull the current selection instantly.

Install — ~3 minutes

The plugin is not in Figma Community yet, so you clone the repo to get it. The MCP server comes from npm.

# 1. Get the Figma plugin (clone the repo)
git clone https://github.com/rudraptpsingh/figbridge

# 2. Patch Claude Desktop's MCP config
npx figbridge-mcp init

Then:

1. Quit and reopen Claude Desktop — it only reads MCP config at launch.
2. In Figma: Plugins → Development → Import plugin from manifest… → pick the plugin/manifest.json from the clone above. (One-time.)
3. Run the Figbridge plugin on any frame, toggle Live bridge on. A green dot in the plugin header = connected to the local bridge. The footer shows the port.
4. In Claude: "What tools does figbridge expose?" — you should see 40+.

For any other MCP client (Cursor, Cline, VS Code, …), point it at the same binary: npx figbridge-mcp.

Via the MCP registry

Figbridge is also listed on the official Model Context Protocol registry as io.github.rudraptpsingh/figbridge. Clients that support the registry (Claude Desktop, Cursor, VS Code) can discover and install it without hand-editing config.

Troubleshooting

If Claude Desktop shows "Server disconnected" or port 7331 gets stuck, run:

npx figbridge-mcp doctor

It reaps orphan figbridge-mcp processes and reports which ports are alive. The bridge auto-falls-back to 7332..7340 if 7331 is held, and the plugin auto-probes the same range — so "port in use" won't block you. FIGBRIDGE_PORT=NNNN overrides the preferred starting port.

For long local agent sessions that drive Figma through POST /command, run a persistent bridge:

npx figbridge-mcp bridge

This starts only the local HTTP+SSE bridge and keeps it alive after stdin closes. Use this when a desktop/terminal tool starts short-lived commands but you want the Figma plugin connection to remain stable across multiple agent actions.

Updating

init writes a config that runs npx -y figbridge-mcp@latest, so every Claude Desktop launch pulls the current version — no action needed after a new release.

If you installed an older version (≤ 0.1.1) that baked an absolute path into your config, run this once to self-heal:

npx figbridge-mcp@latest update

Use npx figbridge-mcp init --pin if you'd rather lock to the currently installed copy (no auto-updates). npx figbridge-mcp --version prints the installed version.

MCP tools

Read (8) — get_current_selection · get_last_export · list_history · get_tokens · bridge_status · diff_since · list_pages · list_frames

Catalog (8) — list_screens · list_components · describe_screen · export_app_spec · export_all_pages · list_assets · select_node · export_node

Act & Handoff (5) — get_agent_bundle · clone_screen · recolor · apply_tokens · lint_ds

Browser (11) — preflight_import (risk check before import, including font download URLs), import_url (live URL → Figma frame; optional hybridSnapshot screenshot reference), import_responsive_set (desktop / tablet / mobile and optional light / dark theme captures), import_url_batch (bulk URL imports), screenshot_url, probe_url, fingerprint_url, audit_interactions (hover / focus discovery), verify_text_fidelity, measure_fidelity, audit_regression (baseline URL vs candidate URL frontend/UI regression audit)

Pillar 1 — Round-trip editing (2) — diff_to_source (per-text-node field diff between imported frame and live source) · generate_patch (turn the diff into a minimal HTML/JSX/etc patch against a source dir; style swaps get structured CSS-file hints)

Pillar 2 — Design intelligence audits (5) — audit_palette · audit_typography · audit_a11y (WCAG 2.x contrast, landmarks, alt text) · audit_whitespace (padding/gap rhythm, 4/8-grid conformance) · audit_mobile (multi-viewport responsive: horizontal scroll, overflow-x, sub-44px touch targets, sub-12px text)

Code Connect (3) — connect_components (seed / edit figbridge.connect.json: Figma component → code component + props) · get_code_connect (mapped component, props and a ready-to-paste JSX snippet for an instance) · lint_connect (CI gate: files, exports, props, literal values and Figma properties all still exist). See Code Connect without a Dev seat.

Pillar 3 — Match the mockup (3) — match_mockup (closed render → diff → refine loop: renders a running app and its target mockup, returns per-viewport visual scores plus a prioritized punch-list of copy / color / typography / spacing / elevation / icon / structure differences, a design-language style fingerprint, and — with sourceDir — the source file to edit for each item) · diff_specs (exact structured field-level diff between rendered URLs or captured spec JSON files) · map_components (index an app's source tree — data-testid / component → file, plus design tokens — so diffs name the file to change and the token a literal should become)

Component check against Figma. Screenshot one variant with any Figma exporter (plugin export_frame, or a Figma MCP screenshot), render the same component at its size with screenshot_url (width + height, fullPage: false), then diff_images both: you get a score, SSIM and a montage PNG. Serve a kit page that renders every variant (e.g. a ?kit route) and point match_mockup at it for whole-sheet runs.

Find the sizing rule in code. For a matched design HTML view and app state, pass the repo root as sourceDir to match_mockup or diff_specs. Deltas include viewport x/y and size. FigBridge resolves a data-testid plus data-state (or figbridge.connect.json component name) to a source file and shows the nearby JSX class. When the current dimension has one matching authored literal, codeChange gives the exact line, current rule, and suggested replacement; otherwise it leaves the edit unresolved. It also compares Figma-exported float variables in tokens.json with generated v2Tokens.json and reports tokenDrift. A screenshot by itself only supports the pixel comparison, and different photos or UI states cannot certify a whole-screen match.

The structured diff now keeps uniquely named siblings aligned when the app inserts a bar or panel, reports differing explicit data-state markers, and discloses omitted findings if the punch list reaches its cap. Comparable colour, geometry and style values are reported exactly by default; set tolerant: true to suppress small numeric and sub-JND colour differences. A missing or incomplete structured comparison cannot pass on pixel score alone. The two URLs still need matching content/state and an inspectable design export; FigBridge cannot infer Electron DOM fields or Figma token values from a PNG.

Native Electron state. diff_specs accepts appSpecPath in place of appUrl (and mockupSpecPath in place of mockupUrl). Capture the actual Electron Playwright page after the target state settles. Read mcp/src/dom-to-spec.js, then run await page.evaluate(extractor) and await page.evaluate(() => window.domToSpec({ rootSelector: 'body', viewport: 1440, embedImages: false })); save the result as JSON. Playwright evaluation works with a packaged renderer's script-src 'self' policy, while page.addScriptTag({ content: extractor }) can be blocked by it. Call diff_specs with a rendered Figma HTML mockupUrl, the native appSpecPath, and sourceDir to get exact paired values plus source locations. Both sides may instead be captured JSON files. Each side must provide exactly one URL or spec path. A Figma PNG supports pixel comparison only; exact Figma fields require its inspectable export, and a whole-screen verdict still requires matched content and state.

Different layer trees. Pass anchors to diff_specs when a native DOM tree does not mirror Figma's layer nesting. Each pair names a Figma node (mockupId from a structured Figma spec, or unique mockupName) and an app data-testid; fields can limit a pair to properties actually inspected, such as ['x','y','width','height']. FigBridge compares viewport geometry from both specs and reports exact per-anchor deltas with app source mapping. coverage shows requested, uniquely matched and missing/ambiguous anchors; any unmatched anchor prevents ok: true. This is a measured subset, so add anchors for every region whose properties you intend to certify. Example: { "name": "Action pill", "mockupId": "95:2956", "appTestid": "photo-toolbar-pill", "fields": ["x", "y", "width", "height"] }. A Figma spec node can carry _figmaId and the values read from its live node; a screenshot alone cannot supply them.

All audits are pure deterministic measurement — no model calls. They return numeric scores and structured issue lists ready to feed back into a planning loop. audit_regression can be used as a local/CI gate before shipping a UI change: it compares screenshots, missing visible text, responsive issue deltas, and CSS-feature drift across desktop/tablet/mobile.

Chrome current-tab capture

The chrome-extension/ folder contains an unpacked MV3 extension for authenticated pages:

1. Open chrome://extensions, enable Developer mode, and load the chrome-extension/ folder unpacked.
2. Start Figbridge MCP and open the Figbridge Figma plugin with Live bridge enabled.
3. Use the extension popup to send the visible viewport, opt into full-page DOM capture, pick a page element, or include a viewport screenshot reference beneath editable layers.

Browser captures can group each website or project into its own Figma page, for example Chrome Capture - Raycast or Chrome Capture - Localhost, so separate projects stay navigable inside one open Figma file.

The extension only posts to 127.0.0.1:7331..7340; it does not send page data to a cloud service.

Code Connect without a Dev seat

Figma Code Connect needs a Dev or Full seat on an Organization or Enterprise plan. Figbridge does the same job locally, for free, from a map you commit next to your code.

1. The map — figbridge.connect.json in your repo. One entry per Figma component:

For UI kits that place separate variant components inside a display frame, keep that frame as figma.nodeId and list the exact component IDs in figma.variantNodeIds. FigBridge reads an instance's main component ID and resolves the matching variant, including in structured diffs; it does not infer ownership from a similar name.

{
  "version": 1,
  "fileKey": "WwO2ckSkwjOeusmEQwWrus",
  "imports": { "src/": "@/" },
  "components": [{
    "figma": { "fileKey": "WwO2ckSkwjOeusmEQwWrus", "nodeId": "59:944", "name": "Button",
               "properties": { "Style": { "type": "VARIANT", "options": ["Primary", "Secondary", "Quiet", "Destructive"] } } },
    "code":  { "source": "src/components/primitives/Button.tsx", "export": "Button",
               "import": "import { Button } from '@/components/primitives/Button'" },
    "props": {
      "variant":  { "figma": "Style", "type": "enum", "values": { "Primary": "primary", "Secondary": "secondary" } },
      "loading":  { "figma": "State", "type": "enum", "values": { "Loading": true } },
      "icon":     { "figma": "Icon", "type": "instance", "as": "component", "when": "Show icon", "importFrom": "lucide-react" },
      "children": { "figma": "Label", "type": "text" },
      "testId":   { "type": "static", "expr": "testId" }
    }
  }]
}

Prop type	Code Connect twin	Maps
enum	figma.enum	a variant value → a prop value (values; unmapped values drop the prop). Several rows can read one variant, e.g. State=Loading → loading, State=Disabled → disabled.
boolean	figma.boolean	a boolean property → true / omitted, or through values
text	figma.string	a text property → a string prop, or JSX children
instance	figma.instance	an instance-swap → {Download} (as: "component") or {<Download />}; importFrom adds the import
static	—	a fixed value, or an expr placeholder for props Figma has no property for

when gates any prop on a Figma boolean ("Show icon"). Figma names are matched without their #12:34 suffix. An optional example template takes {{props}}, {{children}}, {{propName}} and raw {{figma.Label}} values, for components whose code shape differs from the Figma one (a segment in Figma, a Segmented with options in code).

2. Seed it. connect_components writes entries for you: the component description's Code: src/…tsx line, its Test id: (through the map_components index) or its name picks the file and export; props come from the TSX, and variant values are matched against each prop's string-literal union. Hand edits are kept unless you pass overwrite.

# from the open Figma file (plugin running), with @/ imports
npx figbridge-mcp call connect_components '{"fromPlugin": true, "imports": "{\"src/\":\"@/\"}"}'

3. Use it. Select an instance in Figma and open the plugin's Code tab: the mapped component, its current props and a ready-to-paste snippet, like Dev Mode's panel. Agents call get_code_connect (a nodeId, the current selection, or an offline node description):

// get_code_connect on a Button instance (Style=Secondary, Show icon, Icon=download, Label "Export 186")
import { Button } from '@/components/primitives/Button'
import { Download } from 'lucide-react'

<Button icon={Download} variant="secondary" size="m" testId={testId}>Export 186</Button>

4. Keep it true. lint_connect fails when a source file, export or prop is gone, when a mapped value left the prop's literal union (including unions imported from another module, or (typeof STATES)[number]), or when a mapped Figma property or variant value is no longer in the entry's Figma snapshot. Put it in CI:

npx figbridge-mcp call lint_connect '{}'    # exit 1 when the map has rotted

Call tools from a shell or CI

Every tool runs without an MCP client:

npx figbridge-mcp tools                                   # list tools
npx figbridge-mcp call map_components '{"sourceDir":"src"}'
npx figbridge-mcp call get_code_connect @args.json        # args from a file
echo '{"url":"http://localhost:5173"}' | npx figbridge-mcp call audit_mobile -

It prints the tool's JSON and exits 1 when the result is ok: false. When a Figbridge bridge is already running (Claude, or figbridge-mcp bridge), plugin tools go through it to the open Figma plugin.

The agent handoff bundle

get_agent_bundle is the differentiator. One call returns a zip:

DESIGN.md          palette · rhythm · do/don't
hierarchy.md       indented tree with deterministic slugs
components.json    variants + props schema
tokens.json        DTCG-shaped
tokens.css         :root + per-mode blocks
flow.mmd           Figma prototype → Mermaid graph
responsive.md      mobile/tablet/desktop merged
ISSUES.md          a11y audit the agent shouldn't repeat
CHANGES.md         surgical diff since last bundle
AGENTS.md          "when you see slug X, import Y"
manifest.json      sha-256 + token counts, stable order for prompt cache
screenshots/       1:1 paired with hierarchy slugs

Three budget tiers (small 8k / medium 32k / large 128k tokens). Slugs are deterministic — rename a node, the slug stays — so CHANGES.md is a real surgical diff instead of a whole-file retranslation.

The closed loop: URL → Figma → diff → patch

Figbridge is the first MCP-native tool that closes the loop in both directions.

                 import_url                      diff_to_source
   ┌──────────┐  ──────────▶  ┌──────────┐  ──────────▶  ┌──────────┐
   │  Source  │                │  Figma   │                │  changes │
   │  (URL,   │                │  frame   │                │   list   │
   │   repo)  │ ◀──────────    │ (edited) │                └────┬─────┘
   └──────────┘  generate_patch└──────────┘                     │
                                                                ▼
                                                         apply or review

1. import_url pulls a live URL into a Figma page (multi-page aware via pageName; section-aware via rootSelector).
2. Audit the result with the five Pillar 2 tools to find palette drift, contrast failures, off-grid spacing, mobile breakage. Use audit_regression to compare production/staging against a local candidate and catch UI/UX regressions before updating Figma or shipping code.
3. The designer edits the frame in Figma.
4. diff_to_source reports exactly which text-node fields diverged from the source URL — characters / fontSize / fontFamily / color / presence.
5. generate_patch turns the diff into a minimal before/after edit list against a local source directory. Style swaps get structured hints (token vs literal) instead of blind text replacements.

No LLM rewrites in the loop. Every step is deterministic and idempotent.

Output formats

Format	Shape
HTML + CSS	Self-contained document, positional layout preserving pixel fidelity.
Tailwind	Same tree with Tailwind arbitrary-value utilities (w-[120px], bg-[#ff7a29]) + CDN script.
Design tokens	DTCG JSON tree, :root { --var: value } CSS, Tailwind config fragment. Reads Figma Variables + local paint styles.

Architecture

• Plugin main thread (plugin/code.js) — reads the node tree, computes HTML/CSS/Tailwind/tokens deterministically. ES2017-safe (no spread / ?? / ?.) for the Figma sandbox.
• Plugin UI (plugin/ui.html) — cream/ink/rust theme, Figma-native layer navigator, inline Commands panel with a Run button per tool.
• MCP server (mcp/src/) — stdio MCP via @modelcontextprotocol/sdk, sibling HTTP + SSE server on :7331 for plugin pushes and bidirectional commands. State in-memory + persisted to ~/.figbridge/last.json.

What Figbridge does not do

• No reach into Figma without the desktop app + plugin open. No REST API, no PAT.
• No AI code rewrites. It's a deterministic tree walker.
• No publishing to Figma or to the cloud.

Development

cd mcp && npm install && npm test        # integration smoke test
node test-agent/run.js                   # 130 unit tests on the render pipeline
node test/scenarios.mjs                  # 54 real-world scenario checks
node test/real-figma.mjs                 # 43 checks against a parsed real .fig
node test/tools-all.mjs                  # full MCP tool surface + e2e
node test/code-connect.mjs               # Code Connect: props reader, suggest, snippets, lint
node test/cli.mjs                        # figbridge-mcp call / tools
node --check plugin/code.js              # plugin syntax check

Links

• Landing page: https://rudraptpsingh.github.io/figbridge/
• npm: https://www.npmjs.com/package/figbridge-mcp

License

MIT © Rudra Pratap Singh