figma-console-mcp-design-system-api

Figma Console MCP Design System API

Skill by ara.so — Design Skills collection.

What is Figma Console MCP?

Figma Console MCP is a Model Context Protocol server that bridges AI assistants with Figma, providing 103 tools for design system extraction, component creation, bidirectional token synchronization, and visual debugging. It enables AI to read, create, and modify Figma designs programmatically.

Key capabilities:

• Design extraction - Pull variables, components, styles, and full design trees
• Bidirectional token sync - Export variables to DTCG JSON + CSS, push edits back to Figma
• Component creation - Create frames, shapes, text, and instantiate components
• Variable management - Create, update, rename, delete design tokens
• Visual debugging - Screenshot nodes, scan accessibility, diff versions
• FigJam & Slides - Create stickies, flowcharts, presentations
• Real-time monitoring - Watch console logs and selection changes (Desktop Bridge)

Installation

NPX Setup (Recommended)

Prerequisites:

• Node.js 18+
• Figma Desktop app
• Figma personal access token (create one)

Configuration for Claude Code:

claude mcp add figma-console -s user \
  -e FIGMA_ACCESS_TOKEN=$FIGMA_ACCESS_TOKEN \
  -e ENABLE_MCP_APPS=true \
  -- npx -y figma-console-mcp@latest

Configuration for other MCP clients (Cursor, Windsurf, Claude Desktop):

Add to your MCP config file:

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}

Config file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Desktop Bridge Plugin Setup

The Desktop Bridge plugin enables write operations (component creation, variable management):

1. Open Figma Desktop
2. Go to Plugins → Development → Import plugin from manifest
3. Select ~/.figma-console-mcp/plugin/manifest.json
4. Run the plugin in your Figma file

The plugin auto-connects to the MCP server on ports 9223-9232.

Environment Variables

# Required
FIGMA_ACCESS_TOKEN=figd_xxx  # Personal access token

# Optional
ENABLE_MCP_APPS=true         # Enable Desktop Bridge plugin
LOG_LEVEL=info               # debug | info | warn | error

Core Tool Categories

1. Design System Extraction

Get file metadata:

// Tool: figma_get_file
{
  "file_key": "abc123xyz"
}
// Returns: Full design tree with components, variables, styles

Extract design tokens:

// Tool: figma_export_tokens
{
  "file_key": "abc123xyz",
  "output_format": "dtcg-json"  // or "css-custom-properties"
}
// Returns: DTCG JSON with all variables across collections/modes

List local variables:

// Tool: figma_get_local_variables
{
  "file_key": "abc123xyz"
}
// Returns: All color, number, string, boolean variables

2. Component & Frame Creation

Create a basic frame:

// Tool: figma_create_frame
{
  "name": "Hero Section",
  "width": 1200,
  "height": 600,
  "background_color": "#0066FF"
}
// Returns: Created frame node with ID

Create text node:

// Tool: figma_create_text
{
  "parent_id": "frame-node-id",
  "content": "Welcome to Design System",
  "font_size": 48,
  "font_weight": 700,
  "color": "#FFFFFF"
}

Create rectangle with gradient:

// Tool: figma_create_rectangle
{
  "parent_id": "frame-id",
  "width": 300,
  "height": 200,
  "fill": {
    "type": "GRADIENT_LINEAR",
    "gradientStops": [
      {"position": 0, "color": "#FF0080"},
      {"position": 1, "color": "#7928CA"}
    ]
  },
  "corner_radius": 16
}

Instantiate component:

// Tool: figma_create_instance
{
  "component_key": "component-key-from-library",
  "parent_id": "frame-id",
  "x": 100,
  "y": 100
}

3. Variable & Token Management

Create color variable:

// Tool: figma_create_variable
{
  "file_key": "abc123xyz",
  "collection_name": "Brand Colors",
  "name": "primary/500",
  "type": "COLOR",
  "value": "#0066FF"
}

Update variable value:

