figma-tunnel-mcp

Control and export from Figma using any MCP client (Claude Code, Cursor, …) over a local WebSocket bridge — optionally exposed to the internet via a Cloudflare tunnel.

Fork of sonnylazuardi/cursor-talk-to-figma-mcp with practical additions:

• Fixed channel (figma) instead of a new random one on every reconnect — clients and tunnels always know the channel.
• Background mode — a Windows launcher that starts Figma with render-throttling disabled and minimized, so image export works while Figma is hidden and never steals your focus.
• Raw-WebSocket helpers — export/query nodes without even running the MCP server.
• "Export All" plugin — one click dumps the whole file (PNG + SVG + original image fills + full layer JSON) into a single ZIP.

What's in here

Path	What it is
src/talk_to_figma_mcp/	MCP server (50+ Figma tools)
src/socket.ts	WebSocket relay (port 3055)
src/cursor_mcp_plugin/	Figma plugin (the bridge) — fixed channel figma
Start-FigmaBg.ps1 / Start-FigmaBg.vbs	Windows launcher: Figma in background, no throttling, minimized
figma-save.mjs	Download node renders to PNG files — zero deps, batch, local or via tunnel
_export_node.cjs	Older single-node PNG exporter via raw WS (needs bun install)
_verify.cjs, _export_probe.cjs	Raw-WS test / diagnostic clients
figma-export-plugin/	Standalone "Export All" plugin (PNG + SVG + images + JSON → ZIP)

Setup

Prereqs: Bun, Node.js, the Figma desktop app (Windows for the background launcher).

1. Install deps: bun install
2. Start the relay and keep it running: bun socket → listens on ws://localhost:3055
3. (optional) add the MCP server to your client, e.g. Claude Code: claude mcp add TalkToFigma -- bunx cursor-talk-to-figma-mcp@latest
4. In Figma: Plugins → Development → Import plugin from manifest… → src/cursor_mcp_plugin/manifest.json
5. Run the plugin → it connects to channel figma.

Your MCP client then does join_channel("figma") and uses the tools.

One command to bring it all up (Windows)

figma-mcp-up.ps1 starts whatever isn't already running and prints the current public URL:

powershell -ExecutionPolicy Bypass -File figma-mcp-up.ps1

Idempotent — it only starts what's missing:

• relay (bun socket, :3055) if the port is free;
• Figma with the anti-throttle flags, sent to the back (Start-FigmaBg.ps1);
• Cloudflare tunnel — started, or restarted if it's stuck in the reconnect loop; the URL stays the same while the tunnel is healthy;
• if it had to (re)start the relay, it briefly brings Figma to the front so the plugin reconnects (its reconnect timer is suspended in the background), then sends it back.

The URL is printed and written to tunnel-url.txt. Processes run detached, so they survive closing the terminal. Re-run any time.

The Figma plugin still needs a one-time manual run after a fresh Figma launch (Plugins → Development → Cursor MCP Plugin). Once connected, the up script keeps it alive across relay/tunnel restarts.

Background mode (Windows) — export images without Figma stealing focus

Figma (Chromium) throttles rendering when its window is backgrounded, which makes export_node_as_image time out. Fix: launch Figma with throttling disabled.

• Double-click Start-FigmaBg.vbs (or make a desktop shortcut to it). It finds the current Figma, launches it with the anti-throttling flags, and pushes the window to the back (unfocused) — out of the way, without stealing focus.
• Run the plugin once (channel stays figma).
• Image export now works while Figma sits behind your other windows.

Keep Figma open, don't minimize it. With the flags, an occluded (behind other windows, or on another virtual desktop) Figma renders reliably. A minimized window still gets its renderer suspended even with the flags, so export becomes flaky (works only after retries; fails over a laggy tunnel). The launcher therefore sends the window to the back instead of minimizing. Over a tunnel, also prefer running exports on the host machine — added latency makes the flaky/minimized case worse.

Download node images straight to files (figma-save.mjs)

The MCP export_node_as_image tool returns base64 inline — handy for the model, but awkward if you actually want the files on disk. figma-save.mjs fixes that: it renders nodes through the same bridge and writes PNGs to disk. No dependencies (built-in WebSocket, Node 22+ or Bun), batch-friendly, and it accepts node ids in the URL form.

# local
node figma-save.mjs --out=shots 15-6239 15-6478

# through a Cloudflare tunnel (run from any machine)
node figma-save.mjs --server=<random>.trycloudflare.com --out=shots 15-6239

