Figma Unified

A comprehensive Model Context Protocol (MCP) server that enables Claude to read, create, edit, and generate code from Figma designs.

Features

• 🔍 Read — Get file structure, nodes, styles, components, variables, and comments
• ✏️ Create — Make frames, shapes, text, components, instances, vector paths, SVG imports, and pages
• 🎨 Modify — Change colors, gradients, sizes, positions, auto-layout, effects, and more
• 🎭 Prototype — Add interactions, flows, transitions, and overlays
• 🧩 Variables — Create and manage design tokens via REST API (no plugin needed)
• 💻 Code Generation — Export to CSS, React, SwiftUI, HTML, and Tailwind
• 📱 Prototype to HTML — Generate interactive HTML prototypes from Figma designs
• ♿ Accessibility — Check color contrast and touch target sizes
• 📐 Layout Validation — Verify spacing, alignment, and overflow
• 🎯 Boolean Operations — Union, subtract, intersect, exclude shapes
• 📤 Export — Export nodes as PNG/JPG/SVG/PDF to local files or base64
• 🔗 Code Connect — Bridge Figma components to code via fuzzy matching and Dev Mode links
• ✨ Text Presets — Apply 16 built-in typography presets (display, heading, body, label, etc.)
• 🌈 Gradient Fills — Set linear, radial, angular, and diamond gradient fills

Installation

Quick Setup (Recommended)

macOS / Linux:

./setup.sh

Windows:

.\setup.bat

• For Claude Code users: stop any running session first with /exit, then run the setup script, then relaunch.

This single command will:

• ✅ Check Node.js is installed (Windows: auto-install via winget)
• ✅ Install all dependencies
• ✅ Build the MCP server and Figma plugin
• ✅ Configure Claude Desktop, Claude Code, or Cursor automatically

After the script finishes, just:

1. Import the plugin in Figma (Plugins → Development → Import from manifest)
2. Restart Claude Desktop (or Claude Code picks it up automatically)

Manual Setup

git clone https://github.com/sso-ss/figma-unified-mcp.git
cd figma-unified-mcp

cd figma-unified-mcp
npm install

npm run build

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "figma-unified-mcp": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/Desktop/Claude/mcp/figma-unified-mcp/dist/server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "figma-unified-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\Desktop\\Claude\\mcp\\figma-unified-mcp\\dist\\server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

claude mcp add figma-unified-mcp \
  -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE \
  -- node /Users/YOUR_USERNAME/Desktop/Claude/mcp/figma-unified-mcp/dist/server.js

claude mcp add figma-unified-mcp `
  -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE `
  -- node C:\Users\YOUR_USERNAME\Desktop\Claude\mcp\figma-unified-mcp\dist\server.js

