Figma MCP Bridge

A Model Context Protocol (MCP) server that enables Claude to read and manipulate Figma documents in real-time through a WebSocket bridge to a Figma plugin.

Features

• 62 Figma operations - Create shapes, modify styles, manage components, export assets
• Real-time bidirectional communication - Changes appear instantly in Figma
• Token-optimized queries - Efficient variable search and node traversal for AI interactions
• Full Figma API access - Styles, variables, auto-layout, boolean operations, and more

Architecture

Claude Code ←──stdio──→ MCP Server ←──WebSocket──→ Figma Plugin ←──→ Figma API
                        (Node.js)    localhost:3055    (runs in Figma)

Quick Start

Prerequisites

• Node.js 18+
• Figma desktop app
• Claude Code CLI or Claude Desktop

Installation

Option A: Install from npm (recommended)

For Claude Code CLI:

claude mcp add figma-mcp-bridge -- npx @magic-spells/figma-mcp-bridge

For Claude Desktop:

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Then restart Claude Desktop.

Install the Figma plugin:

• Download the plugin folder from this repo
• In Figma: Plugins → Development → Import plugin from manifest
• Select plugin/manifest.json

Connect:

• Open a Figma file
• Run the plugin: Plugins → Development → Claude Figma Bridge
• The status should show "Connected"

Option B: Install from source

1. Clone the repository

   git clone https://github.com/magic-spells/figma-mcp-bridge.git
   cd figma-mcp-bridge
   npm install
   

2. Add to Claude Code

   claude mcp add figma-mcp-bridge node /path/to/figma-mcp-bridge/src/index.js
   

3. Install the Figma plugin

   • In Figma: Plugins → Development → Import plugin from manifest
   • Select plugin/manifest.json from the cloned repo

4. Connect

   • Open a Figma file
   • Run the plugin: Plugins → Development → Claude Figma Bridge
   • The status should show "Connected"

Configuration

Environment Variables

Variable	Default	Description
FIGMA_BRIDGE_PORT	3055	WebSocket server port (auto-increments if busy)

Auto-approve Figma Tools

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": ["mcp__figma-mcp-bridge__*"]
  }
}

---

Commands Reference

Query Commands

figma_get_context

Get the current Figma document context including file info, current page, and selection.

Parameter	Type	Description
(none)

figma_list_pages

List all pages in the current Figma document.

Parameter	Type	Description
(none)

figma_get_nodes

Get detailed information about specific nodes by their IDs.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Array of node IDs (e.g., ["1:23", "4:56"])
depth	string	No	Detail level: minimal, compact, or full (default)

figma_get_local_styles

List all local styles defined in the document.

Parameter	Type	Required	Description
type	string	No	Filter: PAINT, TEXT, EFFECT, GRID, or ALL (default)

figma_get_local_variables

Get all local variables and variable collections.

Parameter	Type	Required	Description
type	string	No	Filter: COLOR, FLOAT, STRING, BOOLEAN, or ALL (default)

Note: Can return 25k+ tokens. Prefer figma_search_variables for efficiency.

figma_get_children

Get immediate children of a node. Efficient for browsing hierarchy one level at a time.

Parameter	Type	Required	Default	Description
parentId	string	Yes		Node ID to get children of
compact	boolean	No	true	Return minimal data

figma_search_nodes

Search for nodes by name within a scope. Preferred for finding specific frames, sections, or elements.

Parameter	Type	Required	Default	Description
parentId	string	Yes		Scope to search (page/frame/section ID)
nameContains	string	No		Case-insensitive substring match
namePattern	string	No		Glob pattern with wildcards (e.g., *button*)
types	string[]	No		Filter by node types: FRAME, TEXT, SECTION, COMPONENT, INSTANCE, GROUP, etc.
maxDepth	number	No	-1	Search depth (-1 = unlimited, 1 = immediate children)
compact	boolean	No	true	Return minimal data
limit	number	No	50	Maximum results

Returns ~50 tokens/node vs ~500 for full node data.

figma_search_components

Search local components by name. Use when looking for specific components like "Button", "Header", etc.

