./setup.sh

.\setup.bat

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

What Figma tools do you have available?

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

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

# 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

# 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

# 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'

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

## 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>`

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

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

What colors and text styles are defined in file ABC123xyz?

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

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

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

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

Export all design tokens from my file as CSS variables

: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;
}

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

What comments are on file ABC123xyz? Are any unresolved?

/audit_design_system

fileKey: ABC123xyz

Convert the profile card to SwiftUI code

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

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

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

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

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

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

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

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

┌─────────────────┐     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

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

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

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

# 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

# MCP server + CLI
npm run build

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

# Run tests
npm test

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

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