Figma MCP Bridge
by gethopp
README.md
# Figma MCP Bridge
[](https://gethopp.app)
- [Demo](#demo)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [Local development](#local-development)
- [Structure](#structure)
- [How it works](#how-it-works)
<br/>
<img src="https://raw.githubusercontent.com/gethopp/figma-mcp-bridge/main/logo.png" alt="Figma MCP Bridge" align="center" />
<br/>
> [!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](https://github.com/GLips/Figma-Context-MCP/) exist, one issues is the [API limiting](https://github.com/GLips/Figma-Context-MCP/issues/258) 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](#editing-notes) below.
## Demo
[Watch a demo of building a UI in Cursor with Figma MCP Bridge](https://youtu.be/ouygIhFBx0g)
[](https://youtu.be/ouygIhFBx0g)
## 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):
```json
{
"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](https://github.com/gethopp/figma-mcp-bridge/releases) page, then in Figma go to `Plugins > Development > Import plugin from manifest` and select the `manifest.json` file from the `plugin/` folder.
### 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](#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_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 |
| `set_text_properties` | Patch font, size, alignment, auto-resize, color, and bounds on a text node |
| `set_node_properties` | Patch common node properties: name, position, size, visibility, opacity, corner radius |
| `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 |
| `create_page` | Create a new page in the document, optionally switching to it |
| `create_frame` | Create a new frame, optionally under a parent |
| `create_text` | Create a new text node |
| `create_shape` | Create a rectangle, ellipse, or line |
| `create_image` | Create an image-backed rectangle from a local path, URL, or data URI |
| `import_html_layers` | Bulk-import an html-figma layer tree (JSON) as frames, text, rectangles, and vectors |
| `duplicate_nodes` | Duplicate nodes in place |
| `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.
### 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).
- 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](https://github.com/sergcen/html-to-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](https://bun.sh) as its package manager and script runner throughout. Install it first if you don't have it.
#### 1. Clone this repository locally
```bash
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.
```bash
cd figma-mcp-bridge && bun install
```
#### 3. Build the server
```bash
cd server && bun install && bun run build
```
#### 4. Build the plugin
```bash
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:
```json
{
"figma-bridge": {
"command": "node",
"args": ["/path/to/figma-mcp-bridge/server/dist/index.js"]
}
}
```
### Code style
The repo is formatted with [Prettier](https://prettier.io) (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:
```bash
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) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
```
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessUnresponsive