Reqwise Figma MCP

An MCP server that lets AI agents read and draw on the Figma canvas — safely.

Reqwise Figma MCP pairs a local MCP server with a companion Figma plugin. Point Claude Code, Cursor, or any MCP-capable agent at it, and the agent can inspect a Figma file and draw into it by executing JavaScript against a figma.* proxy API — with the plugin layer catching the mistakes that usually turn "AI draws a screen" into "AI draws an overflowing, half-clipped mess."

It exists because the current generation of Figma MCPs make agents responsible for discipline they don't have: remembering never to overlay a semi-transparent frame, re-declaring token maps every call, manually computing x/y offsets, eyeballing screenshots to check for clipping. Reqwise moves that discipline into the server and plugin, and gives the agent a structured way to verify its own work.

Why this one

See ARCHITECTURE.md for the full design rationale and the root-cause fixes behind these defaults.

Quickstart

1. Install

git clone https://github.com/<you>/reqwise-figma-mcp.git
cd reqwise-figma-mcp
npm install
npm run build

This builds the server to dist/ and the plugin bundle to plugin/code.js.

2. Register the MCP server

claude mcp add reqwise-figma -- node /absolute/path/to/reqwise-figma-mcp/dist/server/index.js

(See docs/INSTALL.md for Cursor and Claude Desktop JSON config, plus npx-based setups.)

3. Import the plugin into Figma Desktop

Figma Desktop → menu → Plugins → Development → Import plugin from manifest… → select plugin/manifest.json from this repo. Run it from Plugins → Development → Reqwise Figma MCP and keep its window open.

4. Check the connection

Ask your agent to call figma_status. A healthy connection looks like:

{
  "pluginConnected": true,
  "mode": "leader",
  "port": 38470,
  "plugin": { "version": "0.1.0", "apiVersionMatch": true, "fileName": "My File", "pageName": "Page 1" },
  "hints": ["All systems nominal. Draw with figma_write; verify with figma_read layout_audit."]
}

If pluginConnected is false or a hint mentions a version mismatch or missing heartbeat, see the troubleshooting table in docs/INSTALL.md.

pluginConnected is tri-state: true/false are measured, null means unknown — a follower process could not query the leader (see statusSource and statusError). Treat null as "no information", not as disconnected: operations may still be forwarding fine, so do not reinstall or restart the plugin on the strength of a null.

Tools

Full parameter reference for every operation and every figma.* method: docs/TOOLS.md.

Example: figma_write

// Set tokens once — they persist in this session's `state.tokens`.
await figma.setupTokens({
  colors: { primary: "#2563EB", surface: "#0B0B0F" },
  numbers: { "radius-md": 8 },
});

// Draw a card with wrapping text, reusing the parent's width.
const card = await figma.create({
  type: "FRAME", name: "Card", parentId: state.rootId,
  width: 320, layoutMode: "VERTICAL",
});
await figma.applyVariable(card.id, "fills", "surface");
await figma.create({
  type: "TEXT", parentId: card.id, wrap: true,
  characters: "A long paragraph that must wrap inside the card.",
});

// Verify before screenshotting for a human.
const audit = await figma.layoutAudit(card.id);
if (audit.summary.issues.length) console.warn(audit.summary.issues);

Example: generate design.md

Ask your agent to call:

{ "op": "generate_design_md", "params": { "depth": 3, "includeAnatomy": true, "includeScreens": true } }

The response contains a source-grounded design.md: extraction coverage, colors, typography, observed layout frequencies, screen composition evidence, local and remote component usage, exact node ids/keys/variant ids/property keys, ready-to-run instantiate examples, reuse rules, responsive evidence and known gaps. Save it in the target codebase before asking the agent to create UI from an existing Figma component system. Facts are separated from observations and unknown UX semantics. For a very large file, tune maxComponents, maxScreens, maxInstances or maxOutputChars; output limits omit complete sections rather than cutting Markdown mid-table/code-block.

Architecture

MCP client (Claude Code / Cursor)
      │ stdio (MCP)
      ▼
 Reqwise MCP server (Node ≥ 18, TypeScript)
      │  owns HTTP+WS server on localhost:38470 (fallback +1..+9)
      │    GET  /health    → diagnostics JSON
      │    POST /rpc       → follower → leader forwarding (auth token)
      │    WS   /ws        → Figma plugin UI connection
      ▼
 Figma Desktop plugin
   ├── ui.html   (WebSocket client, heartbeat, reconnect w/ backoff)
   └── code.js   (Plugin API executor, safe-default handlers)

Every operation — leader-direct or follower-forwarded — passes through one validateOperation() choke point before it reaches the plugin. Full topology, the leader/follower protocol, and the 15 safe-default fixes are documented in ARCHITECTURE.md.

Documentation

• docs/INSTALL.md — detailed setup, MCP client configs, troubleshooting
• docs/TOOLS.md — full tool + figma.* API reference, error codes
• docs/MIGRATION.md — migrating from figma-ui-mcp
• docs/RECIPES.md — practical cookbook
• ARCHITECTURE.md — design goals and internals

License

MIT © 2026 Hoang Phan. See LICENSE.