Writable Figma MCP Bridge (Figma Connector)

Provides a universal write channel for any MCP-compatible AI client to execute arbitrary JS inside the Figma sandbox — local, no cloud services, localhost-only by default.

Works with most desktop AI assistants, which can read and write Figma files after connecting through standard MCP.

🌐 Language: 中文 | English

1. Introduction

The Figma Connector is a local MCP service + Figma plugin combo that lets any desktop AI assistant read and modify the Figma file you are currently editing through the standard MCP protocol. The entire pipeline runs on your machine (127.0.0.1) and does not rely on any external API or cloud service.

The design philosophy is "local-first, auditable": the whole pipeline runs only on your machine (127.0.0.1), requires no external API Key or OAuth, and the code is small and fully reviewable.

Related MCP server: Local Figma MCP Bridge

2. Core Features

• Writable MCP bridge: exposes figma_run_js as a trusted write entry point to MCP clients.

• Safe writes: snapshots nodes before every task; if an error occurs, automatically rolls back newly created nodes from that run.

• Design system first: built-in helpers (design system indexing, component import, variable binding, style application, etc.) to avoid hardcoding.

• Status visualization: the panel shows three states in real time — "waiting for task / reading / writing" (blue = writing, green = reading).

• Aim button: one-click jump to and select the target node for each link (with adaptive zoom).

• Duplicate link notice: when you paste an existing link, a bottom toast says "This link already exists" to prevent accidental duplicates.

• Multi-plugin protection: GET /health lists all polling windows; FIGMA_WRITER_STRICT=1 can enforce single-window exclusivity to avoid writing the wrong file in multi-window setups.

3. How It Works

AI 客户端 (Claude / WorkBuddy)
        │  MCP (http://localhost:8788/mcp)
        ▼
本地 MCP 服务 (server.mjs)  ── 任务入队
        │
        ▲ 轮询 GET /plugin/job
        │
Figma 插件 (code.js 运行在 Figma 沙箱)  ── 在 Figma 内执行读/写
        │ 结果 POST /plugin/result
        ▼
本地 MCP 服务  ── 把结果回传给 AI

1. The AI calls the server via MCP (http://localhost:8788/mcp).

2. The server enqueues the task.

3. The Figma plugin polls /plugin/job, picks up the task, and executes it inside Figma (only allowed to operate on the currently open file).

4. The plugin reports the result back to the AI via POST /plugin/result.

⚠️ The actual read/write boundary of the plugin is "whichever document is currently open in Figma." The link selected in the panel is used to declare "which file is being operated on" and report that to the server/AI; if the two disagree, reads and writes are still scoped to the currently open file.

4. Environment Requirements

• Node.js ≥ 18 (required to run the local MCP server; download from nodejs.org).

• Figma desktop app (the web version does not support local plugins/dev mode).

• No API key need, no OAuth, no internet access required (the server runs only on 127.0.0.1).

5. Quick Start

1. Start the Local Server

Option A: Command line (recommended, for easy log viewing)

cd writable-figma-mcp-bridge
node server.mjs

Option B: Double-click the launcher

• macOS: double-click start.command in the repository

• Windows: double-click start.bat

Double-clicking the script optionally starts node server.mjs (minimized/background) without typing commands. Precondition: Node.js is installed on this machine.

After startup the default address is 127.0.0.1:8788, reachable only from this machine, exposing the single tool figma_run_js by default(MCP) tool.

2. Install the Plugin Manually in Figma & (important)

Figma plugins must be manually installed against the repository's manifest.json. Steps:

1. Open Figma desktop (officially supports macOS / Windows).

2. Open any Figma design file.

3. In the top menu: Plugins → Development → Import plugin from manifest….

4. Select this repository's manifest.json in the file picker (located at writable-figma-mcp-bridge/manifest.json).

5. Run it via the menu Plugins → Development → Writable Figma MCP Bridge.

6. In the panel that appears, click "Start" to connect to the local server.

As long as "Start" is bright, and the status reads "Waiting for task…", the plugin is connected. After that, all. After that, all read/write tasks dispatched by the AI via MCP will act on the file you currently have open. Then all read/write via.

3. Configure the MCP Client

Normally, as long as the local server port is reachable and the Figma plugin is installed, a client can connect directly with no extra configuration.

If you cannot connect, add the following configuration manually in your MCP client (point the URL at the actual port):

{
  "mcpServers": {
    "figma-writer": {
      "type": "http",
      "url": "http://localhost:8788/mcp"
    }
  }
}

Default port 8788. If the port is occupied, the server automatically picks a subsequent port and the startup log shows the actual address. If the port changes, edit the port in the URL above to match.

6. Feature Details

Link Management

• Paste a Figma file link in the input at the top and click "Add" to add it to the list below.

• Each row can be "selected" as the currently active link (reported to the server during polling), and includes an "aim" button.

• When pasting a duplicate, a red floating toast slides up at the bottom saying "Link already exists".

Aim (Aim)

The crosshair icon on the right of each link row: clicking it parses the node-id and navigates to that node's page(tab) in Figma, then it will use the "fit zoom" and selects the node. If the link points to another file (the node is not found in the currently open file), it clearly shows "Link may point to another file".

Status Indicator

The status dot in the upper right corner of the panel changes with each task:

• Gray「waiting for task…」: idle

• Blue「AI currently writing…」: write operation detected

• Green「AI currently reading…」: read operation detected

Automatic Rollback

Before each figma_run_js, the document nodes are snapshotted; if the execution throws, newly created nodes from that run are automatically deleted in the diagram, and the deleted count is reported. Modifications to existing nodes are not rolled back automatically beyond that (you can use Cmd/Ctrl+Z in Figma to undo).

7. Security

8. Environment Variables

9. Available Helpers (usable inside figma_run_js)

figma_run_js injects: figma (Figma API), args (structured), and helpers (safe helpers).

• helpers.loadFont(fontName)

• helpers.ensureTextFontLoaded(textNode, fallbackFontName)

• helpers.paint(value, theme) / helpers.hexToRgb(hex) / helpers.rgbToHex(rgb)

• helpers.normalizeHex(value, theme)

• helpers.findVariable(nameOrKey, resolvedType)

• helpers.indexDesignSystem(options)

• helpers.cloneReferenceNode(selector, options)

• helpers.importComponentByName(nameOrKey, options)

• helpers.applyTextStyle(textNode, styleName)

• helpers.applyPaintStyle(node, styleName, field)

• helpers.bindVariable(node, field, variableName, fallbackValue, resolvedType)

• helpers.bindFillVariable(node, variableName, fallbackValue) / helpers.bindStrokeVariable(...)

• helpers.findNodes(selector) / helpers.getNode(id)

• helpers.summarizeNode(node, depth) / helpers.inspectNodeAppearance(node)

• helpers.validateCanvas(options)

Avoid optional chaining ?. and nullish coalescing ?? in code passed to figma_run_js — Figma's plugin runtime may reject them.

10. Available Helpers (inside figma_run_js) note

11. License

MIT License.