{
  "mcpServers": {
    "figma-unified-mcp": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/Desktop/Claude/mcp/figma-unified-mcp/dist/server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "figma-unified-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\Desktop\\Claude\\mcp\\figma-unified-mcp\\dist\\server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Verification

In Claude Desktop or Claude Code, try:

What Figma tools do you have available?

Claude should list the tools available for your profile. You can also check the logs:

tail -f ~/Library/Logs/Claude/mcp-server-figma-unified-mcp.log

CLI — unified-design

A standalone command-line interface that uses the same REST API + plugin bridge as the MCP server, but without the MCP overhead. No plugin needed for read operations.

Setup

cd figma-unified-mcp
npm install
npm run build
npm link           # makes 'unified-design' available globally

Windows note: PowerShell 5.1 does not support &&. Use ; to chain commands (e.g., npm install; npm run build) or run them on separate lines. If unified-design is blocked by execution policy, use unified-design.cmd instead, or run directly with node dist/cli.js.

macOS / Linux: If unified-design isn't found after npm link, ensure your npm global bin directory is in your PATH:

export PATH="$(npm prefix -g)/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc

Or run directly with node dist/cli.js.

Plugin Bridge — Coexisting with MCP Server

Canvas write commands (e.g., create-frame, set-fill) require the Figma plugin. The CLI automatically detects how to connect:

• MCP server running? → CLI connects as a client to the existing bridge (no port conflict)
• No server running? → CLI starts its own bridge server and waits for the plugin

This means you can use the CLI alongside Claude Desktop / Cursor without stopping the MCP server.

Authentication

# Option 1: Environment variable
export FIGMA_ACCESS_TOKEN=figd_xxx

# Option 2: Config file (~/.figmarc)
unified-design config set accessToken figd_xxx

# Option 3: Auto-discovery (reads from Claude Desktop / Cursor MCP config)
# Just works — no setup needed if you already configured MCP

Quick start

# Set a default file so you don't need --file-key every time
unified-design config set defaultFileKey ABC123

# Read operations (REST API — no plugin needed)
unified-design get-file                          # File tree (depth 2)
unified-design get-node --node-id 123:456        # Single node details
unified-design search --query "Button"            # Find nodes by name
unified-design get-styles                        # All styles
unified-design get-variables                     # All variables/tokens
unified-design screenshot --node-id 123:456      # Export as PNG
unified-design export-svg --node-id 123:456      # Export as SVG
unified-design audit                             # Design quality audit

# Paste Figma URLs directly
unified-design get-node --url 'https://figma.com/design/ABC123/File?node-id=1-2'

# Variable operations (REST API — no plugin needed)
unified-design create-variable-collection --name "Colors" --modes light,dark
unified-design create-variable --collection-id <id> --name primary --type COLOR --value "#3B82F6"
unified-design set-variable-value --variable-id <id> --mode-id <id> --value "#1E40AF"
unified-design update-variable --variable-id <id> --name "brand-primary"
unified-design delete-variable --variable-id <id>

# Canvas write operations (need Figma plugin running)
unified-design create-frame --name "Header" --width 375 --height 64
unified-design set-fill --node-id 1:2 --color "#3B82F6"
unified-design set-text --node-id 1:3 --text "Hello World"
unified-design move-node --node-id 1:2 --x 100 --y 200

Output control

# Compact JSON (auto-enabled when piping to another command)
unified-design get-styles --compact

# Select specific fields (dot-notation, comma-separated)
unified-design get-file --fields "document.name,document.children"

# Save to file
unified-design get-styles --output styles.json

# Chain with jq
unified-design get-styles | jq '.styles[].name'

Short aliases

Interactive REPL

Run without arguments for an interactive session:

unified-design
# >
# unified-design ❯ file
# unified-design ❯ find --query "Logo"
# unified-design ❯ audit --json
# unified-design ❯ /exit

Using CLI as an AI Agent Backend

The CLI is optimized for use with Claude Code and other AI coding agents. When piped (non-TTY), output is automatically compact JSON — ~90% fewer tokens than MCP tool schemas.

Add this to your project's CLAUDE.md:

## Figma CLI
Use `unified-design` CLI to read and modify Figma designs:
- `unified-design get-file --file-key <key> --compact`
- `unified-design search --file-key <key> --query <name>`
- `unified-design screenshot --file-key <key> --node-id <id>`

See CLAUDE.md for the full agent instructions.

Tool Profiles

Control how many tools are registered via the TOOL_PROFILE environment variable:

Set in your MCP config:

{
  "env": {
    "FIGMA_ACCESS_TOKEN": "figd_...",
    "TOOL_PROFILE": "standard"
  }
}

Non-full profiles include figma_run escape hatch to access excluded tools on demand.

Available Tools

Connection Tools (3)

Utility Tools (3)

Read Tools (32)

Visual/Export Tools (4)

Create Tools (10)

Modify Tools (19)

Instance Override Tools (2)

Variable/Token Tools (10) — REST API, no plugin needed

Prototype Tools (10)

Design Quality Tools (3)

Code Connect Tools (4)

Code Generation Tools (9)

Available Agent Skills (14)

See skills.md for all 14 agent skills and their parameters.

Usage Examples

Example 1: Read a Figma File

You say:

Can you analyze my Figma file? The URL is:
https://www.figma.com/design/ABC123xyz/MyDesign

Claude will:

1. Extract the file key from the URL
2. Use figma_get_file to fetch the structure
3. Summarize pages, frames, and components

Example 2: Get Design Tokens

You say:

What colors and text styles are defined in file ABC123xyz?

Claude will:

1. Use figma_get_styles to get all styles
2. Use figma_get_variables to get variables
3. Present them in an organized list

Example 3: Create a Button Component

You say:

Create a primary button component in Figma with:
- Blue background (#3B82F6)
- White text "Click me"
- 16px padding
- 8px border radius

Claude will:

1. Use figma_connect_plugin to connect
2. Use figma_create_component to create the component
3. Use figma_create_text to add the label
4. Use figma_set_fill to set the blue background
5. Use figma_set_auto_layout to add padding
6. Use figma_set_corner_radius to round corners

Example 4: Build a Login Screen

You say:

Design a mobile login screen with email, password fields, and a sign in button.

Claude will:

1. Create a frame (375x812 for mobile)
2. Add a logo placeholder
3. Create input fields with labels
4. Add a primary button
5. Apply consistent spacing with auto-layout

Example 5: Generate React Code

You say:

Generate a React component from the card in node 123:456

Claude will:

1. Use figma_generate_react with the node ID
2. Return a complete React component with Tailwind classes

Example output:

interface CardProps {
  text?: string;
}

export function Card(props: CardProps) {
  return (
    <div className="flex flex-col gap-4 p-6 bg-white rounded-xl shadow-lg">
      <h2 className="text-xl font-semibold">Card Title</h2>
      <p className="text-gray-600">Card description goes here</p>
      <button className="bg-blue-500 text-white px-4 py-2 rounded-lg">
        Action
      </button>
    </div>
  );
}

Example 6: Export Design Tokens

You say:

Export all design tokens from my file as CSS variables

Claude will:

1. Use figma_generate_tokens with format "css"
2. Return CSS custom properties

Example output:

:root {
  --color-primary: #3B82F6;
  --color-secondary: #10B981;
  --color-neutral-100: #F3F4F6;
  --color-neutral-900: #111827;
  --font-size-heading: 24px;
  --font-size-body: 16px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
}

Example 7: Add Prototype Interaction

You say:

Make the login button navigate to the Dashboard frame when clicked, with a slide animation

Claude will:

1. Use figma_create_interaction with:
   • trigger: ON_CLICK
   • action: NAVIGATE
   • destinationId: (dashboard frame ID)
   • transition: SLIDE_IN
   • direction: LEFT
   • duration: 300

Example 8: Review Comments

You say:

What comments are on file ABC123xyz? Are any unresolved?

Claude will:

1. Use figma_get_comments to fetch all comments
2. List each comment with:
   • Author name
   • Message content
   • Created date
   • Resolved status

Example 9: Audit Design System

You say:

/audit_design_system

fileKey: ABC123xyz

Claude will run a comprehensive audit checking:

• ✅ Color consistency (are colors using styles/variables?)
• ✅ Typography scale (is there a defined type scale?)
• ✅ Spacing consistency (8px grid?)
• ✅ Component usage (are components properly structured?)
• ✅ Variable coverage (what's tokenized vs hardcoded?)

Example 10: Generate SwiftUI

You say:

Convert the profile card to SwiftUI code

Claude will:

1. Use figma_generate_swiftui
2. Return SwiftUI code

Example output:

import SwiftUI

struct ProfileCard: View {
    var body: some View {
        VStack(spacing: 16) {
            Image("avatar")
                .resizable()
                .frame(width: 80, height: 80)
                .clipShape(Circle())
            
            Text("John Doe")
                .font(.system(size: 20))
                .fontWeight(.semibold)
            
            Text("Product Designer")
                .font(.system(size: 14))
                .foregroundColor(.gray)
        }
        .padding(24)
        .background(Color.white)
        .cornerRadius(16)
    }
}

struct ProfileCard_Previews: PreviewProvider {
    static var previews: some View {
        ProfileCard()
    }
}

Example 11: Create Variables/Tokens

You say:

Create a color variable collection with primary, secondary, and neutral colors that support light and dark modes

Claude will:

1. Use figma_create_variable_collection with modes "Light" and "Dark"
2. Use figma_create_variable for each color
3. Use figma_set_variable_value to set values per mode

Example 12: Search and Modify

You say:

Find all buttons in my file and change their corner radius to 12px

Claude will:

1. Use figma_search to find nodes named "button"
2. Use figma_set_corner_radius on each result

Example 13: Set Gradient Fill

You say:

Apply a sunset gradient (orange to purple) to the hero section background

Claude will:

1. Use figma_set_fill with a fills array:

{
  "nodeId": "1:23",
  "fills": [{
    "type": "GRADIENT_LINEAR",
    "gradientStops": [
      { "position": 0, "color": { "r": 1, "g": 0.5, "b": 0, "a": 1 } },
      { "position": 1, "color": { "r": 0.6, "g": 0.2, "b": 0.8, "a": 1 } }
    ]
  }]
}

Example 14: Export to Local File

You say:

Export the hero banner to my Desktop as a PNG at 2x scale

Claude will:

1. Use figma_export_to_file with:
   • nodeId: the hero banner node
   • filePath: ~/Desktop/hero-banner.png
   • scale: 2

Example 15: Text Style Presets

You say:

Make the title use heading-xl style and the body use body-md

Claude will:

1. Use figma_set_text_style with preset: "heading-xl" (96px bold)
2. Use figma_set_text_style with preset: "body-md" (16px regular)

Available presets: display, heading-xl/lg/md/sm/xs, body-xl/lg/md/sm/xs, label-lg/md/sm, caption, overline

Example 16: Code Connect — Link Components to Code

You say:

Scan my project at ~/my-app/src and link matching components to Figma

Claude will:

1. Use figma_scan_codebase to find React/Vue/Svelte components
2. Use figma_match_components to fuzzy-match against Figma components
3. Review confidence scores with you
4. Use figma_publish_dev_resources to attach GitHub URLs to Figma Dev Mode

Developers then see code links directly in Figma's Dev Mode panel.

Architecture

┌─────────────────┐     stdio      ┌──────────────────┐
│  Claude Client  │◄──────────────►│  MCP Server      │
└─────────────────┘                │  (Node.js)       │
                                   └────────┬─────────┘
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    │                       │                       │
                    ▼                       ▼                       ▼
            ┌───────────────┐       ┌───────────────┐       ┌───────────────┐
            │  REST API     │       │  REST API     │       │  WebSocket    │
            │  (Read)       │       │  (Write)      │       │  Server:18211 │
            └───────┬───────┘       └───────┬───────┘       └───────┬───────┘
                    │                       │                       │
                    ▼                       ▼                       ▼
            ┌───────────────┐       ┌───────────────┐       ┌───────────────┐
            │  Figma API    │       │  Figma API    │       │ Figma Plugin  │
            │  api.figma.com│       │  api.figma.com│       │ (in Figma)    │
            └───────────────┘       └───────────────┘       └───────────────┘
            
            Read operations         Variable writes         Canvas writes
            (files, styles,         (create, update,        (create frames,
             components)             delete tokens)          modify nodes)
                                    NO PLUGIN NEEDED        PLUGIN REQUIRED

Three data paths:

1. REST API (Read) — File data, styles, components, variables (no plugin)
2. REST API (Write) — Variable/token CRUD operations (no plugin needed)
3. WebSocket + Plugin — Canvas manipulation (creating/modifying nodes)

No-plugin mode: All read operations + variable management work with just a Figma access token. You only need the plugin for canvas writes (frames, shapes, text, auto-layout, prototyping).

Troubleshooting

"Plugin not connected"

1. Make sure Figma Desktop is open
2. Run the plugin: Plugins → Development → Figma Unified MCP Bridge
3. Click Connect
4. Verify status shows "Connected"

"FIGMA_ACCESS_TOKEN not set"

Add your token to claude_desktop_config.json:

"env": {
  "FIGMA_ACCESS_TOKEN": "figd_xxxxx"
}

"WebSocket connection failed"

The MCP server starts a WebSocket on port 18211. Make sure:

1. Port 18211 is not in use (change with FIGMA_WS_PORT env var)
2. No firewall blocking localhost connections

Check Logs

macOS:

# MCP server logs
tail -f ~/Library/Logs/Claude/mcp-server-figma-unified-mcp.log

# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp.log

Windows (PowerShell):

# MCP server logs
Get-Content "$env:APPDATA\Claude\Logs\mcp-server-figma-unified-mcp.log" -Wait

# Claude Desktop logs
Get-Content "$env:APPDATA\Claude\Logs\mcp.log" -Wait

Development

Rebuild after changes

# MCP server + CLI
npm run build

# Figma plugin (use ; instead of && on Windows PowerShell)
cd figma-plugin; npm run build

# Run tests
npm test

Running tests

npm test              # Run all tests once
npm run test:watch    # Watch mode

Project Structure

figma-unified-mcp/
├── src/
│   ├── server.ts              # MCP server entry
│   ├── cli.ts                 # CLI entry (unified-design)
│   ├── config.ts              # Configuration & URL parsing
│   ├── types.ts               # TypeScript types
│   ├── cli/
│   │   ├── colors.ts          # ANSI color utilities
│   │   └── audit.ts           # Design audit command
│   ├── transport/
│   │   ├── rest-client.ts     # Figma REST API
│   │   └── plugin-bridge.ts   # WebSocket bridge to plugin
│   ├── tools/
│   │   ├── shared.ts          # Shared helpers (toolSuccess, toolError)
│   │   ├── tool-profiles.ts   # Profile filtering (minimal/standard/full)
│   │   ├── connection.ts      # Connection tools
│   │   ├── read.ts            # Read tools (35+)
│   │   ├── visual.ts          # Export tools
│   │   ├── create.ts          # Create tools
│   │   ├── modify.ts          # Modify tools
│   │   ├── variables.ts       # Variable tools
│   │   ├── prototype.ts       # Prototype tools
│   │   ├── codegen.ts         # Code generation tools
│   │   ├── code-connect.ts    # Code Connect tools (scan, match, publish)
│   │   ├── skill.ts           # Skill tool runner
│   │   └── figma-run.ts       # Escape hatch for non-full profiles
│   └── prompts/
│       ├── index.ts           # Agent skill registration
│       └── screen-patterns.ts # UX pattern data for design_screen skill
├── tests/
│   ├── config.test.ts         # URL parsing & config tests
│   ├── shared.test.ts         # Shared helper tests
│   ├── tool-profiles.test.ts  # Profile filtering tests
│   └── code-connect.test.ts   # Code Connect fuzzy matching & scanner tests
├── figma-plugin/
│   ├── manifest.json          # Plugin manifest
│   ├── code.ts                # Plugin logic
│   ├── ui.html                # Plugin UI
│   └── code.js                # Compiled plugin
├── CLAUDE.md                  # Agent instructions for Claude Code
├── skills.md                  # All 14 agent skills documentation
├── package.json
├── tsconfig.json
└── tsup.config.ts

License

MIT

Author

@sso-ss

Credits

Built with:

• Model Context Protocol SDK
• Figma Plugin API
• Figma REST API