Figma Unified MCP

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

<details> <summary>Click to expand manual installation steps</summary>

Prerequisites

• Node.js 18+ — Download
• Figma Desktop App — Download
• Claude Desktop — Download
• Figma Personal Access Token — Get one here

Step 1: Clone or Download

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

Step 2: Install Dependencies

cd figma-unified-mcp
npm install

Step 3: Build the MCP Server

npm run build

This creates dist/server.js — the compiled MCP server.

Step 4: Configure Your Claude Client

Option A: Claude Desktop

Edit your Claude Desktop configuration file:

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the Figma MCP server:

macOS / Linux:

{
  "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"
      }
    }
  }
}

Windows:

{
  "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"
      }
    }
  }
}

⚠️ Replace YOUR_USERNAME with your actual username and figd_YOUR_TOKEN_HERE with your Figma Personal Access Token.

Option B: Claude Code (CLI)

macOS / Linux:

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

Windows (PowerShell):

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

Or add it to .claude/settings.json:

macOS / Linux:

{
  "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"
      }
    }
  }
}

Windows:

{
  "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"
      }
    }
  }
}

Step 5: Restart Your Claude Client

Quit and reopen Claude Desktop, or restart Claude Code to load the MCP server.

Step 6: Install the Figma Plugin

1. Open Figma Desktop
2. Go to Plugins → Development → Import plugin from manifest...
3. Select: figma-unified-mcp/figma-plugin/manifest.json
4. The plugin "Figma Unified MCP Bridge" is now installed

Step 7: Connect Plugin to MCP

1. In Figma, go to Plugins → Development → Figma Unified MCP Bridge
2. Click Connect (default settings: localhost:18211, channel figma)
3. Status should show "Connected" ✅

</details>

---

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

Alias	Command	Alias	Command
file	get-file	mv	move-node
node	get-node	rm	delete-node
find	search	cp	clone-node
styles	get-styles	fill	set-fill
vars	get-variables	text	set-text
snap	screenshot	frame	create-frame
svg	export-svg	rect	create-rectangle
a11y	check-accessibility	comp	create-component
new-var	create-variable	set-var	set-variable-value
del-var	delete-variable	new-collection	create-variable-collection

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:

Profile	Tools	Token cost	Best for
minimal	43	~3,500/msg	Claude $20 plan, daily design work
standard	71	~6,500/msg	Prototyping + variables + code connect + advanced modify
full	112	~9,800/msg	Full power, all features

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)

Tool	Description
figma_status	Check MCP server and plugin connection status
figma_connect_plugin	Connect to the Figma plugin via WebSocket
figma_send_command	Send a raw command to the Figma plugin

Utility Tools (3)

Tool	Description
figma_cache	Inspect or clear the in-memory library/component/style cache
figma_run	Escape hatch to run any tool by name (for non-full profiles)
figma_skill	Run a registered agent skill/prompt by name

Read Tools (32)

Tool	Description
figma_get_file	Get full file structure and metadata
figma_get_node	Get a specific node by ID
figma_get_nodes	Get multiple nodes by IDs
figma_get_styles	Get styles (fileKey → REST API, omit → plugin local styles)
figma_get_components	Get components (source: file/local/library)
figma_get_variables	Get all variables/design tokens
figma_get_comments	Get all comments on a file
figma_post_comment	Add a comment to a file
figma_search	Search for nodes by name or type
figma_get_selection	Get currently selected nodes in Figma
figma_get_team_components	Get published components from team libraries
figma_get_team_styles	Get published styles from team libraries
figma_get_component	Get details of a specific component by key
figma_get_style	Get details of a specific style by key
figma_get_library_items_used	Analyze which external library items a file uses
figma_get_file_versions	Get version history of a file
figma_get_team_projects	Get all projects in a team
figma_get_project_files	Get all files in a project
figma_scan_text_nodes	Scan text nodes with chunking for large designs
figma_scan_nodes_by_types	Find nodes by type (FRAME, TEXT, etc.)
figma_set_focus	Focus on a node and scroll viewport
figma_set_selections	Select multiple nodes and scroll to view
figma_get_library_collections	Get enabled library variable collections
figma_get_library_variables	Get variables from a library collection
figma_get_viewport	Get current viewport position and zoom
figma_import_component_by_key	Import a published component by key
figma_import_style_by_key	Import library styles by key (batch supported)
figma_get_code_connect_map	Get code connect mappings for components
figma_get_design_system_rules	Extract design system rules from current file
figma_export_png	Export a node as PNG/SVG/PDF via plugin
figma_create_page	Create a new page
figma_switch_page	Switch to a page by name, ID, or index

Visual/Export Tools (4)