Grab it on a machine that only has the tunnel:

curl -O https://raw.githubusercontent.com/skulidropek/figma-tunnel-mcp/main/figma-save.mjs
node figma-save.mjs --server=<random>.trycloudflare.com 15-6239

Options: --server= (host or ws(s):// url, default ws://localhost:3055), --channel= (default figma), --scale= (default 2), --out= (default .), --retries= (default 3). Node ids like 15:6239 or 15-6239 (from ?node-id=15-6239). Each node is saved as <id>.png in the out dir.

<details><summary>Older single-node helper (<code>_export_node.cjs</code>, needs <code>bun install</code>)</summary>

node _export_node.cjs figma "15:6239" 2 out.png ws://localhost:3055

</details>

Remote access (Cloudflare tunnel)

Expose the relay to the internet (ephemeral, no account needed):

cloudflared tunnel --url http://localhost:3055

You get a https://<random>.trycloudflare.com URL. A remote MCP client connects with:

bunx cursor-talk-to-figma-mcp@latest --server=<random>.trycloudflare.com

then join_channel("figma").

⚠️ No authentication. Anyone who has the tunnel URL + channel name can read and modify your file. Use it briefly and stop the tunnel when done. The quick-tunnel URL changes on every restart.

Notes

• The "Export All" plugin (figma-export-plugin/) renders every container (frames, components, groups, instances, sections). On large files that is thousands of images and a big ZIP, and can be slow. For specific screens prefer targeted _export_node.cjs.

---

Talk to Figma MCP (upstream docs)

This project implements a Model Context Protocol (MCP) integration between AI agent (Cursor, Claude Code) and Figma, allowing AI agent to communicate with Figma for reading designs and modifying them programmatically.

https://github.com/user-attachments/assets/129a14d2-ed73-470f-9a4c-2240b2a4885c

Project Structure

• src/talk_to_figma_mcp/ - TypeScript MCP server for Figma integration
• src/cursor_mcp_plugin/ - Figma plugin for communicating with Cursor
• src/socket.ts - WebSocket server that facilitates communication between the MCP server and Figma plugin

How to use

1. Install Bun if you haven't already:

curl -fsSL https://bun.sh/install | bash

2. Run setup, this will also install MCP in your Cursor's active project

bun setup

3. Start the Websocket server

bun socket

4. NEW Install Figma plugin from Figma community page or install locally

Quick Video Tutorial

Video Link

Design Automation Example

Bulk text content replacement

Thanks to @dusskapark for contributing the bulk text replacement feature. Here is the demo video.

Instance Override Propagation Another contribution from @dusskapark Propagate component instance overrides from a source instance to multiple target instances with a single command. This feature dramatically reduces repetitive design work when working with component instances that need similar customizations. Check out our demo video.

Manual Setup and Installation

MCP Server: Integration with Cursor

Add the server to your Cursor MCP configuration in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

WebSocket Server

Start the WebSocket server:

bun socket

Figma Plugin

1. In Figma, go to Plugins > Development > New Plugin
2. Choose "Link existing plugin"
3. Select the src/cursor_mcp_plugin/manifest.json file
4. The plugin should now be available in your Figma development plugins

Windows + WSL Guide

1. Install bun via powershell

powershell -c "irm bun.sh/install.ps1|iex"

2. Uncomment the hostname 0.0.0.0 in src/socket.ts

// uncomment this to allow connections in windows wsl
hostname: "0.0.0.0",

3. Start the websocket

bun socket

Usage

1. Start the WebSocket server
2. Install the MCP server in Cursor
3. Open Figma and run the Cursor MCP Plugin
4. Connect the plugin to the WebSocket server by joining a channel using join_channel
5. Use Cursor to communicate with Figma using the MCP tools

Local Development Setup

To develop, update your mcp config to direct to your local directory.

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bun",
      "args": ["/path-to-repo/src/talk_to_figma_mcp/server.ts"]
    }
  }
}

MCP Tools

The MCP server provides the following tools for interacting with Figma:

Document & Selection

• get_document_info - Get information about the current Figma document
• get_selection - Get information about the current selection
• read_my_design - Get detailed node information about the current selection without parameters
• get_node_info - Get detailed information about a specific node
• get_nodes_info - Get detailed information about multiple nodes by providing an array of node IDs
• set_focus - Set focus on a specific node by selecting it and scrolling viewport to it
• set_selections - Set selection to multiple nodes and scroll viewport to show them

