figma-mcp-bridge

Figma MCP Bridge

• Demo
• Quick Start
• Available Tools
• Local development
• Structure
• How it works

[!NOTE]
Requires the Figma desktop app (macOS/Windows). The browser version of Figma does not support importing development plugins.

While other amazing Figma MCP servers like Figma-Context-MCP exist, one issues is the API limiting for free users.

The limit for free accounts is 6 requests per month, yes per month.

Figma MCP Bridge is a solution to this problem. It is a plugin + MCP server that streams live Figma document data to AI tools without hitting Figma API rate limits, so its Figma MCP for the rest of us ✊

It supports multiple Figma files connected simultaneously; open the plugin in each file and your AI agent can query any of them by fileKey. Single-file setups work exactly as before with no changes required.

It also includes a small, opt-in set of write tools for safe agent-driven edits — see Editing Notes below.

Demo

Watch a demo of building a UI in Cursor with Figma MCP Bridge

Quick Start

1. Add the MCP server to your favourite AI tool

Add the following to your AI tool's MCP configuration (e.g. Cursor, Windsurf, Claude Desktop):

{
  "figma-bridge": {
    "command": "npx",
    "args": ["-y", "@gethopp/figma-mcp-bridge"]
  }
}

That's it — no binaries to download or install.

2. Add the Figma plugin

Download the plugin from the latest release page, then in Figma go to Plugins > Development > Import plugin from manifest and select the manifest.json file from the plugin/ folder. The same plugin runs in Figma design files, Dev Mode (read-only), and FigJam boards.

3. Start using it 🎉

Open a Figma file, run the plugin, and start prompting your AI tool. The MCP server will automatically connect to the plugin.

To work across multiple files, just open the plugin in each Figma file. The bridge keeps all connections active and your AI agent can target any of them by fileKey.

If you want to know more about how it works, read the How it works section.

Available Tools

Tool	Description
list_files	List all connected Figma files (supports multi-file workflows)
get_document	Get the current Figma page document tree
get_selection	Get the currently selected nodes in Figma
get_node	Get a specific Figma node by ID (colon format, e.g. 4029:12345)
get_prototype_connections	Read prototype interactions on a node and its descendants
trace_prototype_flow	Trace prototype navigation between screens
get_styles	Get all local paint, text, effect, and grid styles
get_metadata	Get file name, pages, and current page info
get_design_context	Get a depth-limited tree optimized for understanding design context
get_variable_defs	Get all variable collections, modes, and values (design tokens)
get_screenshot	Export nodes as PNG/SVG/JPG/PDF (base64-encoded)
save_screenshots	Export and save screenshots directly to the local filesystem
get_motion_styles	List all available animation presets (beta)
get_node_motion	Read a node's current animation styles and properties (beta)
apply_animation_style	Apply a preset animation style to a node (beta)
remove_animation_style	Remove an applied animation style from a node (beta)
apply_manual_keyframe_track	Apply a manual keyframe track to a node property (beta)
remove_manual_keyframe_track	Remove a manual keyframe track from a node property (beta)
set_timeline_duration	Set the duration of a timeline in seconds (beta)
set_node_visibility	Show or hide specific nodes
set_text_content	Replace the contents of a text node (TEXT, FigJam sticky, or shape label)
set_text_properties	Patch font, size, alignment, auto-resize, color, and bounds on text nodes/sublayers
set_node_properties	Patch common node properties: name, position, size, visibility, opacity, corner radius (single or batch)
set_solid_fill	Replace a node's fill or stroke with a single solid paint
set_gradient_fill	Replace a node's fill or stroke with a linear/radial/angular/diamond gradient
set_effects	Replace a node's effects list (drop/inner shadows, layer/background blurs)
set_stroke_properties	Patch stroke weight, align, dash pattern, cap, and join
set_auto_layout	Configure auto-layout direction, padding, gap, alignment, sizing, and wrap (not sections)
create_page	Create a new page in the document, optionally switching to it
create_frame	Create a new frame, optionally under a parent
create_section	Create a section — a named, resizable container (Figma and FigJam)
create_text	Create a new text node
create_shape	Create a rectangle, ellipse, or line
create_shape_with_text	Create a FigJam shape with its own text label (SHAPE_WITH_TEXT), incl. text fill
create_image	Create an image-backed rectangle from a local path, URL, or data URI
create_sticky	Create a sticky note in FigJam
create_connector	Create a connector between two nodes in FigJam, with attachment anchors
import_html_layers	Bulk-import an html-figma layer tree (JSON) as frames, text, rectangles, and vectors
duplicate_nodes	Duplicate nodes in place
duplicate_with_offset	Duplicate nodes and move each duplicate by a fixed offset
fit_to_content	Resize a SECTION around its children with optional padding
distribute_horizontally	Space 3+ nodes with equal horizontal gaps (first/last stay fixed)
distribute_vertically	Space 3+ nodes with equal vertical gaps (first/last stay fixed)
align_to_grid	Snap node positions to a grid of the given size
place_below	Move a node below another with gap and start/center alignment
place_right_of	Move a node to the right of another with gap and start/center alignment
reparent_nodes	Move nodes into another parent
group_nodes	Wrap a list of nodes (sharing a parent) in a new group
ungroup_node	Ungroup a group or frame — children move up to its parent
set_selection	Set the page selection to a list of node IDs (works in Dev Mode)
scroll_and_zoom_into_view	Frame the viewport around the given nodes (works in Dev Mode)
delete_nodes	Delete nodes with explicit confirmation

