10x-variables-mcp

10x-variables-mcp

MCP server for the 10x Variables Figma plugin. Lets AI agents (Claude Code, Cursor, and any MCP client) manage variable collections, variables, JavaScript expressions, external libraries, reusable helpers, and the update interval inside your Figma document.

Setup

1. Add the server to your MCP client config:

   {
     "mcpServers": {
       "10x-variables": {
         "command": "npx",
         "args": ["-y", "10x-variables-mcp"]
       }
     }
   }
   

2. In Figma, open the 10x Variables plugin and enable Enable agent control (MCP) in plugin Settings. The status line shows "Connected to agent" when the link is up.

How it works

The server exposes 20 MCP tools over stdio and hosts a localhost WebSocket server (default port 38472, override with TENX_MCP_PORT). The WebSocket server binds to 127.0.0.1 only and rejects connections from web pages — only the Figma plugin and local processes can reach it. The plugin's UI dials into that socket and relays commands into the plugin. That means:

• The plugin window must stay open in Figma. If it isn't, tools return [PLUGIN_NOT_CONNECTED] with recovery instructions. The only exception is get_expression_docs, which is answered by the server itself.
• Commands run one at a time in each plugin (strict FIFO), so mutations never interleave.

Multiple documents

Every open Figma document with the plugin running is its own connected instance, and agents can work with several at once:

• get_status (no arguments) lists every instance with its id and document name.
• While more than one instance is connected, every other tool call must pass the optional instance argument (a document name or instance id) — unqualified calls fail with [AMBIGUOUS_INSTANCE] listing the choices, so a mutation can never land in a document the agent didn't name.
• Every result is stamped with the instance it came from.
• Variable/collection ids are file-scoped; agents are instructed never to reuse ids across documents.

Dead connections are reaped by a WebSocket ping every 30 s.

Tools

remove_variables and remove_collection are destructive and permanently delete content — agents are instructed to confirm with you first. remove_variables deletes in order and stops at the first error; earlier deletions stay applied, and the response's removedVariableIds lists exactly which ids were deleted.

get_expression_docs teaches the agent how to write expressions: topic guide (default) covers expression shape, $ / $$ / $this reference syntax, built-in globals, color semantics, and gotchas; topics colordx and culori return the full TypeScript API of the built-in color libraries — the same generated definitions the plugin's expression editor uses, so they never drift from the runtime.

License behavior

get_status reports a license block: licensed, expressionVariables, freeLimit, evaluationActive, and a purchase link when unlicensed. On the free tier, expression evaluation pauses when the document exceeds the free limit; expression writes (set_expression, create_variable with an expression) then return an error — the expression is stored but won't evaluate until the plugin is licensed.

Development

yarn install
yarn test    # Jest suite (broker + tools)
yarn build   # tsc → dist/

The wire protocol is shared with the plugin source at ../src/shared/mcp/protocol.ts.