Parameter	Type	Required	Default	Description
nameContains	string	No		Case-insensitive substring match
namePattern	string	No		Glob pattern with wildcards
includeVariants	boolean	No	false	Include individual variants from component sets
compact	boolean	No	true	Return minimal data
limit	number	No	50	Maximum results

figma_search_styles

Search local styles by name. More efficient than figma_get_local_styles when looking for specific styles.

Parameter	Type	Required	Default	Description
nameContains	string	No		Case-insensitive substring match
type	string	No	"ALL"	Filter: PAINT, TEXT, EFFECT, GRID, ALL
compact	boolean	No	true	Return minimal data
limit	number	No	50	Maximum results

---

Creation Commands

figma_create_rectangle

Create a new rectangle.

Parameter	Type	Required	Default	Description
x	number	No	0	X position
y	number	No	0	Y position
width	number	No	100	Width in pixels
height	number	No	100	Height in pixels
name	string	No	"Rectangle"	Node name
fills	color	No		Fill color
parentId	string	No		Parent node ID

figma_create_ellipse

Create an ellipse, circle, arc, or ring.

Parameter	Type	Required	Default	Description
x	number	No	0	X position
y	number	No	0	Y position
width	number	No	100	Width (diameter for circle)
height	number	No	100	Height
name	string	No	"Ellipse"	Node name
fills	color	No		Fill color
parentId	string	No		Parent node ID
arcData.startingAngle	number	No		Starting angle in radians
arcData.endingAngle	number	No		Ending angle in radians
arcData.innerRadius	number	No		Inner radius ratio (0-1) for rings

figma_create_line

Create a line.

Parameter	Type	Required	Default	Description
x	number	No	0	X position
y	number	No	0	Y position
length	number	No	100	Line length
rotation	number	No	0	Rotation in degrees
strokeWeight	number	No	1	Stroke weight
strokes	color	No		Stroke color
strokeCap	string	No	"NONE"	Cap: NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL
name	string	No	"Line"	Node name
parentId	string	No		Parent node ID

figma_create_frame

Create a frame container (supports auto-layout).

Parameter	Type	Required	Default	Description
x	number	No	0	X position
y	number	No	0	Y position
width	number	No	100	Width
height	number	No	100	Height
name	string	No	"Frame"	Node name
fills	color	No		Fill color
parentId	string	No		Parent node ID

figma_create_text

Create a text node.

Parameter	Type	Required	Default	Description
x	number	No	0	X position
y	number	No	0	Y position
text	string	No	"Text"	Text content
fontSize	number	No	16	Font size
fontFamily	string	No	"Inter"	Font family
fontStyle	string	No	"Regular"	Font style
fills	color	No		Text color
name	string	No	"Text"	Node name
parentId	string	No		Parent node ID

figma_clone_nodes

Clone (duplicate) nodes.

Parameter	Type	Required	Default	Description
nodeIds	string[]	Yes		Node IDs to clone
parentId	string	No		Parent for clones
offset.x	number	No	20	X offset from original
offset.y	number	No	20	Y offset from original

figma_create_component

Create a reusable component.

Parameter	Type	Required	Default	Description
fromNodeId	string	No		Convert existing node to component
x	number	No	0	X position
y	number	No	0	Y position
width	number	No	100	Width
height	number	No	100	Height
name	string	No	"Component"	Component name
fills	color	No		Fill color
parentId	string	No		Parent node ID
description	string	No		Component description

figma_create_instance

Create an instance of a component.

Parameter	Type	Required	Description
componentId	string	Yes	Component ID to instantiate
x	number	No	X position
y	number	No	Y position
parentId	string	No	Parent node ID
name	string	No	Instance name

---

Style Commands

figma_set_fills

Set fill color on a node.

Parameter	Type	Required	Description
nodeId	string	Yes	Node to modify
fills	color	Yes	Fill color

Color formats:

• Hex: { color: "#FF0000" } or { color: "#FF0000AA" } (with alpha)
• RGB: { r: 1, g: 0, b: 0, a: 0.5 }
• Full array: [{ type: "SOLID", color: { r, g, b }, opacity: 1 }]

figma_set_strokes

Set stroke color on a node.

Parameter	Type	Required	Description
nodeId	string	Yes	Node to modify
strokes	color	Yes	Stroke color
strokeWeight	number	No	Stroke weight in pixels

