figma-ui-mcp

Bidirectional Figma MCP bridge — let AI assistants (Claude Code, Cursor, Windsurf, Antigravity, VS Code Copilot, or any MCP-compatible IDE) draw UI directly on Figma canvas and read existing designs back as structured data, screenshots, or code-ready tokens. No Figma API key needed — works entirely over localhost.

Requires Figma Desktop — the plugin communicates with the MCP server over localhost HTTP polling. Figma's web app does not allow localhost network access, so Figma Desktop is required.

Claude ──figma_write──▶ MCP Server ──HTTP (localhost:38451)──▶ Figma Plugin ──▶ Figma Document
Claude ◀─figma_read──── MCP Server ◀──HTTP (localhost:38451)── Figma Plugin ◀── Figma Document

How the localhost bridge works

The MCP server starts a small HTTP server bound to localhost:38451. The Figma plugin (running inside Figma Desktop) uses long polling — the server holds requests up to 8s until work arrives, flushing immediately when new ops are queued (near-realtime latency <100ms). All traffic stays on your machine — nothing is sent to any external server.

Multi-instance support (v2.3.0+): Multiple Figma files/tabs can connect simultaneously. Each plugin instance sends a sessionId, and the bridge routes operations to the correct session. Use the optional sessionId param in figma_write/figma_read to target a specific file.

Features

| Direction | Tool | What it does | |-----------|------|-------------| | Write | figma_write | Draw frames, shapes, text, prototypes via JS code | | Read | figma_read | Extract node trees, colors, typography, screenshots | | Info | figma_status| Check plugin connection + active sessions | | Docs | figma_docs | Get full API reference + examples | | Rules | figma_rules | Generate design system rule sheet — tokens, typography, components |

What's new in v2.5

| Feature | Description | |---------|-------------| | get_design_context | AI-optimized payload for a node — flex layout, token-resolved colors (var(--name)), typography with style names, component instances with variant properties. Best single call for design→React/Vue/Swift code. | | get_component_map | List every component instance in a frame with componentSetName, variantLabel, properties, and suggestedImport path. Scaffold import statements in one call. | | get_unmapped_components | Find component instances that have no description in Figma (no code mapping yet). Prompts AI to ask user for correct import paths. | | figma_rules tool | New top-level MCP tool — aggregates color tokens, typography styles, variables (all modes), and component catalog into a single markdown rule sheet. Equivalent to official Figma MCP's create_design_system_rules. Call once at session start. | | get_css operation | figma_read get_css { nodeId } → ready-to-use CSS string (flex, typography, fill, border, shadow, opacity, transform). One call, paste into code. | | Resolved variables | get_node_detail now resolves boundVariables IDs → { name, resolvedType, value }. No more manual ID lookup. | | Resolved style refs | fillStyleId / textStyleId now include fillStyle: { name, hex } and textStyle: { name, fontSize, fontFamily }. | | Instance overrides detail | overrides: [{ id, overriddenFields: ["fills","characters",...] }] — full diff vs mainComponent, not just count. | | componentSetName + variantLabel | INSTANCE nodes now expose set name ("Button") and variant label ("State=Primary, Size=Large") separately. | | insertIndex for create | figma.create({ ..., insertIndex: 2 }) — insert node at exact position in parent, not always at end. | | Typography tokens | setupDesignTokens({ fontSizes, fonts, textStyles }) — 1 call bootstrap full typography system with variable-bound text styles. Multi-mode (Compact/Comfortable/Large) supported. | | applyTextStyle | Apply a local text style to a TEXT node by name in 1 call — auto-loads font. | | STRING variables for fonts | applyVariable now binds fontFamily, fontStyle, characters (swap Inter → SF Pro via 1 variable). | | Effects | effects: [{ type: "DROP_SHADOW" \| "INNER_SHADOW" \| "LAYER_BLUR" \| "BACKGROUND_BLUR", ... }] on any node. | | Gradient fills | fill: { type: "LINEAR_GRADIENT" \| "RADIAL_GRADIENT", angle, stops } in create/modify. | | Individual corner radii | topLeftRadius, topRightRadius, bottomLeftRadius, bottomRightRadius on FRAME/RECT. | | 8-digit hex + rgba alpha | fill: "#FFFFFF80" or "rgba(255,255,255,0.5)" — alpha auto-applied to paint opacity. | | SVG arc (A) + commas | VECTOR d paths accept A arc command (auto-converted to cubic Bézier) and commas. | | Icon libraries | 7 free open-source libraries, iOS-filled first: Ionicons → Fluent → Bootstrap → Phosphor → Tabler Filled → Tabler Outline → Lucide. | | Instance overrides | figma.instantiate({ overrides: { "LayerName": { text, fill, fontSize } } }) — override props per-layer. | | Batch delete | figma.delete({ ids: [...] }) — delete multiple nodes in 1 round-trip. | | Prototyping | setReactions — click/hover/press → navigate/overlay/swap with Smart Animate. | | Scroll behavior | setScrollBehavior — HORIZONTAL / VERTICAL / BOTH overflow. | | Variants & instance swap | setComponentProperties / swapComponent — variants + instance swap. | | Component property definitions (v2.5.24) | addComponentProperty + bindComponentProperty — create TEXT / BOOLEAN / INSTANCE_SWAP properties on master components. Instance text overrides now actually re-measure auto-layout (button grows to fit longer label). | | Multi-instance | Multiple Figma tabs connect simultaneously via sessions. |

Full version history: see CHANGELOG.md.

Quick Start

Step 1 — Add the MCP server to your AI client

Choose your platform:

# Project scope (default)
claude mcp add figma-ui-mcp -- npx figma-ui-mcp

# Global scope (all projects)
claude mcp add --scope user figma-ui-mcp -- npx figma-ui-mcp

Edit config file:

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

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

Edit .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

Edit .vscode/mcp.json (project) or add to settings.json (global):

{
  "mcp": {
    "servers": {
      "figma": {
        "command": "npx",
        "args": ["-y", "figma-ui-mcp"]
      }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

1. Open "..." dropdown at the top of the agent panel
2. Click "Manage MCP Servers" → "View raw config"
3. Add to mcp_config.json:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

git clone https://github.com/TranHoaiHung/figma-ui-mcp
cd figma-ui-mcp
npm install
# Then point your MCP client to: node /path/to/figma-ui-mcp/server/index.js

⚠️ IMPORTANT: After adding the MCP server, you MUST restart your IDE / AI client (quit and reopen). The MCP server only loads on startup — simply saving the config file is not enough. This applies to Claude Code, Cursor, VS Code, Windsurf, and Antigravity.

Step 2 — Install the Figma plugin

⬇ Download plugin.zip — no git clone needed

1. Download and unzip plugin.zip anywhere on your machine
2. Open Figma Desktop (required — web app cannot access localhost)
3. Go to Plugins → Development → Import plugin from manifest...
4. Select manifest.json from the unzipped folder
5. Run Plugins → Development → Figma UI MCP Bridge

The plugin UI shows a green dot when the MCP server is connected.

Updating to a newer version

# Step 1 — get the new version + plugin path
npx figma-ui-mcp@latest --version
# figma-u