Connect Figma to code
To build from a design with an AI assistant, the assistant needs a live line into Figma — to read the frame, its structure, and its token bindings. This is the setup we use, and it's the first thing to get working before any design-to-code build (it's what powers Step 0 of the demo build logs).
There are two ways to connect. We use the first (the Neumo Toolkit bridge); the second (the official Figma MCP) is a good read-only alternative.
| Neumo Toolkit + figma-console-mcp (what we use) | Official Figma MCP (alternative) | |
|---|---|---|
| Direction | Live, two-way — read selection/variables, run code, write back | Mostly read (design → code) |
| Setup | Install our plugin + run the bridge | Enable Figma's MCP server |
| Best for | The full design↔code loop | Quick read-only design/token pulls |
Path A — Neumo Toolkit + figma-console-mcp (what the demos use)
The Neumo Toolkit is our Figma plugin. It wraps
figma-console-mcp and opens a
live WebSocket bridge between the Figma desktop app and your AI client, so the
assistant can call Figma tools against the file you have open.
The connection has three pieces: the plugin (in Figma), the bridge + MCP
server (figma-console-mcp), and your AI client (Claude Code).
Claude Code ⇄ figma-console-mcp (MCP server + Desktop Bridge) ⇄ Neumo Toolkit plugin ⇄ your Figma file
(stdio) (WebSocket :9223–9232)
In code (your AI client)
Register
figma-console-mcpas an MCP server so Claude gets its tools. In your project.mcp.json:{ "mcpServers": { "figma-console-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "figma-console-mcp@1.35.0"], "env": { "FIGMA_WS_PORT": "9223" } } } }Pin the version. Floating on
@latestonce broke the Toolkit's handshake, and the Toolkit reports a matching version to the server when it registers. Keep the two in step — see Keeping the version pin in sync.FIGMA_WS_PORTis a preference, not a guarantee. It makes the usual case predictable, but if 9223 is taken the server still falls forward. That is fine, because the plugin scans for it. Keep it at9223. The server only uses the port you pin and the nine above it, and the plugin scans exactly 9223–9232. Any other pin moves the server outside what the plugin checks.Run the bridge.
figma-console-mcpexposes a Desktop Bridge over WebSocket onws://localhost:9223, rolling forward to9224…9232if a port is busy. Your editor starts it from.mcp.jsonwhen the session opens (/mcpshows it connected). You don't need to note the port, because the plugin finds it.
In Figma
Install the toolkit:
npm install --save-dev @kofile/neumo-toolkitIn the Figma desktop app (plugin dev needs desktop, not browser): Plugins → Development → Import plugin from manifest… → select
node_modules/@kofile/neumo-toolkit/manifest.json.Open your design file, then run Neumo Toolkit from Plugins → Development.
The plugin's Bridge tab connects by itself. With Port on Auto, it scans 9223–9232 and connects to every
figma-console-mcpthat answers. STATUS showsConnected on <port>. The pill only turns green after the server has answered, not just because a socket opened.
Verify + use it
- In Claude Code,
/mcpshould list figma-console-mcp as connected. - With a file open and the bridge green, the assistant can call the
figma-console-mcptools — e.g. read the current selection, read variables (figma_get_variables), and screenshot a node (figma_take_screenshot/figma_get_screenshot) — against the live file.
Keeping the version pin in sync
figma-console-mcp is pinned in two places, and only one of them is in git:
| Where | What it pins | Tracked? |
|---|---|---|
apps/neumo-toolkit/src/bridge-protocol.ts → BRIDGE_PLUGIN_VERSION |
the version the plugin reports when it registers | yes |
your .mcp.json → figma-console-mcp@x.y.z |
the server you actually run | no — gitignored |
Because .mcp.json carries machine-specific paths and credentials it is
gitignored, so no PR can update it for you. A bump PR moves the tracked
pin; you move yours by hand.
Check where we stand at any time:
node scripts/check-bridge-protocol.mjs
It reads the pin, asks npm what is current, downloads both versions, and
reports what the bridge protocol gained or lost in between — plus which
server-sendable methods the Toolkit implements. --json for machine output,
--markdown <path> for a PR body.
A weekly Bridge Protocol Check workflow runs the same script and opens one
PR (branch chore/bridge-protocol-bump, force-updated rather than duplicated)
when we are behind, with the protocol diff in the body.
Adopting a bump:
- Update
.mcp.jsonto the new version and restart your MCP client. npx nx build neumo-toolkit.- Re-import
apps/neumo-toolkit/manifest.jsonin Figma Desktop. - Open the Bridge tab, let it connect, and confirm the server reports
"connectedClients": 1(curl -s http://localhost:<port>/health). - Run one
figma_executeand one screenshot round-trip.
Steps 3–5 are why the PR is never auto-merged: nothing in CI can confirm a handshake inside Figma Desktop.
What the pin does not protect you from. The Toolkit implements 3 of the
73 bridge methods the server can send. Anything else fails as Unsupported bridge method — regardless of version. That is coverage, not drift: the
protocol surface was identical from 1.35.0 through 1.40.9, so upgrading does
not add methods the Toolkit handles. Widening that set is separate work.
Troubleshooting
If STATUS reads Not found, no server answered on 9223–9232. Start your
editor's MCP session, then click Connect. Also check the Port dropdown
is on Auto, since a port forced earlier is remembered. To confirm the
editor's server has the plugin, run curl -s http://localhost:<port>/health and
look for "connectedClients": 1. Full troubleshooting is on the
Toolkit page.
Path B — Official Figma MCP (read-only alternative)
If you just need to read a design (design → code) and don't need the live write-back loop, Figma's own MCP server works well. Two flavors:
- Remote (recommended, all plans):
https://mcp.figma.com/mcp. Auth via a Figma personal access token (file:read). No Figma-side setup. - Desktop / Dev Mode (paid Dev/Full seat): the Figma desktop app runs a local
server at
http://127.0.0.1:3845/mcp. Toggle Dev Mode → enable MCP server in the right sidebar. This flavor adds selection-scoped context.
In the client
# remote
claude mcp add --transport http figma https://mcp.figma.com/mcp
# desktop (Figma open, Dev Mode MCP enabled)
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
.mcp.json equivalent:
{ "mcpServers": { "figma": { "type": "http", "url": "https://mcp.figma.com/mcp" } } }
claude mcp list should show it connected.
Point it at a design
From a Figma node URL …/design/<fileKey>/<name>?node-id=1-2, the fileKey is
the slug after /design/ and the nodeId is 1-2 (→ 1:2). Then:
get_screenshot— a PNG of the nodeget_design_context— reference code + contextget_variable_defs— the node's variable/token bindings (the ground truth for aligning to tokens — see the demo write-up's Pass 5)get_metadata— lightweight structure (node ids/types/sizes)
Notes
- Remote needs a Figma account + PAT; desktop needs a paid Dev/Full seat + Dev Mode enabled + the desktop app running.
- Common failures: MCP not enabled in Figma, wrong URL, missing
node-id, or the desktop app closed. Verify withclaude mcp list.
Which should I use?
- Building against the design system, iterating live, or writing back to Figma → Path A (Neumo Toolkit). It's the full loop and what our demos use.
- A quick, read-only design/token pull → Path B (official Figma MCP), especially the remote server (works on any plan, just needs a token).
You can have both configured; they don't conflict.