localfig

localfig

The Figma desktop app as an MCP server. localfig gives an AI agent the full Figma Plugin API on the file you have open — through a tiny dev plugin and a loopback HTTP bridge, entirely on your machine.

• Reads and writes. Frames, text, auto-layout, variables, components, image fills, exports, undo — anything the Plugin API can do, the agent can do.
• No Figma cloud API, no personal access token, no per-account quota.
• Zero dependencies. Node built-ins only. Nothing leaves your machine.
• Works with any MCP client that can launch a stdio server: Claude Code, Cursor, Windsurf, Cline, Claude Desktop and more.

MCP client  --stdio JSON-RPC-->  localfig  --http localhost:8765-->  Figma plugin  -->  Plugin API

Why localfig

	localfig	Official Figma MCP	REST-API servers	Fixed-command plugin bridges
Writes to the file	anything the Plugin API can	limited	no — the REST API cannot write nodes	a fixed menu of commands
Arbitrary Plugin API JavaScript	yes (figma_eval)	no	no	no
Quota / login	none	plan-dependent	token + rate limits	none
Tokens, styles, components read back	figma_tokens, figma_metadata	yes, incl. Code Connect	partial	rarely
Agent can see the design as an image	yes, inline in the response	yes	files or links, not inline	varies
Undo per agent step, change tracking	yes	no	no	no

Requirements

• Node.js 18 or newer
• The Figma desktop app — dev plugins cannot be imported in the browser
• An MCP client: Claude Code, Cursor, Windsurf, Cline, Claude Desktop, …

Install (once)

npx -y localfig --setup

That generates your local secret, writes the plugin to ~/.localfig/plugin/, registers localfig with every MCP client it finds on your machine, and prints the manifest path for the next step. --dry-run shows what it would do without touching anything, and --clients=cursor,vscode limits it to the clients you name. Prefer a clone? git clone https://github.com/LucasGorgal/localfig.git && cd localfig && node server.mjs --setup does the same.

Client	Where setup registers localfig
Claude Code	claude mcp add --scope user
Claude Desktop	claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code (Copilot agent mode)	user mcp.json
Cline (extension and CLI)	~/.cline/data/settings/cline_mcp_settings.json, or VS Code's extension storage on older versions
Gemini CLI	~/.gemini/settings.json
Codex	~/.codex/config.toml
opencode	~/.config/opencode/opencode.json
Zed	settings.json, under context_servers
LM Studio	~/.lmstudio/mcp.json

A client counts as installed when its config folder exists. Setup merges into existing files instead of replacing them: other servers and settings stay, an existing localfig entry keeps its env, and a .localfig.bak copy is written before any change. Files it cannot safely rewrite, such as a settings.json with comments, are left untouched and reported with the entry to paste. Restart any client that was already open.

For a client that is not in the list, add this to its MCP configuration:

{ "mcpServers": { "localfig": { "command": "npx", "args": ["-y", "localfig"] } } }

On Windows, use "command": "cmd", "args": ["/c", "npx", "-y", "localfig"] instead: most clients start servers without a shell, and npx is a .cmd script there.

Then import the plugin into Figma (once):

1. Open any design file in the desktop app. The Plugins menu only exists inside a file, not on the home screen.
2. Figma menu (the logo, top-left) → Plugins → Development → Import plugin from manifest… — or press Ctrl / (Cmd /) and type import plugin from manifest.
3. Pick ~/.localfig/plugin/manifest.json (the setup output prints the full path).

The manifest asks for two permissions — teamlibrary (library components and tokens) and currentuser (who is driving) — and registers a relaunch button.

Use (every session)

1. Open the file you want to work on.
2. Run the plugin: Ctrl / → localfig — or Ctrl Alt P (Cmd Opt P) to re-run the last plugin, or the Reconnect localfig button in the properties panel of a file it has run in. A small panel appears and says Connected to localfig once the MCP server is up. Leave it open.
3. Ask your agent to do Figma work. Every tool acts on the file where the plugin is running — there is no file key, which is why nothing touches the cloud.

Closing the panel (or the file) disconnects; re-run the plugin to reconnect. This is the one manual step: Figma provides no way to launch a plugin from outside.

Tools