// Tool: figma_update_variable
{
  "file_key": "abc123xyz",
  "variable_id": "var-id",
  "value": "#0055DD"
}

Bidirectional token sync workflow:

// 1. Export tokens to DTCG JSON
// Tool: figma_export_tokens
{
  "file_key": "abc123xyz",
  "output_format": "dtcg-json"
}
// Save response to tokens.json

// 2. Edit tokens.json locally (change hex values, etc.)

// 3. Import changes back to Figma
// Tool: figma_import_tokens
{
  "file_key": "abc123xyz",
  "tokens": {
    "color": {
      "primary": {
        "$type": "color",
        "$value": "#0055DD"
      }
    }
  }
}
// Only changed values trigger API calls (diff-aware merge)

4. Visual Debugging & Screenshots

Screenshot a node:

// Tool: figma_get_image
{
  "file_key": "abc123xyz",
  "node_ids": ["node-id-1"],
  "format": "png",
  "scale": 2
}
// Returns: Base64-encoded PNG or image URL

Screenshot with selection context:

// Tool: figma_screenshot_selection
{} // Screenshots currently selected node in Figma Desktop

5. Accessibility Scanning

Run design accessibility audit:

// Tool: figma_accessibility_scan
{
  "file_key": "abc123xyz",
  "node_id": "frame-id"
}
// Returns: 14 WCAG checks (contrast, touch targets, etc.)

Component accessibility scorecard:

// Tool: figma_accessibility_component_scorecard
{
  "file_key": "abc123xyz"
}
// Returns: Per-component breakdown of accessibility issues

6. Version History & Diffing

List file versions:

// Tool: figma_get_versions
{
  "file_key": "abc123xyz"
}

Diff two versions:

// Tool: figma_diff_versions
{
  "file_key": "abc123xyz",
  "version_a": "v1.0",
  "version_b": "v2.0"
}
// Returns: Added/removed/changed nodes

Binary-search blame (find when property was introduced):

// Tool: figma_blame
{
  "file_key": "abc123xyz",
  "node_path": "Frame → Button",
  "property": "cornerRadius"
}
// Returns: Version where property first appeared

Common Patterns

Extract Design System to CSS Variables

// 1. Export all tokens
const tokens = await figma_export_tokens({
  file_key: "abc123xyz",
  output_format: "css-custom-properties"
});

// 2. Write to CSS file
// tokens.css_output contains:
// :root {
//   --color-primary-500: #0066FF;
//   --spacing-md: 16px;
// }

Create Button Component from Scratch

// 1. Create frame
const frame = await figma_create_frame({
  name: "Button/Primary",
  width: 120,
  height: 44,
  background_color: "#0066FF"
});

// 2. Add text
await figma_create_text({
  parent_id: frame.id,
  content: "Click me",
  font_size: 16,
  color: "#FFFFFF",
  text_align: "CENTER"
});

// 3. Add auto-layout
await figma_set_properties({
  node_id: frame.id,
  properties: {
    layoutMode: "HORIZONTAL",
    primaryAxisAlignItems: "CENTER",
    counterAxisAlignItems: "CENTER",
    paddingLeft: 24,
    paddingRight: 24
  }
});

Sync Design Tokens with Code

// Pull tokens from Figma
const figmaTokens = await figma_export_tokens({
  file_key: "abc123xyz",
  output_format: "dtcg-json"
});

// Merge with local modifications
const localTokens = JSON.parse(fs.readFileSync('tokens.json'));
const merged = { ...figmaTokens, ...localTokens };

// Push changes back
await figma_import_tokens({
  file_key: "abc123xyz",
  tokens: merged
});

Monitor Design Changes in Real-Time

// Requires Desktop Bridge plugin running

// Watch console logs
await figma_watch_console({
  duration_seconds: 300  // 5 minutes
});

// Watch selection changes
await figma_watch_selection({
  duration_seconds: 60
});

// Watch document changes
await figma_watch_document({
  duration_seconds: 120
});

Create FigJam Board Elements

