Neumo Toolkit (Figma Plugin) — Setup Guide
How to install and connect @kofile/neumo-toolkit — the Figma desktop
plugin that bridges the Neumo / GDS design system into Figma so Claude and other
external editors can call Figma tools over a live WebSocket connection (via
figma-console-mcp).
It is the design-side counterpart to
@kofile/neumo-mcp-server: the MCP server answers
questions about the design system; the toolkit gives an assistant a live
connection into Figma for design-to-code work.
This is a Figma plugin, not an MCP server. You don't register it in
.mcp.json. You install the npm package, import its manifest into the Figma desktop app, and connect it to a runningfigma-console-mcpbridge.
Table of contents
- How it differs from the MCP server
- Prerequisites
- 1. Install the package
- 2. Import the plugin into Figma
- 3. Start the bridge server
- 4. Connect
- Updating
- Troubleshooting
How it differs from the MCP server
@kofile/neumo-mcp-server |
@kofile/neumo-toolkit |
|
|---|---|---|
| What it is | MCP server (stdio) | Figma desktop plugin |
| Who runs it | Your AI client (e.g. Claude Code) | Figma loads it |
| Wired up via | .mcp.json |
Import manifest in Figma |
| Talks over | stdio | WebSocket → figma-console-mcp (ports 9223–9232) |
| Purpose | Query DS components/tokens, run audits | Live design↔code bridge into Figma |
The two are complementary — install both for the full workflow.
Note:
figma-console-mcp(southleft) is a separate bridge from the official Figma MCP server. This toolkit rides onfigma-console-mcpspecifically.
Prerequisites
- Figma desktop app (plugin development requires the desktop app, not the browser)
- Node.js ≥ 18 — to run the
figma-console-mcpbridge - Access to the
@kofilenpm scope
1. Install the package
You don't need to clone the design-system monorepo — the published package ships
the built dist/ + manifest.json, and Figma resolves the plugin files relative
to the manifest.
npm install --save-dev @kofile/neumo-toolkit # pin a version, e.g. @kofile/neumo-toolkit@0.1.0
This installs the plugin at node_modules/@kofile/neumo-toolkit/ with:
manifest.json ← the file you point Figma at
dist/code.js ← plugin main thread (Figma sandbox)
dist/ui.html ← iframe UI shell
dist/ui.js ← tab nav + Bridge WebSocket client
This is a Figma-side install, not project-side. Importing the manifest registers the plugin in your Figma desktop app globally — it isn't scoped to this repo. The repo only matters because that's where
node_modules(and thus the manifest path you point Figma at) lives.
2. Import the plugin into Figma
In the Figma desktop app:
- Plugins → Development → Import plugin from manifest…
- Select the manifest at:
<your-project>/node_modules/@kofile/neumo-toolkit/manifest.json - Run Neumo Toolkit from the Plugins → Development menu.
The plugin opens with three tabs: Bridge (the WebSocket connection), Tokens, and Components (the latter two are placeholders in v0.1).
3. Start the bridge server
The Bridge tab connects to a running figma-console-mcp server. Normally your
editor starts it for you from .mcp.json (see
Connect Figma to code); to run one by hand:
npx figma-console-mcp
It listens on ws://localhost:9223 by default and rolls forward
(9224, 9225, …, up to 9232) if a lower port is already in use — a second
editor, a second Figma window, or a stale server from an earlier session.
You don't need to know which port it took. The plugin finds it.
4. Connect
Open Neumo Toolkit in your file. With the port set to Auto (the
default), the plugin checks every port from 9223 to 9232 when it opens and
connects to each figma-console-mcp server it finds. STATUS shows which
ports it connected to, for example Connected on 9224.
"Connected" means the server answered, not just that a socket opened. The plugin waits for the server's hello before showing it as connected.
It connects to every server it finds, not just the first one. An old server from an earlier session usually holds the lowest port. If the plugin stopped there, the server your editor is actually using would never get a connection.
To confirm from the shell, ask the server your editor is using, on its port:
curl -s http://localhost:9223/health # → "connectedClients": 1
You're now bridged. Claude and other external editors can call Figma tools against this file.
Forcing a port. Pick a number in the Port dropdown to connect to that port only. Switch back to Auto to scan again. The plugin remembers your choice, so if Auto stops working, check you haven't left a port selected.
Updating
npm install --save-dev @kofile/neumo-toolkit@latest
Then reload the plugin in Figma (re-run it, or Plugins → Development → reload). The bundled plugin code is a snapshot from publish time, so bump the package to get new features/fixes.
Troubleshooting
🔴 STATUS: "Not found"
What it means: no figma-console-mcp server answered anywhere on 9223–9232
(or on the one port you forced). The hint under the dropdown says which.
Fix:
- Check whether a server is running at all:
No output means nothing is running. Start your editor's MCP session (orlsof -nP -iTCP -sTCP:LISTEN | grep -E ':92(2[3-9]|3[0-2])'npx figma-console-mcp), then click Connect. - If a forced port is selected in the dropdown, switch it back to Auto.
Connected, but the editor still can't reach Figma
The plugin found a server, but not the one your editor is using. Run
curl -s http://localhost:<port>/health on the editor's port. If it reports
"connectedClients": 0, that server started after the plugin connected, so
click Connect to scan again.
Leave
FIGMA_WS_PORTunset, or set it to9223. The server only uses the port you pin and the nine above it, and Auto scans exactly 9223–9232. If you pin it lower (older docs said9220), the server binds a port Auto never checks. If you pin it higher, it can fall forward past 9232, which Figma doesn't let the plugin reach.
Plugin doesn't appear in Figma
- Confirm you used the desktop app (browser Figma can't import dev plugins).
- Re-import: Plugins → Development → Import plugin from manifest… and select
node_modules/@kofile/neumo-toolkit/manifest.json. - Confirm
dist/code.jsanddist/ui.htmlexist (they ship in the package).
Connection succeeds but selection/variables don't update
The UI iframe owns the WebSocket; the plugin main thread (code.js) brokers
anything needing the Figma API. Make sure a file is open and an element is
selected — the CURRENT SELECTION panel reflects the active selection.
Bridge: figma-console-mcp on ports 9223–9232. The plugin has found it
automatically since UX-2596; earlier versions needed the port picked by hand.