Enables AI agents to bidirectional communicate with Figma by converting designs into framework-aware code and authoring canvas elements directly.
Also known as awdr74100/figwright, @figwright/mcp
- Stars
- 1,408
- Tools
- 135
- Downloads, 30 days
- 7,934
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Figwright MCP?
Figwright enables AI agents to bidirectional communicate with Figma by converting designs into framework-aware code and authoring canvas elements directly. It exposes 135 tools, such as ping, get_selection, get_document.
Summary generated from the project's README
About Figwright MCP server
Figwright provides a bidirectional connection between AI agents and Figma, allowing for a two-way workflow that goes beyond simple design inspection. It enables coding agents to transform Figma selections into framework-aware code that reuses your existing components, tokens, and icons. Simultaneously, it allows agents to author and edit the Figma canvas directly, creating everything from simple text and shapes to complex auto-layouts, variables, and full screens.
The system operates locally on your machine using a WebSocket relay between an MCP server and a Figma plugin. This setup ensures your designs are never sent to external servers. It is designed to work with MCP clients like Claude Code or Cursor and requires Node.js 20.19+ or 22.12+. Unlike official Dev Mode solutions, this server functions on the free Figma tier and provides 135 tools for reading and writing design data.
Developers can use specific skills to orchestrate these tools, such as figma-codegen for implementation or figma-build for design creation. The server is run via npx, making it easy to integrate into existing development environments without a global installation.
What you can do with it
- 1Convert designs to codeAn AI agent can transform a selected Figma frame into a functional React component using your project's specific styling system.
- 2Generate Figma designs from textYou can instruct an agent to build a specific UI section, such as a pricing area, directly on the Figma canvas.
- 3Automate canvas editingAn agent can manipulate various canvas elements including auto-layout, styles, and even complex vector paths via Figma Draw.
Written from the project's README. Every use case is checked against a quote from it.
How to install Figwright MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Figwright MCP in Claude Code
$ claude mcp add figwright -- npx -y @figwright/mcpInstall Figwright MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"figwright": {
"command": "npx",
"args": [
"-y",
"@figwright/mcp"
]
}
}
}Install Figwright MCP in VS Code
.vscode/mcp.json
{
"servers": {
"figwright": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@figwright/mcp"
]
}
}
}Install Figwright MCP in VS Code CLI
$ code --add-mcp '{"name":"figwright","type":"stdio","command":"npx","args":["-y","@figwright/mcp"]}'Install Figwright MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"figwright": {
"command": "npx",
"args": [
"-y",
"@figwright/mcp"
]
}
}
}Install Figwright MCP in Codex
$ codex mcp add figwright -- npx -y @figwright/mcpInstall Figwright MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.figwright] command = "npx" args = ["-y", "@figwright/mcp"]
Install Figwright MCP in Gemini CLI
$ gemini mcp add -s user figwright npx -- -y @figwright/mcpInstall Figwright MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"figwright": {
"command": "npx",
"args": [
"-y",
"@figwright/mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @figwright/mcp 0.7.0 in an isolated container with no network and no keys. It answered and listed 135 tools.
Figwright MCP tools 135
Read from the server with tools/listpingRead-onlyHealth check. Returns server info plus, when a plugin is connected, end-to-end info from the Figma sandbox. On a follower it also reports the leader’s version and build, and warns (versionSkew / buildSkew) when a stale older server still owns the plugin. sessions.all names each connected file as of its last activity, so a file whose tab has not been in front since it connected shows fileName: null — use list_files, which asks each plugin directly, when you need the names (and use_file to claim one).
get_selectionRead-onlyReturn the current selection on the active Figma page: { pageId, pageName, nodes }, where each node is a full flat serialization — geometry, fills/strokes/effects, text properties, style/variable ids, mainComponent — without children. The zero-argument "what is the user looking at" call: use it to identify the selected node ids (and page), then walk deeper with get_design_context or get_node. An empty nodes array means nothing is selected.
get_documentRead-onlyReturn the full node tree (recursive children) of the active Figma page, with base geometry, rotation, opacity, cornerRadius, and fills enrichment.
get_nodeRead-onlyReturn one node by id with its full recursive subtree at maximum fidelity — every serialized field (geometry, paints, effects, auto-layout, text with per-run segments, style/variable ids, mainComponent), no depth limit, no deduplication. Best for inspecting a single component or a node you are about to modify; for exploring or grounding anything large, prefer get_design_context (depth-limited, deduped, tokens resolved to names). Returns { node }, null when the id matches nothing.
get_nodes_infoRead-onlyReturn multiple Figma nodes by id. Output preserves input order; missing ids slot null.
get_vectorRead-onlyRead a vector’s geometry — what set_vector takes back: vectorPaths (SVG path data per subpath, measured from the layer’s top-left) and vectorNetwork (vertices, the segments joining them with their Bézier tangents, the regions that fill, and per-vertex caps, joins and corner radii), plus handleMirroring. For a VECTOR or text on a path (TEXT_PATH, read-only); a rectangle, ellipse, polygon, star or line has no editable path — flatten_nodes it into a VECTOR first. Not part of get_node / get_design_context, which stay small; codegen exports vector art rather than rebuilding it from its points. Returns { nodeId, type, width, height, vectorPaths, vectorNetwork, handleMirroring }.
get_metadataRead-onlyReturn file metadata: fileName, current page, all page references, and which editor the file is open in (editorType / mode) — "dev" is read-only and "figjam" has no components, variables or styles — and colorProfile, the space its colours are stored in (SRGB / DISPLAY_P3 / LEGACY): in a DISPLAY_P3 file every r/g/b is P3, so a colour written from code takes space: "SRGB".
get_pagesRead-onlyReturn every page in the active Figma file as { id, name, flows }. flows lists the prototype flows Presentation view offers on that page, as { nodeId, name } in order: nodeId is the flow's starting frame, and the first flow is the one Presentation view opens by default. An empty flows means the page has none a plugin can see (a flow whose frame is hidden, grouped or nested is invisible until that frame is visible and top-level again). Change flows with update_flows.
search_nodesRead-onlySearch the node tree by case-insensitive name substring and/or exact node type. At least one of name or type is required. Scope to a subtree with root (a node id); defaults to the current page. Returns a flat array of matching nodes.
scan_text_nodesRead-onlyReturn every TEXT node within a subtree, each with its characters / fontSize / fontName — text set along a path (TEXT_PATH) included. Scope with root (a node id); defaults to the current page.
scan_nodes_by_typesRead-onlyReturn a flat list of every node whose type is in `types`, searched recursively through a subtree scoped by `root` (a node id) or the current page by default. Use this to collect nodes by kind (e.g. all TEXT or COMPONENT nodes); to search by name or characters use search_nodes, and for a styled tree snapshot use get_design_context. Returns a flat array of matching nodes.
get_stylesRead-onlyReturn the document's local styles grouped as { paints, texts, effects, grids }. Paint styles carry their paints; text styles carry fontName / fontSize / lineHeight / letterSpacing / textWrapStyle; effect styles carry their effects; grid styles carry their layout grids. Any value the designer bound to a variable carries a `boundVariables` map ({ field: variableId }) on the object that owns it — the individual paint, gradient stop, effect or layout grid, and the text style itself for typography. A bound value is a reference, not a literal: emit the token, not the resolved colour/number sitting next to it. `variables` maps every referenced id to its { name, type, codeSyntax? } (ids stay the key because variable names collide across collections); it is omitted when nothing in the document is bound. This lists local styles, not all shared styles used by imported instances. To use a published style in another file, pass its key to import_style in that target file and use the returned styleId. A result led by colorProfile: "DISPLAY_P3" comes from a Display P3 file: its colours are P3, so emit one as color(display-p3 r g b), not the plain hex.
Show all 135 toolsShow fewer tools
get_variable_defsRead-onlyReturn the document's local variables as { collections, variables }. Each collection lists its modes and defaultModeId; each variable lists its resolvedType and valuesByMode (primitives, RGBA colors, { type: "VARIABLE_ALIAS", id } references to other variables, a composed color { color, opacity } pairing a color with a separate opacity where either half may be an alias, or — for an EASING variable — an easing curve { type, easingFunctionCubicBezier?, easingFunctionSpring? }). A variable also carries scopes when the designer narrowed where Figma offers it (e.g. ["CORNER_RADIUS"]) — authoritative intent about what the token is for; absent means every scope. This lists local definitions, not all shared library references. To use a published variable in another file, pass its key to import_variable in that target file and use the returned variableId. A result led by colorProfile: "DISPLAY_P3" comes from a Display P3 file: its COLOR values are P3, so emit one as color(display-p3 r g b), not the plain hex.
get_local_componentsRead-onlyReturn the components and component sets within a node subtree (or the current selection) as { components, componentSets }. Scans a subtree, not the whole document — pass nodeId, or select the frames to scan. A document root is not supported; use get_pages and scan each page by nodeId. Components carry their variantProperties (when part of a set); component sets carry their variantGroupProperties (available values per axis) and the ids of their variant components.
get_component_apiRead-onlyReturn a component's full property API — the prop contract behind its instances. Pass a COMPONENT, COMPONENT_SET, or INSTANCE id (an instance resolves to its main component / set). Returns { id, name, type, properties } where properties maps each property name to { type (VARIANT|BOOLEAN|TEXT|INSTANCE_SWAP|SLOT), defaultValue, variantOptions?, preferredValues?, description? }. Property names come back verbatim for set_instance_properties: VARIANT by bare name (e.g. "Size"), BOOLEAN/TEXT/INSTANCE_SWAP suffixed with #id (e.g. "Label#2:0"). Unlike get_local_components (a subtree inventory), this targets one component and is safe on large files.
get_viewportRead-onlyReturn the current page viewport as { center, zoom, bounds } — the on-screen center point, zoom level (1.0 = 100%), and visible bounds rect.
get_fontsRead-onlyReturn every font used on the current page as { fonts: [{ fontName, count }] }, sorted by usage frequency (descending). Mixed-font text contributes one count per styled segment. fontName carries variationSettings for a variable font — two rows sharing a family + style but differing there are different weights, not duplicates. A sibling variationAxes { family: ["wght", "slnt", ...] } lists the OpenType axes each variable family exposes: those are the tags the write tools accept in fontName.variationSettings. A family missing from it is static.
get_annotationsRead-onlyReturn Dev Mode annotations as { annotations: [{ nodeId, nodeName, annotations }] }. With nodeId, returns that node's annotations; without it, scans the current page for all annotated nodes.
get_reactionsRead-onlyReturn the prototype reactions on a node as { nodeId, reactions: [{ trigger, actions }] }. Each reaction pairs an interaction trigger (click, hover, key press, timeout…) with its actions — navigate to a node, open an overlay, open a URL, back/close, set a variable or variable mode, control media, or a conditional block. Every field Figma holds is returned, including each action's transition and easing, so the output can be handed back to set_reactions unchanged to reproduce the reactions exactly.
get_motion_stylesRead-onlyList the file's available Figma Motion animation-style presets — the templates you apply with apply_animation_style. Returns { styles: [{ styleId, name, description?, props? }] }; the styleId is what apply_animation_style takes and props lists a preset’s tunable keys. Motion is a beta feature: this read works wherever the plugin API exposes it; applying presets needs the Figma Design editor.
get_node_motionRead-onlyRead one node's Figma Motion (animation) state: applied animation styles, all keyframe animations, manual keyframe tracks, and the timelines it belongs to. Call it before editing to discover styleIds / timelineIds and existing keyframes; for every animated layer under a frame use get_motion_context. Returns { nodeId, motion: { animationStyles, animations, manualKeyframeTracks, timelines } }, raw as Figma returns it, with motion: null when the node supports no Motion. Also returns playheadPosition — the editor's Motion playhead in seconds, present only with an active timeline. Use it as a keyframe timelinePosition when the user means "here", i.e. wherever they have scrubbed to.
get_motion_contextRead-onlyList every Figma Motion (animation) source under a node: the node and its whole subtree, hidden layers and instance children included, never deduped (each instance under its own instance-qualified id). Call it once per root you implement — only coverage.status "complete" with no nodes means nothing there animates; a missing motion summary in get_design_context does not. Returns { rootNodeId, coverage, diagnostics?, nodes: [{ nodeId, parentId, name, type, motion }] } for each node with an applied animation style or a keyframe; motion is get_node_motion’s raw read, except that manualKeyframeTracks keeps only the tracks animations does not already play as stored (a variable-bound easing). A call is bounded: "partial" coverage names why and lists pendingNodeIds, disjoint subtree roots to call it on next. Nodes on one timeline id share a clock. Loop, trigger and pivot are not in the data — never fill them in as if Figma had.
list_filesRead-onlyReturn every Figma file that currently has the Figwright plugin open, as { files: [{ sessionId, fileName, currentPage, pluginVersion, routed, bound, duplicateName?, error? }] }. More than one entry means more than one file is reachable, and calls follow whichever one the user last touched (routed: true) — which changes under you when they switch tabs. Claim one with use_file so this agent stays in it. bound marks the file this agent has claimed. duplicateName marks entries sharing a name (Figma allows it; "x (Copy)" is the usual way), for which use_file needs the sessionId rather than the name. fileKey is always null: only private-org plugins can read it.
use_fileRead-onlyClaim one open Figma file for this agent, so its tool calls stop following whichever file the user last touched. Call this when list_files or ping shows more than one file connected — without it two agents working on two files both track the foreground tab, and the one that is not in front silently reads and writes the wrong file. Pass fileName (refused when two open files share it) or sessionId (always unambiguous; take it from list_files). release: true drops the claim and goes back to following the foreground file. The claim lasts for this server process only, so it never affects another agent, and it survives the user closing and reopening the plugin panel (the file is re-found by name). Returns the claim plus the same file list as list_files.
get_design_contextRead-onlyGet a depth-limited, token-efficient node tree — the main design-grounding read; prefer it over get_document / get_node for anything large. Starts from nodeId (a pasted Figma URL also works), else the current selection; errors when neither is available. detail: minimal (id/name/type) / compact (+ geometry) / full (+ styling, layout, text and design-system tokens resolved to names plus a deduped globalVars style table). Defaults to full with dedupeComponents true — the code-generation view; pass detail: compact explicitly for a cheap structure scan. An over-budget full result degrades gracefully, always with a leading note saying which shape you got: a small overshoot returns the same tree with LAYOUT intact and only appearance dropped (every frame keeps its flex/grid mode, padding, gap and alignment, each node its sizing/constraints, each text its characters — enough to build correct containers, then re-ground per section for colour and type); anything bigger returns a sectionPlan, which is the BEST outcome and not the worst — each section grounded on its own comes back at full detail with layout AND colour AND type. Layout-only and geometry-only views appear only for a subtree with nothing left to split into. Whatever shape comes back, build layout from each frame's own layout object — never reconstruct spacing from child x/y as margins or absolute offsets. depth limits child levels (omit or 0 = unlimited; cut nodes are flagged truncated). dedupeComponents collapses repeated instances of an already-expanded main component (flagged deduped); a deduped instance still carries textOverrides ({ name, characters } — the visible text it actually renders) and propertyOverrides (its per-instance visual diffs), so per-instance content survives without re-expanding the collapsed subtree. A node carrying variableModes ({ color: "Dark" }) renders in that variable mode: its values are that mode's but its token names are the default's, so keep the token refs and scope the subtree in the project's theme mechanism (a root lists the modes it inherits too). A result led by colorProfile: "DISPLAY_P3" comes from a Display P3 file, where every hex and r/g/b is a P3 colour: emit a raw one as color(display-p3 r g b), not the plain hex, which renders visibly duller. A Figma effect radius is not CSS: emit a blur as blur(radius × 0.43) and a shadow blur as radius × 0.85 in box-shadow; a progressive blur (blurType PROGRESSIVE) carries ready cssLayers to emit as given, and a BACKGROUND_BLUR with drawn: false paints nothing in Figma, so emit no backdrop-filter for it. A tree too large to return whole comes back as a sectionPlan instead ({ sections: [{ nodeId, name, nodes, … }] } + a note): do not retry unscoped — call again per section nodeId at detail full and build section by section. On a full result, raw color values that exactly equal a project design token are annotated in projectTokens ({ '#6266F0': { ref, name, matchedBy: ['value'] } }, or { matchedBy, candidates: [...] } when several tokens share the value). An entry carrying `from` is a SCSS variable whose ref does NOT resolve on its own — the file you write must @use it first, and `from` is REPO-relative while Sass resolves @use against the importing file, so re-resolve it from where you are writing (src/components/x.scss imports '../styles/tokens'). `as *` keeps the ref as given, a namespaced @use requires prefixing it; emitting the ref without the import is a compile error. matchedBy: ['value'] marks every entry as name-blind value-equality evidence — a hypothesis to verify, not a resolved binding: emit the ref only when the token fits the context semantically, keep the raw value otherwise, and let a bound Figma variable win over a raw-value match.
get_screenshotRead-onlyExport nodes as images the model can see, one image block per node: { images: [{ nodeId, format, base64, width?, height?, scale?, recovered?, empty? }] }. format is PNG (default) / JPG / SVG. scale applies to raster formats; when omitted, each node is auto-fitted to a legible size (long edge into ~512–2576px: oversized frames scale down, tiny icons scale up ≤4x) — pass an explicit scale to force one. An explicit scale is capped so the long edge stays within 2576px, the most a vision model resolves: past that the model sees the identical pixels, so the extra bytes buy no detail — use save_screenshots when you need a full-res file on disk. Past 20 nodes in one call the whole batch drops to a 2000px long edge, which is what providers require of many-image requests; ask for fewer nodes when you need the detail. A batch is also capped by total size, not just resolution: a full-page frame is ~2.4MB, so 3–4 of them fill one response. Past that the remaining nodes come back labelled but not inlined, with a note naming them — re-request those ids in a follow-up call, or use save_screenshots for many nodes at once. Each raster label reports the exported width×height px and the scale, the anchor for mapping raster px back to design px. base64 is null for missing or non-exportable nodes. Nodes that are fully clipped or off-canvas (carousels, masks, off-screen states) are auto-recovered at their intrinsic bounds and flagged recovered:true. empty:true means the node genuinely renders nothing even unclipped (hidden / no content) so the export is blank.
save_screenshotsRead-onlyExport nodes and write them to disk under outDir: { saved: [{ nodeId, format, path, recovered?, empty? }] }. format is PNG (default) / JPG / SVG; scale applies to raster formats (default 1). path is null for missing or non-exportable nodes. Nodes that are fully clipped or off-canvas (e.g. a carousel's edge items) are auto-recovered at their intrinsic bounds and flagged recovered:true. empty:true means the node genuinely renders nothing even unclipped (hidden / no content) so the file is blank. Files are named after a sanitized node id.
save_image_fillsRead-onlyExtract the ORIGINAL image bytes behind each node's IMAGE fills and write them to disk under outDir — the source asset exactly as uploaded (no mask, clip, crop, scale, or effects applied), unlike save_screenshots / get_screenshot which re-render the composited node. Returns { nodes: [{ nodeId, images: [{ index, imageHash, format, path, width?, height?, scaleMode? }], mixed? }] }. index is the fill position in node.fills; width/height are the image intrinsic size; scaleMode is how the fill is displayed (FILL / FIT / CROP / TILE); format is sniffed from the bytes (PNG / JPG / GIF / WEBP, or BIN if unrecognized). Identical images (same imageHash reused across nodes) are fetched once and share one file named by hash. path is null when the fill image can't be resolved; images:[] means the node has no image fill; mixed:true means the node's fills are per-text-range and were not enumerated. For a rendered/composited raster use save_screenshots; for a vector node use export_pdf.
export_pdfRead-onlyExport a node (or the current page) to a single-page vector PDF file on disk. Figma's plugin API renders one PDF page per node and cannot paginate a page into one-frame-per-page or merge multiple nodes into a multi-page file. Pass a frame / section / component id for a vector PDF of that node; omit nodeId for the current page (large pages can be slow). For raster output (PNG/JPG) use save_screenshots instead. Returns { nodeId, path, empty? }; path is null if the target is missing or not exportable, and empty:true means it rendered a blank PDF.
export_videoRead-onlyExport an animated Figma top-level frame to an MP4 / WebM / GIF file on disk. Pass any node in the frame (or the frame itself) — its enclosing top-level frame is encoded across the animation's duration. Requires the Figma Design editor and a frame with animated content (Smart Animate / Motion keyframes); a static frame, a nested frame, or FigJam / Dev Mode yields path:null with a reason (and, when reason is `failed`, Figma’s own message in error). Encoding is a heavy render — call it on its own, not concurrently with other tool calls, or the render can fail. Returns { nodeId, format, path, reason?, error? }.
analyze_projectRead-onlyDetect the local project profile (framework, language, styling system, component file extensions, svg handling) by reading manifests and config — the foundation scan_components / component_map switch on. Optional standalone probe: those tools run detection internally and return the same profile, so call this only to inspect detection in isolation (no Figma, no file scan). Runs on the server filesystem. rootDir defaults to the server cwd. Detects Tailwind v3 (config file) and v4 (CSS-first @import/@theme) and reports tailwindVersion, and UnoCSS (uno.config.* / a @unocss package) as styling.system 'unocss'; detects svg loader (svgr / vite-svg-loader / …) → svg.mode component vs url + an import hint. Also reads the project's own preprocessor stylesheets (.scss/.sass/.less/.styl/.pcss, and SFC <style lang="scss"> blocks) to report styling.classNaming — how it spells a compound BEM-style class: 'ampersand' (.card { &__title {} }) or 'flat' (.card__title {}). Match it. When it is absent the project has no such habit: declare class names flat and in full, so the class the markup carries is findable by searching for it — a name assembled from & exists only after compilation. Never "flatten" by nesting the full name (.card { .card__title {} }): that compiles to the descendant selector .card .card__title, adding specificity and breaking the moment the element is not a DOM descendant.
scan_componentsRead-onlyScan the local project for existing UI components so they can be reused instead of regenerated. Runs on the server filesystem, not in Figma. Identifies components by AST signature (exported, PascalCase, function-ish) rather than by folder layout, so any structure works. React (.tsx/.jsx) is parsed for name + props; Vue/Svelte derive the name from the file and parse props from the <script> block (defineProps / export let / $props). extensions defaults to the detected profile's; rootDir defaults to the server cwd. Returns { components, profile }.
component_mapRead-onlyMap the Figma component instances in a selection/subtree to existing local code components, so they can be reused instead of regenerated. Joins the grounded Figma component names (and their variant axes) against an AST scan of the project; an explicit docs/figma-component-map.md row (FigmaName | code/path) overrides the fuzzy match — this file is the durable record a verified mapping is written back to, so the next run reuses it instead of re-guessing. A row whose target no longer resolves (deleted/renamed) is reported in staleOverrides and degrades to the fuzzy result rather than a phantom import. Each distinct component is mapped once with all its instance ids. A mapped candidate also reports matchedProps (Figma axes the component already has) and unmatchedProps (axes it lacks → component-extension TODOs). Returns { mappings (candidate + confidence + status high/medium/low/unmapped), unmapped, staleOverrides, profile }.
token_mapRead-onlyMap the document's Figma variables — and its shared paint styles (single solid color styles, the design-token mechanism of pre-variables files; such rows carry source: 'style') — to the project's design tokens, so generated code references existing tokens instead of hard-coded values. Joins the grounded Figma names + values against the project's design tokens — parsed from its CSS (Tailwind v4 @theme or :root custom properties), on a Tailwind v3 or UnoCSS project from the theme scales in its JS/TS config (whose tokens have no var() form: reference them by candidate.ref, the utility base), and on a SCSS project from its $variables. A SCSS candidate carries candidate.from, the file declaring it: candidate.ref does NOT resolve on its own — the consuming file must @use that file. from is REPO-relative and Sass resolves @use against the importing file, so re-resolve it from the file being written (from src/components/card.scss it is '../styles/tokens', never the repo-relative path verbatim). `as *` keeps the ref as written; a namespaced @use requires prefixing the ref with that namespace. Emitting the ref without the import is a compile error. The match is name-based with an exact color value-match as confirmation. When several project tokens share the exact same color value and the name cannot pick one, the mapping is capped below 'high' and candidate.ambiguousWith lists the other same-value tokens — verify that pick semantically instead of trusting it blindly. When the rival is the SAME name in another file (a SCSS layout with per-component variable files), candidate.ambiguousFrom lists those files instead: the ref is right and the declaring file is the open question, so confirm which one the design means before writing its @use. On a project with a utility framework (Tailwind or UnoCSS) a variable that hits a framework built-in scale (spacing/N, line-height/N, weight/*) is reported as status 'framework-builtin' with { builtin: { scale, step } } rather than unmapped — it has no @theme token but the utility (p-4 / gap-4, leading-7, font-bold) is still usable. A variable in a multi-mode collection whose value differs per mode (a Light/Dark theme) carries figmaModes (mode name → value per theme; figmaValue is only the default mode), and the result lists themedCollections — keep such tokens theme-aware (a token that itself switches per theme, or the non-default values wired through the project's dark-mode mechanism), never just the default-mode literal. tokenSource overrides the detected styling config; rootDir defaults to the server cwd. A JS-config theme built at runtime (spread from an imported palette, computed, or living in a preset) is only partly readable — the note says how much was skipped or whether the theme was reachable at all, and the project CSS is pooled alongside it either way. An explicit docs/figma-token-map.md row (FigmaName | ref) overrides the fuzzy join with matchedBy ["map-file"] — this file is the durable record a verified token mapping is written back to, so the next run reuses it instead of re-guessing an ambiguous or value-only match. A row whose ref no longer resolves to a project token is reported in staleOverrides and degrades to the normal join. Returns { mappings (candidate + confidence + status + matchedBy + builtin), unmapped, staleOverrides, tokenSource, profile }, led by colorProfile: "DISPLAY_P3" in a Display P3 file — its Figma values are P3 colours there, so a value match is equal numbers in different spaces: keep the token, but the design renders more saturated than it.
icon_mapRead-onlyMap the Figma icon nodes in a selection/subtree to the project's existing `.svg` files, so codegen reuses the designer-curated asset instead of re-exporting a duplicate. Joins the grounded Figma icon names against the repo svg files (gitignore-aware scan), name-based and near-exact (a wrong icon is a silent visual bug, so unsure matches fall through to a fresh export rather than mis-reuse). Each match reports the file path, the color contract read from the file (currentColor / fixed / multi-color), and how to recolor it in this project (currentColor → text-{token}, gated on the svg mode since currentColor dies through an <img>). It does not fabricate the import line — compose it from the file path and profile.svg (importHint gives the loader form: svgr `?react` / vite-svg-loader `?component` / `{ ReactComponent }` / url `<img>`), mirroring the project's existing imports for the alias/relative path. Unmatched icons are returned in `unmapped`; `iconLibraries` lists any installed icon component library (lucide / heroicons / iconify) as the alternative to a fresh export. rootDir defaults to the server cwd. Returns { mappings, unmapped, iconLibraries, profile }.
design_diffRead-onlyDiff a Figma node against a saved baseline of itself, so after a design changes you edit only the affected code instead of regenerating. First call on a node saves a baseline (its get_design_context, full detail) under .figwright/snapshots/ and returns status 'baseline-created'; a later call returns status 'diff' with the per-node, per-property changes (added / removed / changed nodes; fills, layout/padding, text, token bindings — resolved to readable values, not opaque ids) or 'no-changes'. Pass update:true to accept the current design as the new baseline (re-snapshot). nodeId defaults to the selection; rootDir defaults to the server cwd. The baseline is a plain file the tool writes under the project — committing it (so teammates share the baseline) or gitignoring it is your call; the tool never changes git. It never mutates Figma. Scope by a component / section nodeId, the same unit codegen works on.
set_fillsActionSet a node's fills. SOLID: { type:'SOLID', color:{r,g,b} } (0–1). Gradient: { type:'GRADIENT_LINEAR'|…, gradientStops:[{position,color:{r,g,b,a}}], gradientTransform } (round-trips get_node output). A SOLID paint may carry boundVariables ({ color: variableId }) and a gradient stop its own — the paint then tracks that variable instead of the literal. Channels are in the document's colour space; a colour taken from code adds space: 'SRGB' so a Display P3 file shows it as the code does. PATTERN tiles another layer across the fill: { type:'PATTERN', sourceNodeId, tileType, scalingFactor, spacing, horizontalAlignment, verticalAlignment } (round-trips get_node output; omitted fields take the defaults). Images go in with set_image_fill. Returns { ok, nodeId }.
set_textActionReplace the entire text content of a TEXT node or of text on a path (TEXT_PATH); the plugin loads the node's current fonts first. Styled runs the old and new text share whole at the start or end keep their styling, so a typo fix leaves a bold word or a link alone; the rewritten span takes the style of the text it replaces. For formatting (font, size, color, spacing) use set_text_properties, and to substitute text across many nodes use find_replace_text. Returns { ok, nodeId }.
set_text_propertiesActionSet a TEXT node's (or text on a path's) typography and layout/overflow properties. Typography: fontName ({ family, style?, variationSettings? } — variationSettings carries a variable font's axis values, e.g. { wght: 650 }), fontSize, lineHeight, letterSpacing, textCase, textDecoration, paragraphSpacing / paragraphIndent (px between / indenting the paragraphs the text splits into at "\n" — the write half of the same fields get_design_context reads), textWrapStyle (BALANCE evens the line lengths of a heading, PRETTY avoids an orphan last word — the same three values as CSS text-wrap) — these load the required fonts first. Alignment: textAlignHorizontal (CSS text-align; JUSTIFIED = justify) and textAlignVertical (where the text sits in a box taller than it — it only shows with a fixed height, textAutoResize NONE or WIDTH_AND_HEIGHT hugging leaves no slack). Layout/overflow: textTruncation (ellipsis), maxLines (line clamp), textAutoResize. Any field may be omitted to leave it unchanged. maxLines applies when textTruncation is ENDING. Text on a path (TEXT_PATH) takes fontName, fontSize, letterSpacing, textCase and the two alignments — on a path textAlignHorizontal anchors the text at its start point and textAlignVertical picks the side of the path; the line, paragraph, decoration and box fields are refused there. Returns { ok, nodeId }.
set_text_rangeActionStyle character ranges of an existing TEXT node — the write-side mirror of a read segment, for inline rich text (a link inside a sentence, a bold word, a coloured span, a bulleted list, a smaller /mo after a price). Each range gives start/end (char offsets into the node's characters) plus any subset of run properties: fontName / fontSize / fills / textDecoration / textCase / lineHeight / letterSpacing / hyperlink / listOptions / indentation / textWrapStyle, and design-system bindings textStyleId / fillStyleId / boundVariables. Ranges apply in order (a later range overrides an earlier one on overlap). Fonts are loaded automatically. Set the whole node first with create_text / set_text; use set_text_properties for node-level typography & overflow. Text on a path (TEXT_PATH) takes the run fields it draws — fontName, fontSize, fills, textCase, letterSpacing, hyperlink and the bindings — and refuses decoration, lineHeight, lists and textWrapStyle. Returns { ok, nodeId }.
create_frameActionCreate a frame — the primary container for UI and the only node that hosts auto-layout — optionally sized/positioned and appended to a parent (default: current page). Pass fills, strokes, cornerRadius, autoLayout and layoutSizing* to style and lay it out in this same call (each means what it does on its set_* tool) instead of a chain of follow-ups. With autoLayout, a width + height you pass stays FIXED on any axis whose layoutSizing* you omit (Figma would otherwise hug it); omit the size, or pass HUG, to hug the content. For a canvas-level grouping container use create_section instead. Returns { ok, nodeId, name, type }.
set_opacityActionSet a node's layer opacity from 0 (transparent) to 1 (opaque); this multiplies with any fill or stroke alpha. Opacity 0 still renders, exports, and hit-tests — to exclude a node from rendering use set_visible(false), and to remove it use delete_nodes. Returns { ok, nodeId }.
set_visibleActionShow or hide a node by toggling its `visible` flag. A hidden node stays in the layer tree but is excluded from rendering and exports, and its descendants are hidden with it; the change is fully reversible. To remove a node use delete_nodes; to dim one while keeping it visible and exported use set_opacity. Returns { ok, nodeId }.
rename_nodeActionRename a single canvas node's layer name; does not affect a component's name elsewhere or its instances. To rename a document page use rename_page; to rename many nodes by pattern use batch_rename_nodes; a prototype flow's name is not its frame's name, so rename a flow with update_flows. Returns { ok, nodeId }.
delete_nodesActionPermanently delete nodes by id; missing or non-removable nodes are skipped. To hide nodes reversibly instead of deleting them, use set_visible(false). Returns { ok, affected } — the ids actually removed.
create_textActionCreate a new TEXT node with the given characters (default font loaded automatically), optionally sized/positioned and appended to a parent (default: current page). To change the text of an existing node use set_text. Typography (fontName, fontSize, lineHeight, textAlignHorizontal, …) takes the same fields as set_text_properties, and fills the text colour (as set_fills), all in this call — set the real font here, a new node is Inter. Returns { ok, nodeId, name, type }.
create_rectangleActionCreate a rectangle, optionally sized/positioned and appended to a parent (default: current page). Useful for solid shapes, dividers, and color blocks; for a container that holds other layers use create_frame; for a bitmap, import_image places one, or set_image_fill puts it into this rectangle (a rounded thumbnail, an avatar). fills, strokes, cornerRadius and layoutSizing* style it in the same call. Returns { ok, nodeId, name, type }.
set_corner_radiusActionSet a node's corner radius and/or corner smoothing. Pass radius for a uniform radius, and/or per-corner topLeftRadius / topRightRadius / bottomRightRadius / bottomLeftRadius (for nodes that support individual corners, e.g. a card rounded only on top, a tab or a chat bubble). A per-corner value overrides radius for that corner. cornerSmoothing is 0–1 (0 = circular, 0.6 = squircle); it can be set without changing any radius. At least one radius or cornerSmoothing is required. Returns { ok, nodeId }.
set_strokesActionSet a node's strokes (SOLID, gradient or PATTERN paints, same shape as set_fills) plus optional strokeWeight, strokeAlign (INSIDE / OUTSIDE / CENTER), dashPattern (dashes), and per-side weights (strokeTopWeight / strokeRightWeight / strokeBottomWeight / strokeLeftWeight — for nodes that support individual stroke weights, e.g. a border-bottom-only divider). A per-side weight overrides strokeWeight for that side. strokeCap shapes the ends of an open path or line — ROUND for a pen line, an ARROW / TRIANGLE / DIAMOND / CIRCLE cap for an arrowhead or a connector end — on every open end, so an arrow cap on a line heads both ends; for one arrowhead draw it with create_vector’s vectorNetwork, the cap on its end vertex. strokeJoin (MITER / BEVEL / ROUND) shapes the corners, strokeMiterLimit (1–16) how long a MITER corner may get before it is bevelled. Any field may be omitted to leave it unchanged. Brushes, dynamic strokes and width profiles are set_complex_stroke. Returns { ok, nodeId }.
move_nodesActionTranslate nodes by (dx, dy). Nodes without a position are skipped. Returns { ok, affected }.
align_nodesActionAlign nodes to their parent's bounds or to each other, and/or space them evenly — Figma's align / distribute toolbar. horizontal: MIN = left edge, CENTER, MAX = right edge; vertical: MIN = top, CENTER, MAX = bottom; either may be omitted to leave that axis alone. relativeTo PARENT (default) aligns each node within its own parent frame — the way to "centre this in its container" without computing x/y; SELECTION aligns the nodes to the bounding box they form together (line up a row on a shared top, or on a shared centre). distribute HORIZONTAL / VERTICAL keeps the outermost two nodes where they are and spaces the rest so the gaps between neighbours are equal (needs 3+ nodes; it cannot be combined with alignment on the same axis). Measures what each node covers, so a rotated node is centred by what you see; PARENT measures in the parent's own axes (left in a rotated frame is that frame's left edge), SELECTION and distribute on the canvas. Refused, before anything moves: an in-flow child of an auto-layout frame — the layout owns its position, so centre it with the parent's primaryAxisAlignItems / counterAxisAlignItems or its own layoutAlign (set_auto_layout / set_layout_props), or set layoutPositioning ABSOLUTE first; a layer inside an instance (align the instance, or edit its main component); a node whose ancestor is in the same call (moving the ancestor already carries it). A repeated id is moved once. Returns { ok, affected }.
create_shapeActionCreate a LINE, POLYGON or STAR, optionally sized/positioned and appended to a parent (default: current page). A LINE is a length: `width` is its length (default 100, with the black 1px stroke Figma gives it) and it has no height — pass strokes / strokeWeight here to style it (caps via set_strokes) and tilt it with rotate_nodes. A POLYGON takes `pointCount` (sides, 3–60, default 3) and a STAR takes `pointCount` (points, 3–60, default 5) and `innerRadius` (the inner ring as a share of the outer, above 0 and up to 1 — 1 is a regular polygon of twice the points; default 0.38). For rectangles and ellipses use create_rectangle / create_ellipse; to cut or merge shapes use boolean_nodes; for arbitrary vector artwork import_svg. fills, strokes and layoutSizing* style it in the same call. Returns { ok, nodeId, name, type }.
boolean_nodesActionCombine shapes into one editable boolean group: UNION merges them, SUBTRACT cuts the upper layers out of the lowest one (a ring from a circle and a smaller circle; the order is the layer stacking, not the order of nodeIds), INTERSECT keeps only the overlap, EXCLUDE keeps everything except the overlap. Like Figma’s own Boolean command, the result takes the fill and effects (or the fill / effect style) of the topmost operand — of the lowest for SUBTRACT — and no stroke; set_strokes on the result if it needs one. The operands stay inside the result as its children, so it can still be unpicked; use flatten_nodes to bake it into one vector. The nodes must share a parent, and the result takes their place there. Needs at least 2 distinct nodes. Not allowed inside a batch. Returns { ok, nodeId, name, type }.
flatten_nodesActionFlatten nodes into a single vector layer (Figma’s Flatten): shapes, text and boolean groups are outlined and merged into one path whose points can be edited. Irreversible for the content — text stops being text and a boolean group stops being unpickable — so use it when the artwork is final, e.g. to export an icon as a single path. The nodes must share a parent, and the result takes their place there. Not allowed inside a batch. Returns { ok, nodeId, name, type }.
repeat_nodesActionWrap layers in a repeat group (Figma Draw), which draws their content several times and stays live — edit the content and every copy follows: a row or grid of dots, the ticks round a dial, petals round a centre, a dashed border made of shapes. LINEAR draws count copies in total, each offset further along axis. RADIAL turns each copy a further 360°/count clockwise about a point straight below the content, so the content’s centre travels a circle offset px across — offset is that circle’s diameter. A second modifier repeats everything the first one drew: two LINEAR ones on different axes make a grid. The nodes must share a parent; the group takes the place of the topmost and the content keeps its position. Change the repeat later with set_repeat; ungroup_nodes removes it. Returns { ok, nodeId, name, type } for the new TRANSFORM_GROUP.
set_repeatActionReplace how a repeat group (TRANSFORM_GROUP — from repeat_nodes, or drawn in Figma Draw) repeats its content. LINEAR draws count copies in total, each offset further along axis. RADIAL turns each copy a further 360°/count clockwise about a point straight below the content, so the content’s centre travels a circle offset px across — offset is that circle’s diameter. A second modifier repeats everything the first one drew: two LINEAR ones on different axes make a grid. get_node reads the current modifiers in this same shape. [] keeps the group and draws the content once. A repeat group inside an instance cannot take this — Figma does not let an instance override it; change the main component. Returns { ok, nodeId }.
create_text_pathActionSet text along a path (Figma Draw): turn a shape, line or vector into text that follows its outline — lettering round a badge or seal, a caption along a curve. The source is consumed (its fill and stroke go; the text is black unless fills says otherwise) and the result takes its place: same parent, stack position and spot on the canvas, under a NEW node id, returned. The path starts where its first segment does and runs clockwise: a rectangle at its top-left corner (4 segments, 8 when its corners are rounded), an ellipse at its rightmost point (4), a polygon or star at its top point (one per side), a line at its start (1), a vector along its own segments. startSegment / startPosition (0–1 along that segment) move the start. textAlignHorizontal anchors the text there — LEFT starts at it, CENTER centres on it, RIGHT ends at it; text running past either end of an open path is not drawn. textAlignVertical TOP sits the baseline on the path (the letters on the outside of a clockwise circle), BOTTOM hangs them on the other side, CENTER straddles it. Restyle it afterwards with set_text, set_text_properties and set_text_range (font, size, case, tracking, links, fills — text on a path has no line height, decoration, lists or box) and move its start with set_text_path. Not allowed inside a batch. Returns { ok, nodeId, name, type }.
set_text_pathActionMove where text on a path (TEXT_PATH) starts: a segment of its path and 0–1 along it — the same textPathStartData get_node reports. The segments are numbered as create_text_path describes; an index past the last is refused (Figma would silently ignore it). Edit the text itself with set_text / set_text_properties / set_text_range. Returns { ok, nodeId }.
set_complex_strokeActionGive a node's stroke a Figma Draw look — a brush, a hand-drawn wobble or a width that varies along it — on any node with a stroke (paths, shapes, frames, text). complexStrokeProperties: { type:'BRUSH', brushType:'STRETCH', brushName, direction } drags one textured stroke along the path; { type:'BRUSH', brushType:'SCATTER', brushName, gap, wiggle, sizeJitter, angularJitter, rotation } stamps the brush along it; { type:'DYNAMIC', frequency, wiggle, smoothen } wobbles it; { type:'BASIC' } goes back to a plain stroke. Fields left out take the brush's own defaults. variableWidthStrokeProperties: { widthProfile } with a preset (WEDGE, TAPER, QUARTER_TAPER, EYE, MIRRORED_TAPER; UNIFORM = constant), or CUSTOM with variableWidthPoints [{ position 0–1 along the stroke, width }] — the stroke is 2 × width × strokeWeight thick there, so 0.5 is its normal weight and 1 twice it; a vector that branches cannot take one. Both may be combined. The node needs a visible stroke first (set_strokes) — its colour and weight still apply. Any of these draws the stroke solid: a dash pattern stays set but is not drawn. These are the same fields get_node reads. Returns { ok, nodeId }.
create_vectorActionDraw a vector — one editable VECTOR layer, no wrapper frame — from its geometry: vectorPaths (SVG path data in any syntax — an icon’s d attribute as is, arcs and relative commands included) or vectorNetwork (Figma’s own form, which can branch and carries per-vertex arrowheads and corner radii). Give exactly one. x / y place the drawing’s origin in the parent, so a point at (10, 4) lands at (x + 10, y + 4); Figma then fits the layer’s box to the drawing, which is where get_vector measures from afterwards. An open path needs strokes to be seen (pass strokes / strokeWeight here); a closed one takes fills. Then shape its stroke with set_complex_stroke (a brush, a hand-drawn wobble, a taper) or set text along it with create_text_path. For a whole SVG file use import_svg. Returns { ok, nodeId, name, type }.
set_vectorActionRedraw an existing VECTOR’s geometry: vectorPaths (SVG path data) or vectorNetwork (vertices, segments with Bézier tangents, regions) — exactly one, in the shape get_vector reads, so read, edit the points, write back (paths in any SVG syntax; what reads back is Figma’s own form — absolute commands, its own subpath order). Coordinates are in the layer’s current space: the drawing stays where they put it and Figma refits the layer’s box around it, so drawing left of 0 moves the layer left (and an auto-layout parent re-flows to the new size). Fills, strokes, effects, a brush or dynamic stroke, and one cap or join the whole line had stay; a width profile is dropped when the new network branches (Figma allows none there). A rectangle, ellipse, polygon, star or line has to be flatten_nodes’d into a VECTOR first; a vector inside an instance cannot be redrawn (change the main component); text on a path cannot change its path. Returns { ok, nodeId }.
outline_strokeActionOutline a node’s stroke — Figma’s Outline Stroke: a new VECTOR (a GROUP of glyph outlines for text) whose filled shape is exactly what the stroke draws — a brush, a hand-drawn wobble, a taper and dashes included — so it can be recoloured, combined with boolean_nodes, edited point by point (get_vector / set_vector) or exported as plain vector art. It is filled with the stroke’s paints and keeps the node’s opacity, blend mode and effects; the node’s own fills are not part of it. It lands directly above the node, at the same spot — above the instance, boolean or repeat group holding the node, which cannot take it, or beside a group an auto-layout frame lays out, which would grow to fit it and move — and absolutely positioned in an auto-layout frame so nothing re-flows or moves. The node itself stays; delete_nodes it to replace it. A scatter brush outlines into thousands of shapes. Returns { ok, nodeId, name, type } for the outline.
set_positionActionSet a node's exact position (x / y), relative to its parent — for a top-level node these are canvas coordinates; for an absolutely-positioned child they are relative to its auto-layout parent. Use this to place an overlay / badge / pinned element at a known spot, or to position a top-level frame on the canvas; to nudge by a delta instead use move_nodes. A node that sits in-flow inside an auto-layout frame is positioned by the layout — set layoutPositioning ABSOLUTE (set_layout_props) first to place it freely. Either coordinate may be omitted to leave it unchanged. Returns { ok, nodeId }.
resize_nodesActionResize nodes to the given width × height (width at least 0.01 px). A LINE takes the width as its length and keeps height 0 — pass 0, or any height is reported in adjusted; every other node needs a height of at least 0.01 px, checked before any node is resized. This fixes the size, so an auto-layout FILL / HUG axis becomes FIXED. Non-resizable nodes are skipped. A layer inside an instance keeps the size its main component gives it — resize the instance itself, change the layer in the main component, or detach_instance first. Every node is read back: affected lists the nodes that reached the requested size, and adjusted lists any Figma sized differently (an instance layer, a minWidth / maxWidth / minHeight / maxHeight bound) with its actual size and why. A call that changed nothing throws. Returns { ok, affected, adjusted? }.
set_auto_layoutActionConfigure a frame's auto layout. layoutMode NONE disables it; HORIZONTAL/VERTICAL enable flex (padding / itemSpacing / alignment / wrap, plus counterAxisSpacing / counterAxisAlignContent for the wrapped cross axis — the CSS row-gap (column-gap when VERTICAL) / align-content — and itemReverseZIndex / strokesIncludedInLayout for paint order and stroke-in-layout); GRID enables CSS-Grid-style layout (padding / gridRowCount / gridColumnCount / gridRowGap / gridColumnGap, plus gridItemsPositioning / gridAutoTracks for children that flow into cells by order and rows that grow with them). Setting GRID on a frame that is already a grid keeps its tracks and placements. Returns { ok, nodeId }.
set_layout_propsActionSet a node's sizing, child properties and content clipping. clipsContent controls whether a frame-like container clips its children; it also works without auto-layout. layoutSizingHorizontal / layoutSizingVertical (HUG = shrink to fit children, FILL = stretch to fill the auto-layout parent, FIXED = keep the current size) are the preferred way to size a frame to its content (HUG) or make a child fill its container (FILL) — reach for these instead of guessing pixel sizes with resize_nodes. layoutAlign (STRETCH = fill the counter axis, INHERIT = default) and layoutGrow (1 = fill the primary axis, 0 = hug) are the older per-axis equivalents. Figma has no per-child alignment: every child of an auto-layout frame shares the frame’s counterAxisAlignItems, so to centre one child alone wrap it in its own auto-layout frame, or make it ABSOLUTE and use align_nodes. layoutPositioning (ABSOLUTE = ignore the flow and position freely, AUTO = participate in layout). minWidth / maxWidth / minHeight / maxHeight set responsive size bounds (→ min-w / max-w); pass null to clear a bound. Bounds apply to auto-layout frames and their direct children. HUG needs an auto-layout frame (or text); FILL needs an auto-layout parent. Any field may be omitted to leave it unchanged. Returns { ok, nodeId }.
set_layout_gridsActionSet a frame's own layout grids — the responsive column/row scaffold laid over it (the 12-column grid, the 8pt baseline), distinct from auto-layout (set_auto_layout arranges children). Each grid is COLUMNS / ROWS (count + gutterSize + alignment, e.g. a 12-col grid) or GRID (uniform squares via sectionSize, a baseline). Replaces the frame's grids with the array given; pass [] to clear them. Only frames (and components/instances) carry layout grids. Returns { ok, nodeId }.
set_blend_modeActionSet how a node composites with the layers beneath it (NORMAL, MULTIPLY, SCREEN, OVERLAY, DARKEN, LIGHTEN, COLOR_DODGE, etc.). PASS_THROUGH is only meaningful on groups/frames (lets children blend with content outside the group). Affects compositing only, not the node's own fills — use set_fills or set_opacity for those. Returns { ok, nodeId }.
set_maskActionSet whether a node is a mask — a mask clips its later siblings to its own shape. Pass isMask true/false, and optionally maskType (ALPHA / LUMINANCE / GEOMETRY) when enabling. Returns { ok, nodeId }.
set_arcActionTurn an ellipse into a pie slice / gauge or a ring / donut by setting its arc data. startingAngle / endingAngle are in radians and carve out the visible wedge (a full circle is 0 → 2π ≈ 6.28319; a half is π ≈ 3.14159); innerRadius is 0–1 of the radius (0 = a solid disc, > 0 = a ring with a hole, e.g. 0.6 for a donut or progress ring). Only ellipses have arc data. Pass any subset — omitted fields keep their current value. At least one is required. Returns { ok, nodeId }.
set_constraintsActionSet how a node responds when its parent frame is resized, via horizontal and vertical constraints: MIN pins to the left/top, MAX to the right/bottom, CENTER keeps it centered, STRETCH pins both edges (grows with the parent), and SCALE resizes proportionally. Constraints apply to children of a plain frame and to ABSOLUTE children of an auto-layout frame; an in-flow auto-layout child is positioned by the layout and ignores them. Returns { ok, nodeId }.
rotate_nodesActionSet absolute rotation (degrees) on nodes. Nodes without rotation are skipped. Returns { ok, affected }.
flip_nodesActionMirror nodes in place — Figma’s Flip horizontal / Flip vertical: HORIZONTAL swaps left and right on the canvas, VERTICAL top and bottom, each node about its own centre, so it stays where it was. A flipped node reads back flipped: true with its cssTransform. Flipping twice restores it. Returns { ok, affected }.
lock_nodesActionLock nodes so they can't be selected or edited on the canvas (e.g. backgrounds); locking a parent also locks its descendants. Locked nodes still render and export — this only affects canvas interaction and is reversed by unlock_nodes. Returns { ok, affected } with the ids actually locked.
unlock_nodesActionUnlock nodes so they can be selected and edited on the canvas again — the inverse of lock_nodes. Ids that no longer exist are skipped. Returns { ok, affected } with the ids actually unlocked.
clone_nodeActionDuplicate a node — including its full subtree — and place the copy as a sibling right after the original under the same parent. Cloning a component instance keeps it an instance; to make a fresh instance of a component use create_instance instead. Cloning a prototype flow's starting frame also clones the flow, under the same name, right after the original (rename or remove it with update_flows). Returns { ok, nodeId, name, type } for the copy.
set_effectsActionSet a node's effects. Shadows (DROP_SHADOW / INNER_SHADOW) need color + offset; blurs need radius. A drop shadow is written with showShadowBehindNode false unless it says true — what a CSS box-shadow draws. Returns { ok, nodeId }.
create_paint_styleActionCreate a reusable local paint (color) style from SOLID or gradient paints (same shape as set_fills); use slashes in the name for folder grouping. Apply it to nodes with apply_style_to_node, or edit it later with update_paint_style. Returns { ok, styleId, name }.
create_text_styleActionCreate a reusable local text style (a typography token) that can be applied to TEXT nodes with apply_style_to_node. The font is loaded before assignment. lineHeight unit is AUTO / PIXELS / PERCENT (AUTO omits value); letterSpacing unit is PIXELS / PERCENT; textWrapStyle is the wrap balancing (CSS text-wrap) every bound node inherits. For one-off formatting of a single node use set_text_properties instead. Returns { ok, styleId, name }.
create_effect_styleActionCreate a local effect style. Shadows (DROP_SHADOW / INNER_SHADOW) need color + offset; blurs (LAYER_BLUR / BACKGROUND_BLUR) need radius. Returns { ok, styleId, name }.
create_grid_styleActionCreate a reusable local layout-grid style for aligning content. Each grid pattern is GRID (uniform squares via sectionSize) or ROWS / COLUMNS (count + gutterSize + alignment). Apply it to frames with apply_style_to_node. Returns { ok, styleId, name }.
update_paint_styleActionUpdate an existing paint style by id. Any of name / paints / description may be omitted to leave unchanged. Because paints replace wholesale, a paint written back WITHOUT its boundVariables clears the variable it was bound to — re-send the binding, or change the variable itself instead. Returns { ok, styleId, name }.
update_text_styleActionUpdate an existing text style (typography token) by id. Any of name / fontName / fontSize / lineHeight / letterSpacing / textWrapStyle / description may be omitted to leave unchanged. A new font is loaded before assignment. lineHeight unit is AUTO / PIXELS / PERCENT (AUTO omits value); letterSpacing unit is PIXELS / PERCENT. Use this to keep a shared style in sync with code instead of creating a duplicate. Returns { ok, styleId, name }.
update_effect_styleActionUpdate an existing effect style by id. Any of name / effects / description may be omitted to leave unchanged; effects, when given, replaces the whole list. Shadows (DROP_SHADOW / INNER_SHADOW) need color + offset; blurs (LAYER_BLUR / BACKGROUND_BLUR) need radius. Use this to keep a shared style in sync with code instead of creating a duplicate. Because effects replace wholesale, an effect written back WITHOUT its boundVariables clears the variables it was bound to — re-send them, or change the variable itself instead. Returns { ok, styleId, name }.
apply_style_to_nodeActionBind a shared style to a node. `field` selects which slot the style applies to: fill / stroke / effect / grid / text. Use a style id already available in this file (including get_node styleIds); for a library style, call import_style with its key in the target file and apply the returned styleId, not the key or a source-file id. Returns { ok, nodeId }.
import_styleActionImport a published library paint, text, effect or grid style by its key into the current file. Returns { ok, styleId, name }; use the returned styleId with apply_style_to_node. A key is not a style id, and an id from the source library is not a target-file reference. Get the key from get_styles in the source file. Does not apply the style or edit any node. Unpublished or inaccessible styles are refused by Figma. Import before a batch; library imports cannot be rolled back.
delete_styleActionDelete a local style (paint / text / effect / grid) by id. Returns { ok, styleId, name }.
create_variable_collectionActionCreate a variable collection. Figma auto-creates a default mode. Returns { ok, collectionId, defaultModeId, name }.
update_variable_collectionActionRename a variable collection and/or its modes. Either of name / modes may be omitted to leave unchanged. No id changes, so every binding and every mode value survives — this is how a mis-named collection gets fixed, because deleting and recreating one mints a new id and takes its variables and modes with it. Mode ids come from get_variable_defs. Every mode id is checked before anything is written, so one bad id leaves the collection untouched rather than half-renamed. Returns { ok, collectionId, name, modes } with the full mode list as it now stands.
add_variable_modeActionAdd a mode (e.g. "Dark") to a variable collection. Returns { ok, modeId, name }. Mode count is gated by the file's Figma plan (Starter allows 1 per collection) — when the plan blocks a new mode this fails with guidance: fall back to a paired collection (e.g. "Color/Dark") holding the same variable names with that theme's values.
create_variableActionCreate a variable in a collection with resolvedType BOOLEAN / FLOAT / STRING / COLOR / EASING / TIMING. Set per-mode values with set_variable_value, then attach it with bind_variable_to_node or bind_variable_to_paint — or, for EASING (a Motion curve) and TIMING (seconds), as a { type: "VARIABLE_ALIAS", id } in a Motion easing or a preset's delay / duration. Optionally pass scopes to narrow where Figma offers the variable in its picker (a radius token scoped to CORNER_RADIUS stops being suggested for width or gap); omit it to leave the variable in every scope, which is Figma's default. Returns { ok, variableId, name }.
set_variable_valueActionSet a variable's value for one mode (modeId comes from the variable's collection). value must match the variable resolvedType: a boolean, a number (FLOAT), a string, a color { r, g, b, a } (0–1, in the document's colour space unless `space` names another — pass "SRGB" for a colour taken from code), an alias { type: "VARIABLE_ALIAS", id } pointing at another variable, or a composed color { color, opacity } that pairs a color with a separate opacity — each half either a concrete value or an alias, with at least one of the two an alias. An EASING variable takes a Motion easing, a TIMING variable a number of seconds. Create the variable first with create_variable. Returns { ok, variableId, name }.
bind_variable_to_nodeActionBind a variable to a node field (e.g. width, height, characters, itemSpacing, topLeftRadius, or cornerRadius to bind all four corners at once), or unbind by passing variableId: null. The variable's resolvedType must match the field's type. To bind a fill or stroke color use bind_variable_to_paint instead; get local variable ids from get_variable_defs. For a library variable, call import_variable with its key in the target file and bind the returned variableId (not the key or a source-file id). Returns { ok, nodeId }.
bind_variable_to_paintActionBind a COLOR variable to a SOLID fill or stroke paint (the design-token way to colour a node) — or unbind by passing variableId: null. Figma stores fill/stroke colour bindings on the paint, not the node, so this is separate from bind_variable_to_node (which covers scalar fields like width / padding / radius). target is fills (default) or strokes; index selects which paint (default 0). The paint at that index must be SOLID. Binding replaces the paint's opacity with the variable's alpha, so a 50% fill bound to an opaque variable ends up opaque; for a translucent token, bind a variable whose value carries that alpha. For a library variable, call import_variable with its key in the target file and bind the returned variableId. Returns { ok, nodeId }.
import_variableActionImport a published library variable by its key into the current file. Returns { ok, variableId, name }; use the returned variableId with bind_variable_to_node, bind_variable_to_paint or other variable bindings. A key is not a variable id, and an id from the source library is not a target-file reference. Get the key from get_variable_defs in the source file. Does not bind or edit any node. Unpublished or inaccessible variables are refused by Figma. Import before a batch; library imports cannot be rolled back.
set_node_variable_modeActionSwitch a node to one of a variable collection's modes — the Dark (or another theme, brand or language) variant of a frame, a component, a layer inside an instance, or a whole page — so every variable bound in its subtree takes that mode's value. This changes which mode a node renders in; to add or remove modes on the collection itself use add_variable_mode / delete_variable_mode. collectionId and modeId come from get_variable_defs. modeId null clears the setting so the node inherits its parent's mode again. Returns { ok, nodeId, collectionId, collectionName, modeId, modeName }.
rename_variableActionRename a variable (e.g. "color/primary" → "color/brand"); use slashes in the name for folder grouping in the Variables panel. The variable id is unchanged, so existing bindings keep working. Returns { ok, variableId, name }.
set_variable_code_syntaxActionDeclare a variable's code-side token name per platform (codeSyntax) — the write half of the codeSyntax that get_design_context / get_variable_defs surface to codegen as the authoritative name (e.g. WEB: "--color-primary"). Per platform (WEB / ANDROID / iOS): a non-empty string sets the declaration, null removes it, an omitted platform is untouched. When authoring design-system variables from existing code tokens, declare the source token name here so future codegen resolves to the exact token instead of deriving a name. Returns { ok, variableId, name, codeSyntax } with the declarations now in effect.
delete_variableActionDelete a single variable by id; any node or paint bound to it reverts to its raw value. To delete an entire collection and all its variables use delete_variable_collection. Returns { ok, variableId, name }.
delete_variable_modeActionRemove a mode from a variable collection, freeing the slot it holds — mode count is gated by the file's Figma plan (Starter allows 1 per collection), so a mode added by mistake otherwise occupies that budget for good. Every variable's value for this mode goes with it. Not reversible: adding a mode back mints a new mode id, and the values that hung on the old id do not come with it — which is also why this tool cannot be used inside batch. Removing the collection's default mode is allowed (Figma moves the default to a mode that remains); the last remaining mode cannot be removed. Mode ids come from get_variable_defs. Returns { ok, collectionId, modeId, name }.
delete_variable_collectionActionDelete a variable collection by id, removing the collection and every variable and mode in it; bindings to those variables revert to their raw values. To delete a single variable instead, use delete_variable. Returns { ok, collectionId, name }.
group_nodesActionGroup nodes under their shared parent. nodeIds must be a non-empty list. Returns { ok, nodeId, name, type } for the new group.
ungroup_nodesActionUngroup GROUP nodes by id — and repeat groups (TRANSFORM_GROUP, from repeat_nodes or Figma Draw), which drops the repeat and leaves the original content in place; other nodes are skipped. Returns { ok, affected } — the ids of the children promoted out of the groups.
reparent_nodesActionMove nodes into a different parent, optionally inserting at `index` (default: appended last). On-screen positions may shift because coordinates become relative to the new parent; nodes that no longer exist are skipped. To reorder within the current parent use reorder_nodes; to wrap nodes in a new frame/group use group_nodes. Returns { ok, affected }.
reorder_nodesActionReorder nodes within their current parent by inserting each at `index` (0 = bottom of the z-order). Detached nodes are skipped. Returns { ok, affected }.
find_replace_textActionReplace a substring across all TEXT nodes under a scope (text set along a path is not searched — scan_text_nodes lists those, and set_text edits one). Without root the whole current page is searched; matching is case-insensitive unless caseSensitive is true. Only the matched text changes: every other run keeps its styling, and each replacement takes the style of the text it replaces. Fonts are loaded before each edit. Returns { ok, affected } — the text node ids changed.
batch_rename_nodesActionRename many nodes at once from a [{ nodeId, name }] list. Missing nodes are skipped. Returns { ok, affected }.
add_pageActionCreate a new page (optionally named). Returns { ok, nodeId, name, type }.
delete_pageActionDelete a page by id. The current page and the last remaining page cannot be deleted. Returns { ok, nodeId }.
rename_pageActionRename a Figma page (a top-level page/tab in the document) by id. Affects only the page name; its node id and contents are unchanged. To rename a layer/node on the canvas use rename_node instead, and a prototype flow with update_flows. Returns { ok, nodeId }.
navigate_to_pageActionSwitch the active page. Subsequent selection / read tools operate on this page. Returns { ok, nodeId }.
set_reactionsActionReplace all of a node's prototype reactions — this overwrites existing reactions rather than appending. Each reaction pairs a trigger (e.g. { type: 'ON_CLICK' }, or ON_KEY_DOWN with device + keyCodes) with an actions array: NODE carries destinationId, navigation (NAVIGATE / SWAP / OVERLAY / SCROLL_TO / CHANGE_TO) and transition; URL, BACK, CLOSE, SET_VARIABLE, SET_VARIABLE_MODE, UPDATE_MEDIA_RUNTIME and CONDITIONAL carry their own fields. An OVERLAY action takes overlayRelativePosition ({ x, y }) to offset the overlay, which Figma applies only when the destination frame's overlay position is set to Manual — that setting lives on the frame and is read-only to plugins, so it must be chosen in Figma first. get_reactions output round-trips through here unchanged; to clear all reactions instead use remove_reactions. On a page with no prototype flows, Figma may make the top-level frame holding a new connection a flow named "Flow 1" on its own; get_pages lists it and update_flows renames or removes it. Returns { ok, nodeId }.
remove_reactionsActionClear every prototype reaction from a node (equivalent to set_reactions with an empty array). Use this to strip interactivity; to replace reactions with new ones use set_reactions. Returns { ok, nodeId }.
update_flowsActionRename, add, remove or reorder a page's prototype flows — the named starting points Presentation view lists (get_pages shows each page's flows). A flow's name is its own: it is not the frame name (rename_node) or the page name (rename_page). Flows are addressed by their starting frame's nodeId, never by name, since several flows may share one. Only the flows named are touched; every other flow keeps its name and place. flows renames a flow in place, or makes a frame a new flow appended at the end; remove stops a frame being a flow (the frame and its reactions stay); order moves flows to the front, and the first flow is the one Presentation view opens by default. A flow starts on a visible top-level frame, component or instance of that page (directly on it or in a section). A flow whose frame is hidden, grouped or nested is invisible to plugins until that frame is visible and top-level again, so it can be neither listed nor changed. The list is checked before and read back after the write: any argument that cannot apply leaves the page unchanged, and the error names the frame and why. Returns { ok, pageId, flows } with the full list as it now stands.
swap_componentActionSwap an instance's main component. Provide componentKey (published component, imported via the API) or componentId (a local COMPONENT node). Returns { ok, nodeId } (the instance id).
set_instance_propertiesActionSet an instance's component properties (variant / boolean / text / instance-swap). Keys are the property names from get_component_api, used verbatim: VARIANT by bare name (e.g. "Size": "Large"), BOOLEAN/TEXT/INSTANCE_SWAP suffixed with #id (e.g. "Label#2:0": "Sign in", "Disabled#1:2": true). An INSTANCE_SWAP value is the target component node id. Unspecified properties keep their value; SLOT properties are not settable. Returns { ok, nodeId }.
add_component_propertyActionDeclare a component property on a component (or its variant set): BOOLEAN (show/hide a layer), TEXT (editable text), or INSTANCE_SWAP (swappable nested instance). The property starts inert — attach it to a layer with bind_component_property (BOOLEAN→visible, TEXT→characters, INSTANCE_SWAP→mainComponent) for it to do anything. defaultValue must match the type (boolean / string / a component key string); preferredValues (INSTANCE_SWAP only) pre-populates the swap menu. VARIANT properties come from combine_as_variants, not here. Returns { ok, componentId, propertyId, name } — pass propertyId to bind / edit / delete / set_instance_properties.
bind_component_propertyActionAttach a declared component property (from add_component_property) to a sublayer field so it drives that layer: field "visible" for a BOOLEAN, "characters" for a TEXT (the node must be a TEXT node), "mainComponent" for an INSTANCE_SWAP (the node must be an INSTANCE). The same property can be bound to several layers (call once per layer). Pass propertyId: null to remove the binding on that field. The property's type must match the field and it must exist on the containing component. Returns { ok, nodeId }.
edit_component_propertyActionChange an existing component property: rename it, change its defaultValue, or (INSTANCE_SWAP only) change its preferredValues. Supply at least one. Renaming returns a new propertyId (the #id suffix is kept but the name part changes), so use the returned propertyId for later calls; existing bindings keep working. Get current property ids from get_component_api. Returns { ok, componentId, propertyId, name }.
delete_component_propertyActionRemove a BOOLEAN / TEXT / INSTANCE_SWAP property from a component and every sublayer reference to it. VARIANT properties are the variant-set structure — delete their variants instead; this refuses a VARIANT. Get current property ids from get_component_api. Returns { ok, componentId, propertyId, name }.
detach_instanceActionDetach a component instance into a plain frame, permanently breaking its link to the main component; the frame keeps its current appearance and its layers become directly editable. To switch an instance to a different component instead of detaching, use swap_component. Returns { ok, nodeId, name, type } for the resulting frame.
import_imageActionImport a raster image (PNG / JPG / GIF) and place it as a rectangle with an IMAGE fill. Provide exactly one of path (a local file the server reads), data (base64-encoded image bytes) or url. Prefer path for a file on this machine: the bytes never pass through the conversation, and a large base64 data argument can exceed the transport message limit. url is fetched by Figma, not by this machine, so it must be publicly reachable. Figma accepts at most 4096px in width and height whichever source is used, so downscale a camera-resolution photo before importing it. The rectangle defaults to the image size unless width/height are given. scaleMode is FILL / FIT / CROP / TILE (default FILL). For vector SVG (logos / icons) use import_svg instead. Returns { ok, nodeId, name, type }.
set_image_fillActionPut a raster image (PNG / JPG / GIF) into an existing node's fills — a photo into a card cover, an avatar into a circle — keeping the node's size, position, corners, effects and constraints. import_image instead creates a new rectangle. Provide exactly one of path (a local file the server reads; preferred, the bytes never pass through the conversation), data (base64) or url (fetched by Figma, so it must be publicly reachable). Figma accepts at most 4096px in width and height. Without index, the topmost IMAGE fill gets the new image and keeps its crop, filters and scale mode, like Figma's Replace image; a node without one gets the image added on top of its fills. With index (0 = the bottom fill, the order get_node lists them in), that fill is replaced. scaleMode is FILL / FIT / CROP / TILE (default: keep the replaced image's, else FILL). Setting fills unlinks a fill style. Returns { ok, nodeId, index, imageHash, width, height } — the fill it wrote and the image size in pixels.
import_svgActionImport an SVG and place it as editable vector nodes (a FRAME of VECTOR paths) via createNodeFromSvg — use this for vector logos, brand marks, and icons. Provide the SVG's raw markup string (read it from the project asset, or inline it). The frame defaults to the SVG intrinsic size unless width/height are given. For raster photos (PNG / JPG) use import_image, or set_image_fill to fill an existing layer, instead; when a matching icon component already exists, create_instance it rather than re-pasting the SVG. Returns { ok, nodeId, name, type }.
create_ellipseActionCreate an ellipse (a circle when width equals height), optionally sized/named/positioned under a parent (default: current page). To turn it into a pie, arc, or ring afterwards use set_arc. fills, strokes and layoutSizing* style it in the same call. Returns { ok, nodeId, name, type }.
create_componentActionCreate a reusable main component. Pass fromNodeId to convert an existing node into a component (e.g. a frame of vectors from import_svg, or a built layout) — it keeps the node's position and parent unless parentId is given; omit fromNodeId to create an empty component to build into. Then create_instance the result to reuse it. Optionally sized / named / positioned and placed under a parent (default: current page). Returns { ok, nodeId, name, type }.
create_sectionActionCreate a section: a canvas-level container for grouping and labelling regions of a page (e.g. flows or screen sets). Sections sit on a page or nest inside another section, but not inside a frame; for a UI container or auto-layout use create_frame instead. Returns { ok, nodeId, name, type }.
create_instanceActionInstantiate a component. Provide componentId (a local COMPONENT node) or componentKey (a published component imported via the API). Optionally name / position / parent the instance. Returns { ok, nodeId, name, type } for the new instance.
combine_as_variantsActionCombine two or more existing COMPONENT nodes into a single COMPONENT_SET (a variant set). Name each component with Figma variant syntax (e.g. "Size=Small", "Size=Large") beforehand so the set derives its properties. The components are reparented into the new set under parentId (default: the first component's current parent). Returns { ok, nodeId, name, type }.
apply_animation_styleActionApply a Figma Motion animation-style preset to a node (get styleIds from get_motion_styles). config tunes it: duration (seconds), timelineOffset (seconds — the lever for staggered entrances: give each node index * step), and preset-specific props. Returns { ok, nodeId, appliedStyleId } — keep appliedStyleId to remove exactly this instance later. To stagger a whole row in one atomic, undoable call, drive N apply_animation_style ops through `batch` with increasing timelineOffset. Motion is a Figma-Design-only beta feature.
remove_animation_styleActionRemove an applied Figma Motion animation style from a node. Pass animationStyleId (the appliedStyleId returned by apply_animation_style, or read from get_node_motion) to remove one; omit it to remove all applied styles on the node. Returns { ok, nodeId }.
apply_manual_keyframe_trackActionSet a hand-authored Figma Motion keyframe track on a node for one field — e.g. TRANSLATION_X, OPACITY, ROTATION, SCALE_XY, or an indexed fills / strokes / effects item. `field` selects what to animate; `track` carries an optional baseValue plus keyframes (each with timelinePosition in seconds, a typed value, and optional easing). Replaces any existing track on that field. Returns { ok, nodeId }. Motion is a Figma-Design-only beta feature.
remove_manual_keyframe_trackActionRemove the manual Figma Motion keyframe track for a given field on a node. `field` selects the same target as apply_manual_keyframe_track (a node PROPERTY or an indexed fills/strokes/effects item). Returns { ok, nodeId }.
set_timeline_durationActionSet the duration (in seconds, must be > 0) of a Figma Motion timeline. Get the timelineId from get_node_motion (a node's `timelines`). Returns { ok, nodeId }.
batchActionApply multiple write ops atomically (all-or-nothing with rollback). ops is an ordered list of { tool, params } where tool is any write that can be undone exactly — property, text, layout, style, variable, component, structure and create writes (e.g. set_fills, set_text, set_auto_layout, reparent_nodes, create_frame). Ops that delete something (delete_*, ungroup_nodes, detach_instance, remove_animation_style) are refused, since what they delete cannot come back under its id. Returns { ok, results } with one result per op in order; on failure the error says what was rolled back.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableawdr74100/figwright is public and reachablegithub.com/awdr74100/figwright ↗Pass
- Package names this repository as its source@figwright/mcp names awdr74100/figwright as sourcenpmjs.com/package/@figwright/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @figwright/mcpnpmjs.com/package/@figwright/mcp/v/0.7.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/awdr74100/figwright ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @figwright/mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model135 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledDestructive tools carry destructiveHintPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAbout · Setup · Skills · Tools · Plugin · FAQ · Contributing
About
Figwright connects an MCP server to a Figma plugin over a local WebSocket relay, so an AI agent (Claude Code, Cursor, Codex, or any other MCP client) can work with Figma instead of just looking at it.
It works in both directions:
Read: turn a Figma selection into framework-aware code, grounded on faithful, de-duplicated design context (layout, typography, variables, components).
Write: author and edit the canvas directly, from frames and text to auto-layout, styles, variables, components, whole screens.
Everything runs on your machine: the server, the relay, and the plugin. Your designs are never sent anywhere.
Why Figwright
- Not gated: the official Dev Mode MCP is behind a paid Dev Mode seat. Figwright runs on the free tier.
- Bidirectional: not read-only. 135 tools span reading and writing the canvas, so an agent can both implement designs and build them.
- Provider-first codegen: Figwright detects your real stack (framework + styling system) and reuses your existing components, tokens, and icons, instead of emitting generic markup you have to rewrite.
- One agent per file: several agents can work at once, each claiming its own open Figma file. Switching tabs no longer sends one agent's edits into another's design — see working across files.
- Open & extensible: the read/write workflows ship as installable skills you can adopt or fork.
Setup
You need an MCP client (Claude Code, Cursor, …), Node.js 20.19+ or 22.12+, and Figma. The free Figma tier is enough, though the desktop app is needed to import the plugin. The server runs via npx as its own process, so its Node version is independent of the one your project builds with; Node 18/21 and 22.0–22.11 are not supported.
1. Add the server to your MCP client
For Claude Code, add this to your .mcp.json (other clients use the same shape):
{
"mcpServers": {
"figwright": {
"command": "npx",
"args": ["-y", "@figwright/mcp@latest"]
}
}
}
npx fetches and runs the published server, so no global install is needed.
2. Install the Figma plugin
The plugin isn't on the Figma Community marketplace yet, so install it from the latest release:
- Download the plugin zip from the latest GitHub Release and unzip it.
- In the Figma desktop app: Menu → Plugins → Development → Import plugin from manifest… and pick the unzipped
manifest.json.
3. Connect
Open the Figwright plugin in Figma (Plugins → Development → Figwright). It connects to the local server automatically and shows Connected. Ask your agent to run ping to confirm the link.
4. (Optional) Install the skills
The skills make agents reach for Figwright at the right moment and follow the grounded workflows:
npx skills add awdr74100/figwright/skills
5. Try it
With a frame selected in Figma, prompt your agent:
Code this Figma selection as a React component.
or, the other direction:
Build a pricing section in Figma from this spec.
Updating
Each release ships the server and the plugin together, so update both. The skills are optional and update the same way you installed them.
1. Restart the server. With the @latest config above there is nothing to install, because every launch fetches the newest release. A session that is already open keeps the server it started with, so new tools don't appear until you restart it: in Claude Code, run /mcp, pick figwright and choose Reconnect (or restart Claude Code); in other clients, restart the client. Do this in each client you use Figwright from.
If you installed the package instead of using @latest (see the FAQ), update it before restarting: npm i -D @figwright/mcp@latest, or npm i -g @figwright/mcp@latest for a global install.
2. Replace the plugin. Download the zip from the latest release, unzip it, and copy its manifest.json and dist into the folder you imported the plugin from, replacing the old ones. Figma runs a development plugin straight from that folder, so you don't import it again. Close the plugin and run it again.
3. Update the skills. Run npx skills update. Agent sessions you start after that use the new version.
To confirm, open the plugin's Debug tab: it lists the server and plugin versions side by side. If the plugin is still too old for the server, the panel header says so, and so does every tool result (see the FAQ).
Skills
Agent skills orchestrate Figwright's tools. They are model-invoked: your agent loads one automatically when the task matches its description.
| Skill | What it does |
|---|---|
figma‑codegen |
Turn a Figma selection into framework-aware code, grounded on your stack and existing components. |
figma‑build |
Build a Figma design from code or a description, reusing the file's existing components and styles. |
Install across any supported agent with the skills CLI:
npx skills add awdr74100/figwright/skills # both
npx skills add https://github.com/awdr74100/figwright/tree/main/skills/figma-codegen # one
[!NOTE] Skills need the
@figwright/mcpserver connected. On their own they have no tools to drive.
Tools
Figwright exposes 135 MCP tools in three groups:
- Read: selection, document and node inspection, styles, variables, components, fonts, prototype reactions and flows, motion (animation) state, screenshots, original image-fill assets, PDF export, and video export of animated frames (MP4 / GIF / WebM); plus
list_files/use_filefor working across more than one open Figma file at once. - Write: create and edit frames, text, shapes (lines, polygons, stars, boolean operations, flattening), auto-layout, alignment and distribution, effects, images (as a new layer or into an existing layer's fill), styles, variables (including importing a team library's variables and styles, and switching a frame to a mode such as Dark), components (including authoring their boolean/text/instance-swap properties), pages, prototype reactions and flows, Motion animations (keyframes, animation-style presets, timelines), and Figma Draw (vector paths drawn and edited point by point from any SVG path data, outlined strokes, repeat groups, text on a path, brush / dynamic / variable-width strokes, pattern fills); plus a
batchtool to apply many edits at once. - Grounding:
get_design_contextfor faithful, de-duplicated design context, andcomponent_map/token_map/icon_map, which join Figma data to your codebase so codegen reuses what you already have; plusdesign_diff, which reports what changed in a design against a saved baseline so you update only the affected code.
[!TIP] Your MCP client lists every tool at connect time, which is always the authoritative, up-to-date catalog.
Plugin
The Figma-side plugin isn't a black box. It shows every call as it happens, lets you inspect the exact payload sent to the model, and surfaces its own connection health.
And it follows your Figma theme, light or dark.
The window is yours to arrange. Drag the bottom-right corner to resize it. A taller panel keeps more of the log in view, and the size is remembered next time you open it. Or put it away: Run in background, in the panel header right under Figma's own ✕, hides the panel while the connection stays live, so a long-running agent keeps working. Run the plugin again to bring it back. The ✕ above it closes the plugin instead, connection and all.
How it works
Your MCP client launches the @figwright/mcp server and talks to it over stdio. The server relays each tool call over a local WebSocket to the Figwright plugin, which carries it out through Figma's Plugin API. Every agent runs its own server process; the processes elect a leader that holds the plugin connections, and the rest forward to it. The plugin runs in every file you open it in, so several agents can each work in their own file at once, and the whole path is built to ride out dropped sockets, leader handovers and long reads:
┌─────────────────────────────────────────────────────────────────────┐
│ MCP CLIENTS · each agent's client launches its own server │
│ Claude Code · Cursor · Claude · any MCP-capable client │
└─────────────────────────────────────────────────────────────────────┘
│ MCP protocol over stdio
▼
┌─────────────────────────────────────────────────────────────────────┐
│ @figwright/mcp · the server processes elect one leader │
│ │
│ LEADER (holds every plugin connection) │
│ • WebSocket relay on 127.0.0.1:3055, Host- and Origin-checked │
│ • routes each agent to the file it claimed with use_file, │
│ otherwise to the file the user was last active in │
│ • session resume: a dropped plugin has 30 s to reconnect, and │
│ calls bound for it wait instead of failing │
│ • "busy ≠ dead" heartbeat: a busy plugin isn't taken for dead │
│ • endpoints: /ws (plugins) · /ping (health) · /rpc (followers) │
│ /abdicate (hand over to a newer build) │
│ │
│ FOLLOWERS │
│ • forward tool calls to the leader over HTTP /rpc │
│ • retry a call caught in a leader handover │
│ • take over automatically if the leader exits, and ask an older │
│ leader to step down once it goes idle │
└─────────────────────────────────────────────────────────────────────┘
│ local WebSocket · msgpack (binary)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ FIGMA (desktop or browser) · one plugin per file it's open in │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Figwright plugin │ │
│ │ • UI (Vue 3 iframe): WebSocket client, heartbeat, reconnect │ │
│ │ • sandbox: executes Figma Plugin API calls │ │
│ │ – replays a retried write instead of applying it twice │ │
│ │ – long reads yield every ~40 ms to keep Figma responsive │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ │ Figma Plugin API │
│ ▼ │
│ Canvas │
└─────────────────────────────────────────────────────────────────────┘
By design Figwright is provider-first: rather than a fixed compiler pipeline, the tools surface honest design context and let the model generate code that matches your codebase. The figma-codegen skill encodes this approach.
Security
Figwright runs entirely on your machine: your client launches the server over stdio, the server relays to the plugin over a WebSocket on 127.0.0.1:3055, and nothing is sent anywhere else. The plugin uses only Figma's public Plugin API, so it reaches the file you have open and nothing beyond it.
Loopback is not on its own a boundary, since a web page you visit can still reach a local port, so the relay gates every request on two headers a page cannot forge: Host, which must name loopback (this is what stops DNS rebinding), and Origin, which admits the plugin's sandboxed handshake and refuses browsers everywhere else. The leader's HTTP endpoints additionally require a media type that cannot be sent without a CORS preflight. See MCP Security Best Practices for the wider picture, and SECURITY.md for Figwright's threat model, what is in and out of scope, and how to report a vulnerability privately.
Figwright is not a substitute for reviewing what your agent does. Its write tools change your Figma file and its export tools write files to paths the agent chooses; an agent acting on a malicious design or a prompt-injected instruction can misuse both. Your MCP client's tool-approval controls are the boundary that matters.
FAQ
Both come down to how your MCP client launches the server: it spawns the command directly, not through your interactive shell, so it inherits none of what your shell sets up. That bites hardest when Node is managed by a version manager (fnm, nvm, asdf, volta, mise), since those configure PATH and npm from shell hooks that only run in a real terminal. It is not specific to Figwright; it affects any npx-launched MCP server. There are two symptoms, with two different fixes.
command not found: the client can't find npx / node on its PATH.
-
Use an absolute path. In a normal terminal run
which npx(orwhich node) and use that full path ascommand:{ "mcpServers": { "figwright": { "command": "/Users/you/.local/share/fnm/node-versions/v26.x.x/installation/bin/npx", "args": ["-y", "@figwright/mcp@latest"] } } } -
Or pass
PATHthroughenv. If your client supports a per-serverenv, add your version manager'sbindirectory toenv.PATH.
-32000 / "Connection closed" / it just never connects: npx runs, but the server exits before the handshake.
npx … @latest re-resolves the package from the registry on every launch. In a directly-spawned environment that step can fail or stall (empty or different npm config, a corporate proxy or private registry that is not configured there, or no network), so the process dies before MCP connects and the client reports the connection as closed. (A missing node for the binary's shebang lands here too.)
The fix is to install the package so launch needs no registry fetch:
-
As a project dependency, the quickest unblock. Install it, then drop
@latestfrom your config. The@latesttag is what forces the registry round-trip; without it,npxuses the copy already innode_modules(a project-scoped config like Claude Code's.mcp.jsonruns from your project root):pnpm add -D @figwright/mcp # or: npm i -D @figwright/mcp{ "mcpServers": { "figwright": { "command": "npx", "args": ["-y", "@figwright/mcp"] } } } -
Or globally, pinned to the binary. Install once, then point
commandstraight at it, with nonpxand no per-launch resolution. Use the absolute path fromwhich figwright-mcp:npm i -g @figwright/mcp which figwright-mcp{ "mcpServers": { "figwright": { "command": "/absolute/path/to/figwright-mcp" } } }
The server is launched by your MCP client, so it only runs while that client is open. Check that:
- your MCP client is running and has Figwright configured (try a
ping); - the plugin is open in the same Figma app on the same machine (the relay is local-only,
127.0.0.1); - nothing is blocking local loopback connections (some firewall / security tools do).
The plugin's Debug tab lists both versions side by side, so a mismatch is visible in one place.
Mostly you don't need to look. The two halves update through different channels — the server re-resolves itself on every launch via npx @latest, while the plugin is a zip you imported by hand and then stop thinking about — so drifting apart is the normal state here rather than an edge case. It is also a silent one: a handler that predates an argument ignores it without erroring, so a write can report success having done only part of what was asked. When your plugin is old enough for that, the panel says so and tells you how to update (Updating has the steps), and every tool result tells your agent the result is unverified.
It stays quiet on a difference that cannot bite — a plugin a version behind a server that changed no arguments is fine — so when the warning does appear it is worth acting on.
No. Figwright talks to Figma through a plugin, so the free tier is enough. No Dev Mode seat or paid tier required.
It runs in both, with less available than in Figma Design, because those editors give plugins less rather than because Figwright holds anything back.
- Figma Design: everything.
- Dev Mode (Inspect panel): reads and exports only. Figma makes plugins read-only there, so screenshots, PDF export and every inspection tool work, while every write fails: nodes, pages, variables and styles alike. That suits the codegen direction; use Design mode to build. (The panel's own window controls — resize and Run in background — aren't there either: Figma owns that frame.)
- FigJam: frames, sections, shapes and text work; components, variables, styles and Motion don't exist in that editor, so the tools for them don't apply.
get_metadata reports the editor (editorType / mode), and any tool that fails because of the editor says so in its error, so an agent can re-plan rather than retry.
Yes. Several MCP servers can share a single plugin via leader/follower election: one leads, the others follow, with a graceful handoff if the leader goes away.
Yes, once each agent claims its file.
By default calls follow whichever file you last touched, so switching tabs switches what the agent sees — the right behaviour for one agent, and the wrong one for two, since the agent whose file isn't in front would silently get the other file's nodes. Whenever more than one file is open and an agent hasn't claimed one, every result it gets says so, so it can claim one before building anything on the wrong file.
list_files shows every file that currently has the plugin open, and use_file claims one for that agent:
> use the marketing site file
→ use_file({ fileName: "Marketing Site" })
The claim belongs to that agent's own server process, so it never affects the other agent, it survives closing and reopening the plugin panel, and calls keep reaching the file even while its tab sits in the background. That process is also the unit: one per MCP client, so the agents have to be separate clients — two editors, or two terminals. Everything inside one of them, subagents included, shares a server and therefore shares a claim. If two open files share a name (x and a second x), use_file refuses the name and asks for the sessionId that list_files prints, rather than guessing. Release it with use_file({ release: true }) to go back to following the foreground file.
Contributing
Contributions are welcome. See CONTRIBUTING.md for how to get set up and open a pull request, and AGENTS.md for the architecture, repo layout, tech stack, and conventions.
What's in the name
figwright follows the -wright tradition, an old English word for a maker or craftsman: a playwright writes plays, a shipwright builds ships, a wheelwright, wheels. The name is a nod to Playwright, which automates the browser. Where Playwright drives the browser, Figwright drives Figma, a maker of designs that both reads the canvas and crafts work back onto it.
Figwright MCP questions
How do I add Figwright MCP to Claude Code?
Run claude mcp add figwright -- npx -y @figwright/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Figwright MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Figwright MCP provide?
It exposes 135 tools, including ping, get_selection, get_document, get_node, get_nodes_info.
Does this require a Figma Dev Mode seat?
No, Figwright works with the free Figma tier by pairing with a Figma plugin instead of requiring a paid Dev Mode seat.
Can I use it with my existing code components?
Yes, Figwright detects your specific framework and styling system to reuse your existing components, tokens, and icons.
Is my design data sent to the cloud?
No, everything runs locally on your machine, including the server, the relay, and the plugin, ensuring designs are never sent anywhere.
Can multiple agents work on different files at once?
Yes, several agents can work simultaneously, each claiming its own open Figma file.