Tool	What it does
figma_status	Plugin connected? File, page, selection, top-level frames, who is driving, and whether dynamic code execution is available
figma_eval	Run arbitrary Plugin API JavaScript in the file — the workhorse
figma_metadata	Structural dump of a subtree: ids, names, types, geometry, text. styles: true adds fills (hex), gradient stops, fonts, effects, auto-layout, bound variables, named styles and component info per node; css: true adds the CSS Figma computes per node
figma_tokens	Every local variable collection with its modes and per-mode values, plus paint / text / effect styles
figma_find	Search the current page or every page by type, layer-name regex and text regex
figma_changes	What changed since your last call — creations, deletions, property changes, per-node summary; edits made by tool calls are tagged and hidden by default, so this is what the person did in Figma meanwhile
figma_history	snapshot: save a named version (restore point). undo: revert the last tool call — every mutating call is checkpointed as one undo step
figma_library	Team library: list variable collections and their variables, import components / styles / variables by key, place instances
figma_export	Export nodes to PNG/JPG/SVG/PDF/JSON on disk. PNG/JPG come back inline as images; JSON (the subtree in Figma REST API shape) and SVG come back inline as text
figma_place_image	Put a local image into a node's fill. Any format the browser decodes — PNG, JPG, WebP, GIF, BMP, AVIF. Images over 4096px per side are downscaled automatically (maxSide)

figma_eval environment

Code runs inside the plugin sandbox, wrapped in an async function: top-level await and return both work.

const n = await figma.getNodeByIdAsync('10:59');   // sync getNodeById is unavailable (dynamic-page access)
await helpers.setText(n.findOne(x => x.type === 'TEXT'), 'new copy');
helpers.reveal(n);                                  // put it on the person's screen
return { id: n.id, w: n.width };                   // JSON-serialized back to the agent

Globals: figma and helpers.

• helpers.createText({characters, font: {family, style}, fontSize, color: '#hex', width, lineHeight, letterSpacing, textCase, textAlign, name, parent, x, y}) — loads the font and orders resize() before textAutoResize.
• helpers.setText(node, chars) — loads the node's real fonts, then sets characters. helpers.loadNodeFonts(node).
• helpers.set(node, props) — batch assign; layoutMode first, width/height via resize, sizing modes after.
• helpers.rgb('#rrggbb'), helpers.rgba('#rrggbbaa') — hex to the {r, g, b[, a]} fills want.
• helpers.reveal(nodes) — scroll and zoom the viewport to what you just made. helpers.notify(msg) — a toast.
• helpers.collection(name, [modes]), helpers.token(collection, name, type, value | {mode: value}), helpers.bind(node, 'fills' | 'strokes' | prop, variable) — create design tokens and bind properties to them, one line each.
• helpers.importComponent(key), helpers.instance(key, parent, props) — team-library components.
• helpers.query(root, sel) — minimal selectors: TEXT, [name=X], [name*=X], A B, a, b. helpers.createAutoLayout(dir, props).
• helpers.command(kind, payload) — run any typed command (tokens, metadata, find, changes, export…) from inside a script: (await helpers.command('tokens', { collection: 'Brand' })).result.

Plugin API gotchas the helpers protect you from

• resize() on a TEXT node resets textAutoResize to NONE; on an auto-layout frame it sets both sizing modes to FIXED. Resize first, then set the sizing.
• Return plain data from figma_eval. Real Figma nodes are collapsed to {id, name, type} so a stray node reference cannot flood the result — use figma_metadata to inspect a subtree.
• Load fonts before any text mutation.
• figma.notify() works here (the cloud MCP blocks it).

Design-system awareness

figma_tokens returns the file's variables the way a design system thinks about them:

{ "collections": [{ "name": "Brand", "modes": ["Light", "Dark"], "defaultMode": "Light",
    "variables": [{ "name": "color/bg", "type": "COLOR", "values": { "Light": "#ffffff", "Dark": "#04060c" } },
                  { "name": "space/md", "type": "FLOAT", "values": { "Light": 16, "Dark": 16 } },
                  { "name": "color/accent", "type": "COLOR", "values": { "Light": "{color/blue-500}", "Dark": "{color/blue-300}" } }] }],
  "styles": { "paint": [...], "text": [...], "effect": [...] } }