Annotations

• get_annotations - Get all annotations in the current document or specific node
• set_annotation - Create or update an annotation with markdown support
• set_multiple_annotations - Batch create/update multiple annotations efficiently
• scan_nodes_by_types - Scan for nodes with specific types (useful for finding annotation targets)

Prototyping & Connections

• get_reactions - Get all prototype reactions from nodes with visual highlight animation
• set_default_connector - Set a copied FigJam connector as the default connector style for creating connections (must be set before creating connections)
• create_connections - Create FigJam connector lines between nodes, based on prototype flows or custom mapping

Creating Elements

• create_rectangle - Create a new rectangle with position, size, and optional name
• create_frame - Create a new frame with position, size, and optional name
• create_text - Create a new text node with customizable font properties

Modifying text content

• scan_text_nodes - Scan text nodes with intelligent chunking for large designs
• set_text_content - Set the text content of a single text node
• set_multiple_text_contents - Batch update multiple text nodes efficiently

Auto Layout & Spacing

• set_layout_mode - Set the layout mode and wrap behavior of a frame (NONE, HORIZONTAL, VERTICAL)
• set_padding - Set padding values for an auto-layout frame (top, right, bottom, left)
• set_axis_align - Set primary and counter axis alignment for auto-layout frames
• set_layout_sizing - Set horizontal and vertical sizing modes for auto-layout frames (FIXED, HUG, FILL)
• set_item_spacing - Set distance between children in an auto-layout frame

Styling

• set_fill_color - Set the fill color of a node (RGBA)
• set_stroke_color - Set the stroke color and weight of a node
• set_corner_radius - Set the corner radius of a node with optional per-corner control

Layout & Organization

• move_node - Move a node to a new position
• resize_node - Resize a node with new dimensions
• delete_node - Delete a node
• delete_multiple_nodes - Delete multiple nodes at once efficiently
• clone_node - Create a copy of an existing node with optional position offset

Components & Styles

• get_styles - Get information about local styles
• get_local_components - Get information about local components
• create_component_instance - Create an instance of a component
• get_instance_overrides - Extract override properties from a selected component instance
• set_instance_overrides - Apply extracted overrides to target instances

Export & Advanced

• export_node_as_image - Export a node as an image (PNG, JPG, SVG, or PDF) - limited support on image currently returning base64 as text

Connection Management

• join_channel - Join a specific channel to communicate with Figma

MCP Prompts

The MCP server includes several helper prompts to guide you through complex design tasks:

• design_strategy - Best practices for working with Figma designs
• read_design_strategy - Best practices for reading Figma designs
• text_replacement_strategy - Systematic approach for replacing text in Figma designs
• annotation_conversion_strategy - Strategy for converting manual annotations to Figma's native annotations
• swap_overrides_instances - Strategy for transferring overrides between component instances in Figma
• reaction_to_connector_strategy - Strategy for converting Figma prototype reactions to connector lines using the output of 'get_reactions', and guiding the use 'create_connections' in sequence

Development

Building the Figma Plugin

1. Navigate to the Figma plugin directory:

   cd src/cursor_mcp_plugin
   

2. Edit code.js and ui.html

Best Practices

When working with the Figma MCP:

1. Always join a channel before sending commands
2. Get document overview using get_document_info first
3. Check current selection with get_selection before modifications
4. Use appropriate creation tools based on needs:
   • create_frame for containers
   • create_rectangle for basic shapes
   • create_text for text elements
5. Verify changes using get_node_info
6. Use component instances when possible for consistency
7. Handle errors appropriately as all commands can throw exceptions
8. For large designs:
   • Use chunking parameters in scan_text_nodes
   • Monitor progress through WebSocket updates
   • Implement appropriate error handling
9. For text operations:
   • Use batch operations when possible
   • Consider structural relationships
   • Verify changes with targeted exports
10. For converting legacy annotations:
    • Scan text nodes to identify numbered markers and descriptions
    • Use scan_nodes_by_types to find UI elements that annotations refer to
    • Match markers with their target elements using path, name, or proximity
    • Categorize annotations appropriately with get_annotations
    • Create native annotations with set_multiple_annotations in batches
    • Verify all annotations are properly linked to their targets
    • Delete legacy annotation nodes after successful conversion
11. Visualize prototype noodles as FigJam connectors:

• Use get_reactions to extract prototype flows,
• set a default connector with set_default_connector,
• and generate connector lines with create_connections for clear visual flow mapping.

License

MIT