← Neumo Design System docs

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 running figma-console-mcp bridge.


Table of contents


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 on figma-console-mcp specifically.


Prerequisites


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:

  1. Plugins → Development → Import plugin from manifest…
  2. Select the manifest at:
    <your-project>/node_modules/@kofile/neumo-toolkit/manifest.json
    
  3. 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:

  1. Check whether a server is running at all:
    lsof -nP -iTCP -sTCP:LISTEN | grep -E ':92(2[3-9]|3[0-2])'
    
    No output means nothing is running. Start your editor's MCP session (or npx figma-console-mcp), then click Connect.
  2. 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_PORT unset, or set it to 9223. 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 said 9220), 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

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.