# 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:**
```bash
./setup.sh
```

**Windows:**
```powershell
.\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](https://nodejs.org/)
- **Figma Desktop App** — [Download](https://www.figma.com/downloads/)
- **Claude Desktop** — [Download](https://claude.ai/download)
- **Figma Personal Access Token** — [Get one here](https://www.figma.com/developers/api#access-tokens)

### Step 1: Clone or Download

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

### Step 2: Install Dependencies

```bash
cd figma-unified-mcp
npm install
```

### Step 3: Build the MCP Server

```bash
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:**
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

Add the Figma MCP server:

**macOS / Linux:**
```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"
      }
    }
  }
}
```

**Windows:**
```json
{
  "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:**
```bash
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):**
```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:**
```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"
      }
    }
  }
}
```

**Windows:**
```json
{
  "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:

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

```bash
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`:
> ```bash
> 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

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

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

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

```bash
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`:

```markdown
## 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](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:
```json
{
  "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](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:**
```tsx
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:**
```css
: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:**
```swift
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:
```json
{
  "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`:
```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:**
```bash
# 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):**
```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

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

```bash
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](https://github.com/sso-ss)

## Credits

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- [Figma Plugin API](https://www.figma.com/plugin-docs/)
- [Figma REST API](https://www.figma.com/developers/api)