All tools accept an optional fileKey parameter when multiple Figma files are connected. Use list_files to discover connected files and their keys.

Prototype Notes

• Prototype tools are read-only and unavailable in FigJam. Set includePrototype: true on get_node to include the same interactions.
• Reactions are Figma's own trigger and action data, with destinations, variables, and modes resolved to names.
• Flow edges list their enclosing branch conditions from outermost to innermost (null marks an else branch).
• Observed AFTER_TIMEOUT values are in seconds (for example, 0.8 for 800 ms).

Editing Notes

• Edit tools work only when the plugin is opened in Figma's design editor (Dev Mode is read-only — they will return a clear error there).
• In FigJam, read tools plus the write tools (set_text_content, set_text_properties, set_node_properties, set_solid_fill, create_text, create_shape, create_shape_with_text, create_sticky, create_connector, create_section, duplicate_nodes, duplicate_with_offset, fit_to_content, distribute_horizontally, distribute_vertically, align_to_grid, place_below, place_right_of, delete_nodes, ...) are available. Auto-layout and motion/animation tools return a clear error in FigJam.
• set_text_content / set_text_properties edit a TEXT node's content directly, or the text sublayer of a FigJam STICKY / SHAPE_WITH_TEXT node. Alignment and auto-resize are TEXT-node-only — they return a clear error on stickies and shapes (x/y/width/height still apply to the containing node).
• set_node_properties accepts either nodeId or a nodeIds array to apply the same property changes to several nodes in one call.
• set_auto_layout targets frames; SECTION nodes have no auto-layout in Figma's API and return an explicit error.
• fit_to_content works on SECTION nodes only (Figma's API exposes no equivalent for other containers): it shifts children so their bounding box starts at padding and resizes the section to bbox + 2×padding.
• The current user must have permission to edit the target file.
• delete_nodes is intentionally gated behind confirm: true.
• Text edits automatically load the fonts currently used by the target text node before applying the new content.
• New text nodes default to Inter Regular unless a font is provided.
• create_image reads local paths relative to the MCP server working directory unless you pass an absolute path.
• import_html_layers takes a JSON file produced by html-figma's browser htmlToFigma(). The path resolves relative to the MCP server working directory and must stay inside it, even when absolute. Everything lands inside one wrapper frame, and the response reports layerCount against expectedLayerCount so partial imports are visible.
• create_page returns the new page's ID — pass it as parentId to create_frame / create_text / create_shape / create_image to author content on that page without switching the editor.

What You Can Build

With the current write surface, an agent can build a basic slide deck in a new empty Figma file: create slide frames, style titles and body copy, lay out rectangles/ellipses/lines for cards and dividers, duplicate slide templates, reparent content into the right frame, and adjust common geometry/visual properties — including solid/gradient paints, shadows and blurs, stroke geometry, and auto-layout configuration.

The current version is intentionally limited — no components/instances, no variables/styles authoring, no per-segment text styling, and no vector boolean operations yet.

Local development

This repo uses Bun as its package manager and script runner throughout. Install it first if you don't have it.

1. Clone this repository locally

git clone git@github.com:gethopp/figma-mcp-bridge.git

2. Install root tooling

Install the root dependencies once. This runs Husky's prepare script, which installs the Git pre-commit hook that formats staged files with Prettier.

cd figma-mcp-bridge && bun install

3. Build the server

cd server && bun install && bun run build

4. Build the plugin

cd plugin && bun install && bun run build

5. Add the MCP server to your favourite AI tool

For local development, add the following to your AI tool's MCP config:

{
  "figma-bridge": {
    "command": "node",
    "args": ["/path/to/figma-mcp-bridge/server/dist/index.js"]
  }
}

Code style

The repo is formatted with Prettier (config in .prettierrc). A Husky pre-commit hook runs lint-staged, which formats only your staged files, so commits stay formatted automatically. You can also run it manually:

bun run format        # format the whole repo
bun run format:check  # verify formatting without writing (useful in CI)

Structure

Figma-MCP-Bridge/
├── plugin/   # Figma plugin (TypeScript/React)
└── server/   # MCP server (TypeScript/Node.js)
    └── src/
        ├── index.ts      # Entry point
        ├── bridge.ts     # WebSocket bridge to Figma plugin
        ├── leader.ts     # Leader: HTTP server + bridge
        ├── follower.ts   # Follower: proxies to leader via HTTP
        ├── node.ts       # Dynamic leader/follower role switching
        ├── election.ts   # Leader election & health monitoring
        ├── tools.ts      # MCP tool definitions
        └── types.ts      # Shared types

How it works

There are two main components to the Figma MCP Bridge:

1. The Figma Plugin

The Figma plugin is the user interface for the Figma MCP Bridge. You run this inside the Figma file you want to use the MCP server for, and its responsible for getting you all the information you need.

2. The MCP Server

The MCP server is the core of the Figma MCP Bridge. It maintains a registry of WebSocket connections keyed by fileKey, so multiple Figma files can be connected simultaneously. The server is responsible for:

• Handling WebSocket connections from one or more Figma plugin instances
• Routing tool calls to the correct file based on fileKey
• Forwarding responses back to the AI client
• Handling leader election (as we can have only one WS connection to an MCP server at a time)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           FIGMA (Desktop app)                               │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                         Figma Plugin                                  │  │
│  │                    (TypeScript/React)                                 │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ WebSocket
                                      │ (ws://localhost:1994/ws)
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PRIMARY MCP SERVER                                 │
│                         (Leader on :1994)                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  Bridge                                    Endpoints:               │    │
│  │  • Manages WebSocket conn                  • /ws    (plugin)        │    │
│  │  • Forwards requests to plugin             • /ping  (health)        │    │
│  │  • Routes responses back                   • /rpc   (followers)     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                           ▲                              ▲
                           │ HTTP /rpc                    │ HTTP /rpc
                           │ POST requests                │ POST requests
                           │                              │
         ┌─────────────────┴───────────┐    ┌─────────────┴───────────────┐
         │    FOLLOWER MCP SERVER 1    │    │    FOLLOWER MCP SERVER 2    │
         │                             │    │                             │
         │  • Pings leader /ping       │    │  • Pings leader /ping       │
         │  • Forwards tool calls      │    │  • Forwards tool calls      │
         │    via HTTP /rpc            │    │    via HTTP /rpc            │
         │  • If leader dies →         │    │  • If leader dies →         │
         │    attempts takeover        │    │    attempts takeover        │
         └─────────────────────────────┘    └─────────────────────────────┘
                    ▲                                      ▲
                    │                                      │
                    │ MCP Protocol                         │ MCP Protocol
                    │ (stdio)                              │ (stdio)
                    ▼                                      ▼
         ┌─────────────────────────────┐    ┌─────────────────────────────┐
         │      AI Tool / IDE 1        │    │      AI Tool / IDE 2        │
         │      (e.g., Cursor)         │    │      (e.g., Cursor)         │
         └─────────────────────────────┘    └─────────────────────────────┘