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:

```json
{ "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.

```js
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:

```json
{ "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 t