figma_metadata with styles: true then reports, per node, boundVariables (which token drives each property), fillStyle / textStyle / effectStyle names, and for instances the main component and its componentProperties; css: true adds the CSS Figma computes for each node. Together they let an agent build on a design system instead of hard-coding values — and hand code off from a real file.

Images

• In: figma_place_image sends the file's bytes to the plugin UI, which is a full Chromium iframe. It decodes any browser-supported format, downscales to maxSide (default 4096, Figma's hard limit) with high-quality smoothing, converts non-native formats to PNG, and hands the result to the main thread. The tool result reports what happened (prepared).
• Out: figma_export writes files to ~/.localfig/exports/ and attaches PNG/JPG (≤ 2 MB each) to the result as images, so the agent sees the render without another call. JSON exports the subtree in Figma REST API shape.

Undo, versions and change tracking

Every mutating tool call is checkpointed with figma.commitUndo, so it lands in the file's undo history as one step a person can Ctrl+Z (the most recent call is committed 60 s after it finishes, or at the next call). Within that window figma_history {action: "undo"} reverts the last call from the agent side — triggerUndo reverts to the last checkpoint — and {action: "snapshot"} saves a named version before risky edits. The plugin also records node changes on every page it has seen (Figma delivers them batched, after the fact): figma_changes returns what changed since a seq, with edits caused by tool calls tagged byPlugin by a time-window heuristic and hidden by default — the agent can notice what the person changed in Figma between calls instead of overwriting it.

Multiple sessions

The first localfig process owns the bridge port; later ones detect it via /health, run as clients, and proxy through it — same tools either way. If the owner dies, the next tool call on a client re-binds the port and takes over ("re-election" in the log); the plugin re-registers when it reconnects.

Files and configuration

~/.localfig/
  token            local secret (generated on first run)
  plugin/          manifest.json + code.js + ui.html — import THIS manifest into Figma
  exports/         where figma_export writes

Variable	Default	Notes
LOCALFIG_HOME	~/.localfig	Where the token, plugin and exports live
LOCALFIG_PORT	8765	Also change networkAccess in the manifest and re-import the plugin
LOCALFIG_OUT	~/.localfig/exports	Where figma_export writes

node server.mjs --help lists the flags.

Security

The bridge binds loopback only (127.0.0.1 and ::1). Every endpoint except /health requires a 32-hex secret generated on first run into ~/.localfig/token and baked into ~/.localfig/plugin/ui.html. Edit plugin/ui.template.html in the package, never the generated ui.html. Nothing is sent to any server.

Design notes

• Why a plugin? It is the only local surface with full read/write access to an open Figma document. The REST API is cloud, needs a token, and cannot write nodes.
• Why HTTP long-poll and not WebSocket? The plugin main thread has no network at all; only the UI iframe does. Long-poll needs no dependency and no framing code, and http://localhost is exempt from mixed-content blocking. Figma's manifest validator rejects raw IPs in networkAccess, hence localhost — and the IPv6 mirror listener, because Windows resolves localhost to ::1 first.
• Binary stays binary on the plugin channel. Exports leave as POST /blob; images enter via GET /asset into a Uint8Array. Only JSON goes through the command channel. (Renders are base64-encoded once, in the MCP result, where the protocol requires it.)
• Why a home directory? The package may live in the npx cache or a read-only global install; the plugin folder you import must not move when the package updates, and per-user state must not live in a package.

Platform notes

Developed and tested on Windows 11 with the Figma desktop app. macOS and Linux should work unchanged — Node built-ins only, no native code — but have not been exercised yet. Reports and fixes welcome.

Test

node test-e2e.mjs

Spawns the server in an isolated home, speaks MCP over stdio, and impersonates the plugin over HTTP — covering the handshake, all ten tools, file round-trips, inline images, owner re-election, and setup against sandboxed MCP client configs, without Figma running. 55 assertions.

Layout

server.mjs               MCP (stdio) + bridge (http), single process; --setup, --help
plugin/manifest.json     copied to ~/.localfig/plugin on start
plugin/code.js           main thread: executes commands against the Plugin API
plugin/ui.template.html  UI source; token/port get baked into ~/.localfig/plugin/ui.html
test-e2e.mjs             end-to-end test without Figma

License

MIT — see LICENSE.