Tool	Description
figma_get_images	Export nodes as PNG/JPG/SVG/PDF via REST API
figma_screenshot	Screenshot one or more nodes (nodeId or nodeIds[]) as base64
figma_export_svg	Export a node as SVG code
figma_export_to_file	Export a node to a local file (PNG/JPG/SVG/PDF) with configurable scale

Create Tools (10)

Tool	Description
figma_create_frame	Create a new frame/artboard
figma_create_rectangle	Create a rectangle shape
figma_create_ellipse	Create an ellipse/circle
figma_create_text	Create a text layer
figma_create_component	Create a reusable component
figma_create_instance	Create an instance of a component
figma_create_line	Create a line
figma_create_path	Create a vector path from points (straight or smooth curves)
figma_create_from_svg	Create a vector node from raw SVG markup
figma_batch	Batch multiple create/modify/variable ops in one round-trip

Modify Tools (19)

Tool	Description
figma_move_node	Move a node to x, y position
figma_resize_node	Resize a node's width/height
figma_set_fill	Set fills — solid color, linear/radial/angular/diamond gradients, or images
figma_set_stroke	Set border/stroke color and weight
figma_set_opacity	Set node opacity
figma_set_visible	Show or hide a node
figma_set_corner_radius	Set border radius
figma_set_text_content	Change text (single nodeId+content or batch updates[])
figma_set_text_style	Set font size, weight, family — or use 16 built-in presets (e.g., heading-xl, body-md)
figma_rename_node	Rename a node
figma_delete_node	Delete nodes (single nodeId or batch nodeIds[])
figma_clone_node	Clone/duplicate a node with offset
figma_set_auto_layout	Configure auto-layout (flexbox)
figma_set_effects	Add shadows, blurs, glows
figma_group_nodes	Group multiple nodes
figma_set_constraints	Set resize constraints
figma_reparent_node	Move node to different parent
figma_get_annotations	Get annotations on nodes
figma_set_annotation	Set annotation (single nodeId+label or batch annotations[])

Instance Override Tools (2)

Tool	Description
figma_get_instance_overrides	Extract instance overrides
figma_set_instance_overrides	Apply overrides to instances

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

Tool	Description	Transport
figma_create_variable_collection	Create a variable collection	REST API
figma_create_variable	Create a design token variable	REST API
figma_set_variable_value	Set variable value for a mode	REST API
figma_update_variable	Update variable name/description/scopes	REST API
figma_delete_variable	Delete a variable	REST API
figma_delete_variable_collection	Delete a variable collection	REST API
figma_bind_variable	Bind a variable to a node property	Plugin
figma_create_style	Create a reusable style	Plugin
figma_apply_style	Apply a style to a node by ID or by name	Plugin
figma_import_style_by_key	Import library styles by key (batch supported)	Plugin

Prototype Tools (10)

Tool	Description
figma_create_interaction	Add click/hover interaction
figma_remove_interactions	Remove all interactions from node
figma_create_flow	Create a prototype flow starting point
figma_remove_flow	Remove a flow starting point
figma_get_flows	List all flows on current page
figma_set_default_transition	Set default transition for frame
figma_setup_overlay	Configure overlay behavior
figma_set_scroll_behavior	Set scroll direction
figma_get_interactions	Get all interactions on a node
figma_present_prototype	Prepare to present prototype

Design Quality Tools (3)

Tool	Description
figma_boolean_operation	Boolean ops (union, subtract, intersect, exclude)
figma_check_accessibility	Check contrast ratios and touch target sizes
figma_validate_layout	Verify spacing, alignment, and overflow

Code Connect Tools (4)

Tool	Description	Profile
figma_scan_codebase	Scan a local directory for UI components (React, Vue, Svelte, Angular, Swift, Flutter, Compose)	standard+
figma_match_components	Fuzzy-match Figma components to code components with confidence scores	standard+
figma_publish_dev_resources	Publish code file URLs to Figma Dev Mode (bulk)	standard+
figma_get_dev_resources	Get existing dev resource links from a Figma file	standard+

Code Generation Tools (9)

Tool	Description	Profile
figma_generate_css	Generate CSS from node styles	full
figma_generate_react	Generate React component	full
figma_generate_swiftui	Generate SwiftUI view	full
figma_generate_html	Generate semantic HTML	full
figma_generate_tailwind_config	Generate Tailwind config	full
figma_generate_tokens	Export design tokens	full
figma_generate_handoff_spec	Generate developer handoff spec	full
figma_codegen_bundle	Generate a complete code bundle (HTML + CSS + JS)	standard+
figma_analyze_for_codegen	Analyze for best codegen approach	full

---

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