figma_set_text

Set text content on a text node.

Parameter	Type	Required	Description
nodeId	string	Yes	Text node to modify
text	string	Yes	New text content

figma_set_opacity

Set node transparency.

Parameter	Type	Required	Description
nodeId	string	Yes	Node to modify
opacity	number	Yes	Opacity (0-1)

figma_set_corner_radius

Set corner radius.

Parameter	Type	Required	Description
nodeId	string	Yes	Node to modify
radius	number	No	Uniform radius for all corners
topLeft	number	No	Top-left corner radius
topRight	number	No	Top-right corner radius
bottomLeft	number	No	Bottom-left corner radius
bottomRight	number	No	Bottom-right corner radius

figma_set_effects

Set effects (shadows, blurs).

Parameter	Type	Required	Description
nodeId	string	Yes	Node to modify
effects	array	Yes	Array of effect objects

Shadow effect:

{
  "type": "DROP_SHADOW",
  "color": { "color": "#000000" },
  "offset": { "x": 0, "y": 4 },
  "radius": 8,
  "spread": 0,
  "visible": true
}

Blur effect:

{
  "type": "LAYER_BLUR",
  "radius": 10,
  "visible": true
}

figma_apply_style

Apply a local style to a node.

Parameter	Type	Required	Description
nodeId	string	Yes	Node to apply style to
styleId	string	Yes	Style ID
property	string	Yes	Property: fills, strokes, text, effects, grid

figma_set_variable

Set variable value or bind to node property.

Parameter	Type	Required	Description
variableId	string	Yes	Variable ID
modeId	string	No	Mode ID (for setting value)
value	any	No	Value to set
nodeId	string	No	Node ID (for binding)
field	string	No	Field to bind (opacity, cornerRadius, fills, etc.)
paintIndex	number	No	Paint array index for fills/strokes (default 0)

---

Layout Commands

figma_set_auto_layout

Configure auto-layout on a frame.

Parameter	Type	Required	Description
nodeId	string	Yes	Frame to configure
layoutMode	string	No	NONE, HORIZONTAL, VERTICAL
primaryAxisSizingMode	string	No	FIXED, AUTO
counterAxisSizingMode	string	No	FIXED, AUTO
primaryAxisAlignItems	string	No	MIN, CENTER, MAX, SPACE_BETWEEN
counterAxisAlignItems	string	No	MIN, CENTER, MAX, BASELINE
paddingTop	number	No	Top padding
paddingRight	number	No	Right padding
paddingBottom	number	No	Bottom padding
paddingLeft	number	No	Left padding
itemSpacing	number	No	Space between items
counterAxisSpacing	number	No	Space between rows when wrapped
layoutWrap	string	No	NO_WRAP, WRAP

figma_set_layout_align

Set child alignment in auto-layout.

Parameter	Type	Required	Description
nodeId	string	Yes	Child node to modify
layoutAlign	string	No	MIN, CENTER, MAX, STRETCH, INHERIT
layoutGrow	number	No	Growth factor (0-1)
layoutPositioning	string	No	AUTO, ABSOLUTE

---

Transform Commands

figma_move_nodes

Move nodes to a new position.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Nodes to move
x	number	No	X position or offset
y	number	No	Y position or offset
relative	boolean	No	If true, x/y are offsets (default false)

figma_resize_nodes

Resize nodes.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Nodes to resize
width	number	No	New width
height	number	No	New height

figma_delete_nodes

Delete nodes.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Nodes to delete

figma_group_nodes

Group multiple nodes.

Parameter	Type	Required	Default	Description
nodeIds	string[]	Yes		Nodes to group
name	string	No	"Group"	Group name

figma_ungroup_nodes

Ungroup group nodes.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Group nodes to ungroup

figma_rename_node

Rename nodes.

Parameter	Type	Required	Description
nodeId	string	No	Single node ID
nodeIds	string[]	No	Batch node IDs
name	string	Yes	New name

figma_reorder_node

Change z-order (layer order).

Parameter	Type	Required	Description
nodeId	string	Yes	Node to reorder
position	string/number	Yes	"front", "back", or index number

