Figma MCP Bridge

🚀 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

Auto-approve Figma Tools

Add to .claude/settings.local.json:

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

📚 Documentation

Query Commands

figma_get_context

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

figma_list_pages

List all pages in the current Figma document.

figma_get_nodes

Get detailed information about specific nodes by their IDs.

figma_get_local_styles

List all local styles defined in the document.

figma_get_local_variables

Get all local variables and variable collections.

⚠️ Important 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.

figma_search_nodes

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

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.

figma_search_styles

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

Creation Commands

figma_create_rectangle

Create a new rectangle.

figma_create_ellipse

Create an ellipse, circle, arc, or ring.

figma_create_line

Create a line.

figma_create_frame

Create a frame container (supports auto-layout).

figma_create_text

Create a text node.

figma_clone_nodes

Clone (duplicate) nodes.

figma_create_component

Create a reusable component.

figma_create_instance

Create an instance of a component.

Style Commands

figma_set_fills

Set fill color on a node.

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.

figma_set_text

Set text content on a text node.

figma_set_opacity

Set node transparency.

figma_set_corner_radius

Set corner radius.

figma_set_effects

Set effects (shadows, blurs).

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.

figma_set_variable

Set variable value or bind to node property.

Layout Commands

figma_set_auto_layout

Configure auto-layout on a frame.

figma_set_layout_align

Set child alignment in auto-layout.

Transform Commands

figma_move_nodes

Move nodes to a new position.

figma_resize_nodes

Resize nodes.

figma_delete_nodes

Delete nodes.

figma_group_nodes

Group multiple nodes.

figma_ungroup_nodes

Ungroup group nodes.

figma_rename_node

Rename nodes.

figma_reorder_node

Change z-order (layer order).

figma_set_constraints

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

Navigation Commands

figma_set_selection

Set the current selection.

figma_set_current_page

Switch to a different page.

Export Commands

figma_export_node

Export a node as an image.

Returns base64-encoded data.

Component Commands

figma_detach_instance

Detach instance from component (converts to frame).

🔧 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:

Node Traversal

Use the depth parameter in figma_get_nodes:

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' })

⚠️ 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