// Create sticky note
await figma_create_sticky({
  file_key: "figjam-key",
  text: "User feedback",
  color: "YELLOW",
  x: 100,
  y: 100
});

// Create flowchart connector
await figma_create_connector({
  file_key: "figjam-key",
  start_node_id: "sticky-1",
  end_node_id: "sticky-2",
  connector_type: "ARROW"
});

// Create table
await figma_create_table({
  file_key: "figjam-key",
  rows: 3,
  columns: 4,
  x: 500,
  y: 200
});

Configuration Best Practices

Token Scopes Required

Your Figma personal access token needs:

• File content (Read) - Required for all read operations
• File versions (Read) - For version history tools
• Variables (Read/Write) - For token management
• Comments (Read/Write) - For collaboration tools

Desktop Bridge Plugin Updates

When to re-import the plugin:

• Release notes explicitly mention plugin changes (v1.22.4, v1.10.0)
• New transport methods added (WebSocket → MessageChannel)
• Plugin shows "connection failed" despite server running

How to re-import:

1. Plugins → Manage plugins
2. Re-import ~/.figma-console-mcp/plugin/manifest.json
3. Restart the plugin

The stable path never changes, so it's a one-click update.

Troubleshooting

"Connection failed" in Desktop Bridge

Symptoms: Plugin shows red "Failed to connect"

Solutions:

1. Verify ENABLE_MCP_APPS=true in your MCP config
2. Restart Figma Desktop completely
3. Check server is running: ps aux | grep figma-console-mcp
4. Verify plugin scans ports 9223-9232: check plugin console logs
5. Re-import plugin manifest if after major version update

"Unauthorized" errors

Symptoms: All API calls return 401/403

Solutions:

1. Verify FIGMA_ACCESS_TOKEN is set correctly
2. Check token hasn't expired (tokens don't expire but can be revoked)
3. Verify token has required scopes (File content, Variables)
4. Try creating a new token with all scopes enabled

Write operations fail (create_frame, create_variable)

Symptoms: Tools return "Desktop Bridge required" or "Read-only mode"

Solutions:

1. Install and run Desktop Bridge plugin
2. Verify ENABLE_MCP_APPS=true is set
3. Check plugin shows green "Connected" status
4. Switch from Remote SSE to NPX/Local Git setup (SSE is read-only)

Token import shows "no changes detected"

Symptoms: figma_import_tokens returns "0 changes applied"

Solutions:

1. Verify DTCG JSON format is correct ($type, $value keys)
2. Check variable names match exactly (case-sensitive)
3. Use figma_export_tokens first to see canonical structure
4. Ensure collection/mode names match existing Figma structure

Screenshots return blank images

Symptoms: figma_get_image returns white/transparent image

Solutions:

1. Verify node IDs are correct (use figma_get_file to list nodes)
2. Check node isn't hidden or has zero dimensions
3. Try different scale values (0.5, 1, 2)
4. For selection screenshots, ensure node is selected in Figma Desktop

Tool Count by Category

• File operations: 12 tools (get_file, get_versions, diff_versions, etc.)
• Node creation: 18 tools (create_frame, create_text, create_rectangle, etc.)
• Variable management: 14 tools (create, update, rename, delete variables)
• Token sync: 2 tools (export_tokens, import_tokens)
• Visual debugging: 8 tools (screenshots, accessibility scans)
• FigJam: 11 tools (stickies, connectors, tables, code blocks)
• Slides: 9 tools (create decks, add slides, manage content)
• Real-time monitoring: 6 tools (watch console, selection, document)
• Component operations: 15 tools (instantiate, detach, swap)
• Dev mode: 8 tools (inspect, measure, export code)

Total: 103 tools

Resources

• Documentation: https://docs.figma-console-mcp.southleft.com
• GitHub: https://github.com/southleft/figma-console-mcp
• npm: https://www.npmjs.com/package/figma-console-mcp
• Changelog: CHANGELOG.md
• Figma API Docs: https://www.figma.com/developers/api