figma_set_constraints

Set resize constraints (non-auto-layout frames only).

Parameter	Type	Required	Description
nodeId	string	Yes	Node to configure
horizontal	string	No	MIN, CENTER, MAX, STRETCH, SCALE
vertical	string	No	MIN, CENTER, MAX, STRETCH, SCALE

---

Navigation Commands

figma_set_selection

Set the current selection.

Parameter	Type	Required	Description
nodeIds	string[]	Yes	Nodes to select (empty to clear)

figma_set_current_page

Switch to a different page.

Parameter	Type	Required	Description
pageId	string	Yes	Page ID to switch to

---

Export Commands

figma_export_node

Export a node as an image.

Parameter	Type	Required	Default	Description
nodeId	string	Yes		Node to export
format	string	No	"PNG"	Format: PNG, SVG, JPG, PDF
scale	number	No	1	Export scale (1 = 100%)

Returns base64-encoded data.

---

Component Commands

figma_detach_instance

Detach instance from component (converts to frame).

Parameter	Type	Required	Description
nodeId	string	Yes	Instance to detach

---

Token Optimization

Variable Queries

Use figma_search_variables instead of figma_get_local_variables:

// Inefficient (~25k+ tokens)
figma_get_local_variables({ type: 'ALL' })

// Efficient (~500 tokens)
figma_search_variables({
  namePattern: 'tailwind/orange/*',
  type: 'COLOR',
  compact: true,
  limit: 50
})

figma_search_variables parameters:

Parameter	Type	Default	Description
namePattern	string		Wildcard pattern (* = any chars)
type	string	"ALL"	Variable type filter
collectionName	string		Collection name filter
compact	boolean	true	Minimal data (id, name, value only)
limit	number	50	Max results

Node Traversal

Use the depth parameter in figma_get_nodes:

Depth	Properties	Use Case
minimal	~5	Tree traversal, finding nodes
compact	~10	Layout inspection
full	~40	Detailed node editing

Finding Nodes

Use search tools instead of traversing the full tree:

// Find nodes by name within a page/frame
figma_search_nodes({
  parentId: '1:2',           // Required scope
  nameContains: 'button',    // Case-insensitive
  types: ['FRAME', 'COMPONENT'],
  compact: true
})

// Browse hierarchy one level at a time
figma_get_children({ parentId: '1:2' })

// Find components by name
figma_search_components({ nameContains: 'Header' })

// Find styles by name
figma_search_styles({ nameContains: 'primary', type: 'PAINT' })

Tool	Use Case	Token Efficiency
figma_search_nodes	Find frames/elements by name	~50 tokens/node
figma_get_children	Browse hierarchy level-by-level	~50 tokens/node
figma_search_components	Find specific components	~50 tokens/result
figma_search_styles	Find specific styles	~30 tokens/result

---

Known Limitations

• No ES6 spread operator in plugin code
• Boolean operations require nodes with same parent
• Constraints don't work on auto-layout children (use layoutAlign)
• Lines have height=0, use length parameter
• Vectors only support M, L, Q, C, Z commands (no arcs)
• detachInstance() also detaches ancestor instances
• 30-second timeout on all commands

---

Troubleshooting

Plugin Not Connecting

1. Ensure the MCP server is running
2. Check the port: default is 3055, or set FIGMA_BRIDGE_PORT
3. Restart the plugin in Figma
4. Click "Reconnect" in the plugin UI

Port Already in Use

The server automatically tries ports 3055-3070. To use a specific port:

FIGMA_BRIDGE_PORT=3057 node src/index.js

Multiple Claude Code Instances

Each Claude Code instance can work with a different Figma file by using different ports:

1. First instance: Use default port 3055
2. Second instance: Set FIGMA_BRIDGE_PORT=3056
3. In Figma plugin: Change the port number in the plugin UI to match

The plugin UI has a port input field - just change it to connect to a different MCP server.

Commands Timing Out

• Commands have a 30-second timeout
• Large exports may timeout; try smaller scales
• Check plugin is still connected (green status)

Font Errors

Text operations require font loading. The plugin handles this automatically, but if a font isn't installed, it will fail. Use fonts available on your system.

---

License

MIT