# Figma Console MCP Server

Figma Console MCP is a Model Context Protocol (MCP) server that bridges AI assistants (like Claude) with Figma, enabling comprehensive design system workflows including extraction, creation, debugging, and variable management. It provides 58+ tools for reading design data, creating UI components, managing design tokens/variables, debugging Figma plugins, and validating design-code parity. The server supports multiple connection modes: Local Mode (NPX/Git) for full capabilities with real-time monitoring, Cloud Mode for web AI clients without Node.js, and Remote SSE for read-only exploration.

The architecture centers around the Desktop Bridge Plugin which connects to Figma Desktop via WebSocket, enabling both read and write operations through the Figma Plugin API. This approach allows variable management on any Figma plan (not just Enterprise), real-time selection tracking, document change monitoring, and console log capture. The server can run locally via NPX or be deployed to Cloudflare Workers, with automatic port fallback (9223-9232) supporting multiple simultaneous MCP client connections.

## Installation and Configuration

### NPX Setup (Recommended)

Install and configure the MCP server for Claude Code, Cursor, Windsurf, or Claude Desktop.

```bash
# Claude Code CLI setup
claude mcp add figma-console -s user \
  -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE \
  -e ENABLE_MCP_APPS=true \
  -- npx -y figma-console-mcp@latest

# Verify installation
npx figma-console-mcp@latest --print-path
# Output: /Users/you/.npm/_npx/.../node_modules/figma-console-mcp
```

```json
// MCP config for Claude Desktop, Cursor, Windsurf
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}
```

### Local Git Setup

Clone and build for development or contribution.

```bash
# Clone, install, and build
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run build:local

# Development mode with hot reload
npm run dev:local

# Run tests
npm test
```

```json
// MCP config for local Git installation
{
  "mcpServers": {
    "figma-console": {
      "command": "node",
      "args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}
```

## Navigation and Status Tools

### figma_navigate

Open a Figma URL to initialize monitoring and set the current file context for subsequent API calls.

```javascript
// Navigate to a specific Figma file
figma_navigate({
  url: 'https://www.figma.com/design/abc123xyz/My-Design-System?node-id=1-2'
})

// Response
{
  "success": true,
  "currentUrl": "https://www.figma.com/design/abc123xyz/My-Design-System?node-id=1-2",
  "fileKey": "abc123xyz",
  "nodeId": "1-2"
}
```

### figma_get_status

Check connection status and validate the setup. Returns WebSocket transport status, connected file info, and setup instructions if not connected.

```javascript
// Check connection status
figma_get_status()

// Response when connected via WebSocket
{
  "mode": "local",
  "setup": {
    "valid": true,
    "message": "✅ Figma Desktop connected via WebSocket (Desktop Bridge Plugin)",
    "transport": "websocket"
  },
  "connectedFile": {
    "name": "My Design System",
    "key": "abc123xyz",
    "currentPage": "Components"
  },
  "transport": {
    "type": "websocket",
    "port": 9223,
    "preferredPort": 9223,
    "portFallbackUsed": false,
    "otherInstances": []
  }
}

// Response when not connected
{
  "mode": "local",
  "setup": {
    "valid": false,
    "message": "❌ No connection to Figma Desktop",
    "setupInstructions": {
      "step1": "Install Desktop Bridge Plugin: Figma → Plugins → Development → Import from manifest",
      "step2": "Run the plugin in your Figma file"
    }
  }
}
```

## Design System Extraction Tools

### figma_get_design_system_kit

Extract your entire design system—tokens, components, and styles—in a single optimized call. Returns visual specs (exact colors, padding, typography, layout), rendered screenshots, and token values per mode.

```javascript
// Full design system extraction
figma_get_design_system_kit({
  fileKey: "abc123xyz"
})

// Targeted extraction with images
figma_get_design_system_kit({
  fileKey: "abc123xyz",
  include: ["tokens", "components"],
  componentIds: ["1:234", "5:678"],
  includeImages: true,
  format: "full"  // "full" | "summary" | "compact"
})

// Response structure
{
  "fileKey": "abc123xyz",
  "fileName": "My Design System",
  "generatedAt": "2025-01-15T10:30:00Z",
  "format": "full",
  "tokens": {
    "collections": [{
      "name": "Colors",
      "modes": [{ "name": "Light", "modeId": "1:0" }, { "name": "Dark", "modeId": "1:1" }],
      "variables": [{
        "name": "primary",
        "type": "COLOR",
        "valuesByMode": {
          "Light": { "r": 0.26, "g": 0.46, "b": 1 },
          "Dark": { "r": 0.37, "g": 0.64, "b": 0.98 }
        }
      }]
    }],
    "summary": { "totalCollections": 3, "totalVariables": 45 }
  },
  "components": {
    "items": [{
      "name": "Button",
      "key": "abc123",
      "properties": { "variant": { "type": "VARIANT", "values": ["primary", "secondary"] }},
      "visualSpec": {
        "fills": [{ "type": "SOLID", "color": "#4375FF" }],
        "cornerRadius": 8,
        "layout": { "mode": "HORIZONTAL", "paddingTop": 12, "paddingLeft": 24 }
      }
    }],
    "summary": { "totalComponents": 12 }
  },
  "styles": {
    "items": [{ "name": "Primary/Default", "styleType": "FILL", "resolvedValue": { "fills": [{ "color": "#4375FF" }] }}],
    "summary": { "totalStyles": 28 }
  }
}
```

### figma_get_variables

Extract design tokens/variables with optional code exports (CSS, Tailwind, Sass). Supports branch URLs and automatic file detection.

```javascript
// Basic variable extraction
figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123xyz'
})

// With code exports and usage analysis
figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123xyz',
  includePublished: true,
  enrich: true,
  export_formats: ['css', 'tailwind', 'sass'],
  include_usage: true,
  include_dependencies: true
})

// Branch URL support
figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123xyz/branch/xyz789/My-File'
})

// Response with CSS export
{
  "collections": [{
    "name": "Colors",
    "modes": [{ "modeId": "1:0", "name": "Light" }],
    "variables": [{
      "id": "VariableID:1:1",
      "name": "colors/primary/500",
      "resolvedType": "COLOR",
      "valuesByMode": { "1:0": { "r": 0.23, "g": 0.51, "b": 0.96 } }
    }]
  }],
  "exports": {
    "css": ":root {\n  --colors-primary-500: #3B82F6;\n}"
  }
}
```

### figma_get_component

Get component data in metadata format (for documentation) or reconstruction format (for programmatic creation).

```javascript
// Metadata format for documentation
figma_get_component({
  fileUrl: 'https://figma.com/design/abc123xyz',
  nodeId: '123:456',
  format: 'metadata',
  enrich: true
})

// Reconstruction format for programmatic creation
figma_get_component({
  fileUrl: 'https://figma.com/design/abc123xyz',
  nodeId: '123:456',
  format: 'reconstruction'
})

// Response (metadata format)
{
  "component": {
    "id": "123:456",
    "name": "Button",
    "description": "Primary action button",
    "properties": {
      "variant": { "type": "VARIANT", "values": ["primary", "secondary"] },
      "size": { "type": "VARIANT", "values": ["sm", "md", "lg"] }
    },
    "bounds": { "width": 120, "height": 40 }
  }
}
```

### figma_get_component_for_development

Get component data optimized for UI implementation, including a rendered image and filtered layout/visual properties.

```javascript
figma_get_component_for_development({
  fileUrl: 'https://figma.com/design/abc123xyz',
  nodeId: '695:313',
  includeImage: true
})

// Response
{
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "component": {
    "name": "Card",
    "layout": {
      "layoutMode": "VERTICAL",
      "itemSpacing": 16,
      "paddingTop": 24,
      "paddingRight": 24,
      "paddingBottom": 24,
      "paddingLeft": 24
    },
    "visual": {
      "fills": [{ "type": "SOLID", "color": "#FFFFFF" }],
      "cornerRadius": 12,
      "effects": [{ "type": "DROP_SHADOW", "radius": 8 }]
    }
  }
}
```

## Design Creation Tools (Local Mode & Cloud Mode)

### figma_execute

Execute any Figma Plugin API code to create designs, modify elements, or perform complex operations. This is the primary tool for design creation.

```javascript
// Create a button component with auto-layout
figma_execute({
  code: `
    // Create frame with auto-layout
    const button = figma.createFrame();
    button.name = "Button";
    button.resize(120, 40);
    button.cornerRadius = 8;
    button.fills = [{ type: 'SOLID', color: { r: 0.23, g: 0.51, b: 0.96 } }];

    // Configure auto-layout
    button.layoutMode = "HORIZONTAL";
    button.primaryAxisAlignItems = "CENTER";
    button.counterAxisAlignItems = "CENTER";
    button.paddingLeft = 16;
    button.paddingRight = 16;
    button.paddingTop = 8;
    button.paddingBottom = 8;

    // Add text
    await figma.loadFontAsync({ family: "Inter", style: "Medium" });
    const text = figma.createText();
    text.characters = "Click me";
    text.fontName = { family: "Inter", style: "Medium" };
    text.fontSize = 14;
    text.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
    button.appendChild(text);

    // Position at viewport center and select
    button.x = figma.viewport.center.x - button.width / 2;
    button.y = figma.viewport.center.y - button.height / 2;
    figma.currentPage.selection = [button];

    return { nodeId: button.id, name: button.name, width: button.width, height: button.height };
  `,
  timeout: 10000
})

// Response
{
  "success": true,
  "result": {
    "nodeId": "1:234",
    "name": "Button",
    "width": 120,
    "height": 40
  }
}
```

### figma_instantiate_component

Create an instance of an existing component on the canvas.

```javascript
// Search for component first
figma_search_components({ query: "Button" })

// Then instantiate with overrides
figma_instantiate_component({
  componentKey: "abc123def456",
  x: 100,
  y: 200,
  overrides: {
    "Button Label": "Submit",
    "Show Icon": true
  }
})

// Response
{
  "success": true,
  "instance": {
    "nodeId": "1:567",
    "name": "Button",
    "componentKey": "abc123def456"
  }
}
```

### figma_arrange_component_set

Organize component variants into a professional component set with row/column labels and Figma's purple dashed border styling.

```javascript
figma_arrange_component_set({
  componentSetId: "123:456",
  options: {
    gap: 24,
    cellPadding: 20,
    columnProperty: "State"
  }
})

// Or find by name
figma_arrange_component_set({
  componentSetName: "Button"
})

// Response
{
  "success": true,
  "componentSet": {
    "id": "123:456",
    "name": "Button",
    "variantCount": 12,
    "layout": {
      "rows": ["Primary", "Secondary", "Ghost"],
      "columns": ["Default", "Hover", "Pressed", "Disabled"]
    }
  }
}
```

## Variable Management Tools (Local Mode & Cloud Mode)

### figma_setup_design_tokens

Create a complete design token structure in one atomic operation: collection, modes, and all variables. Values are keyed by mode name (not mode ID).

```javascript
figma_setup_design_tokens({
  collectionName: "Brand Tokens",
  modes: ["Light", "Dark"],
  tokens: [
    {
      name: "color/background",
      resolvedType: "COLOR",
      description: "Page background",
      values: { "Light": "#FFFFFF", "Dark": "#1A1A2E" }
    },
    {
      name: "color/text/primary",
      resolvedType: "COLOR",
      values: { "Light": "#111827", "Dark": "#F9FAFB" }
    },
    {
      name: "spacing/page",
      resolvedType: "FLOAT",
      values: { "Light": 24, "Dark": 24 }
    },
    {
      name: "radius/button",
      resolvedType: "FLOAT",
      values: { "Light": 8, "Dark": 8 }
    }
  ]
})

// Response
{
  "success": true,
  "message": "Created collection 'Brand Tokens' with 2 modes and 4 tokens (0 failed)",
  "collectionId": "VariableCollectionId:1:1",
  "collectionName": "Brand Tokens",
  "modes": { "Light": "1:0", "Dark": "1:1" },
  "created": 4,
  "failed": 0,
  "results": [
    { "success": true, "name": "color/background", "id": "VariableID:1:1" },
    { "success": true, "name": "color/text/primary", "id": "VariableID:1:2" },
    { "success": true, "name": "spacing/page", "id": "VariableID:1:3" },
    { "success": true, "name": "radius/button", "id": "VariableID:1:4" }
  ]
}
```

### figma_batch_create_variables

Create multiple variables in a single operation—10-50x faster than individual calls.

```javascript
figma_batch_create_variables({
  collectionId: "VariableCollectionId:123:456",
  variables: [
    {
      name: "colors/primary/500",
      resolvedType: "COLOR",
      description: "Primary brand color",
      valuesByMode: { "1:0": "#3B82F6", "1:1": "#60A5FA" }
    },
    {
      name: "colors/primary/600",
      resolvedType: "COLOR",
      valuesByMode: { "1:0": "#2563EB", "1:1": "#3B82F6" }
    },
    {
      name: "spacing/md",
      resolvedType: "FLOAT",
      valuesByMode: { "1:0": 16 }
    }
  ]
})

// Response
{
  "success": true,
  "message": "Batch created 3 variables (0 failed)",
  "created": 3,
  "failed": 0,
  "results": [
    { "success": true, "name": "colors/primary/500", "id": "VariableID:1:1" },
    { "success": true, "name": "colors/primary/600", "id": "VariableID:1:2" },
    { "success": true, "name": "spacing/md", "id": "VariableID:1:3" }
  ]
}
```

### figma_batch_update_variables

Update multiple variable values in a single operation.

```javascript
figma_batch_update_variables({
  updates: [
    { variableId: "VariableID:1:1", modeId: "1:0", value: "#2563EB" },
    { variableId: "VariableID:1:2", modeId: "1:0", value: "#1D4ED8" },
    { variableId: "VariableID:1:3", modeId: "1:0", value: 20 }
  ]
})

// Response
{
  "success": true,
  "message": "Batch updated 3 variables (0 failed)",
  "updated": 3,
  "failed": 0
}
```

### figma_create_variable_collection

Create a new variable collection with optional modes.

```javascript
figma_create_variable_collection({
  name: "Brand Colors",
  initialModeName: "Light",
  additionalModes: ["Dark", "High Contrast"]
})

// Response
{
  "success": true,
  "collection": {
    "id": "VariableCollectionId:1:1",
    "name": "Brand Colors",
    "modes": [
      { "modeId": "1:0", "name": "Light" },
      { "modeId": "1:1", "name": "Dark" },
      { "modeId": "1:2", "name": "High Contrast" }
    ]
  }
}
```

### figma_add_mode

Add a new mode to an existing collection (e.g., Dark mode, Mobile breakpoint).

```javascript
figma_add_mode({
  collectionId: "VariableCollectionId:123:456",
  modeName: "Dark"
})

// Response
{
  "success": true,
  "mode": {
    "modeId": "1:1",
    "name": "Dark"
  }
}
```

## Console and Debugging Tools

### figma_get_console_logs

Retrieve console logs from Figma plugins with filtering options. Works immediately in Local Mode without navigation.

```javascript
// Get last 20 error logs
figma_get_console_logs({
  count: 20,
  level: 'error'
})

// Get all logs from last 30 seconds
figma_get_console_logs({
  since: Date.now() - 30000
})

// Response
{
  "logs": [
    {
      "timestamp": 1705312800000,
      "level": "error",
      "message": "TypeError: Cannot read property 'fills' of undefined",
      "stackTrace": "at processNode (code.js:45:12)\n  at main (code.js:23:5)"
    },
    {
      "timestamp": 1705312799000,
      "level": "log",
      "message": "[Main] Processing 15 nodes"
    }
  ],
  "count": 2
}
```

### figma_watch_console

Stream console logs in real-time for a specified duration.

```javascript
figma_watch_console({
  duration: 60,  // Watch for 60 seconds (max: 300)
  level: 'all'
})

// Response after duration
{
  "logs": [...],
  "summary": {
    "total": 45,
    "byLevel": { "log": 30, "warn": 10, "error": 5 }
  },
  "duration": 60
}
```

### figma_take_screenshot

Capture screenshots of the Figma canvas or specific nodes.

```javascript
figma_take_screenshot({
  target: 'viewport',  // 'plugin' | 'full-page' | 'viewport'
  format: 'png',
  quality: 90,
  nodeId: '123:456'  // Optional: specific node
})

// Response
{
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "png"
  }
}
```

## Design-Code Parity Tools

### figma_check_design_parity

Compare Figma component specs against code implementation. Produces a scored parity report with actionable fix items.

```javascript
figma_check_design_parity({
  fileUrl: 'https://figma.com/design/abc123xyz',
  nodeId: '695:313',
  codeSpec: {
    visual: {
      backgroundColor: '#FFFFFF',
      borderRadius: 12,
      borderColor: '#E4E4E7'
    },
    spacing: {
      paddingTop: 24,
      paddingRight: 24,
      paddingBottom: 24,
      paddingLeft: 24,
      gap: 16
    },
    componentAPI: {
      props: [
        { name: 'variant', type: "'default' | 'outline'", required: false },
        { name: 'children', type: 'ReactNode', required: true }
      ]
    },
    metadata: {
      name: 'Card',
      filePath: 'src/components/card/card.tsx'
    }
  },
  canonicalSource: 'design',
  enrich: true
})

// Response
{
  "summary": {
    "totalDiscrepancies": 2,
    "parityScore": 85,
    "bySeverity": { "critical": 0, "major": 1, "minor": 1, "info": 0 }
  },
  "discrepancies": [
    {
      "property": "borderRadius",
      "category": "visual",
      "severity": "major",
      "designValue": 8,
      "codeValue": 12,
      "suggestion": "Update code to use 8px border-radius"
    }
  ],
  "actionItems": [
    {
      "action": "Update code",
      "property": "borderRadius",
      "from": 12,
      "to": 8
    }
  ]
}
```

### figma_generate_component_doc

Generate platform-agnostic markdown documentation by merging Figma design data with code-side info.

```javascript
figma_generate_component_doc({
  fileUrl: 'https://figma.com/design/abc123xyz',
  nodeId: '695:313',
  codeInfo: {
    importStatement: "import { Button } from '@mylib/ui'",
    props: [
      { name: 'variant', type: "'primary' | 'secondary'", defaultValue: "'primary'" },
      { name: 'size', type: "'sm' | 'md' | 'lg'", defaultValue: "'md'" }
    ],
    usageExamples: [
      { title: 'Basic', code: '<Button>Click me</Button>' },
      { title: 'Secondary', code: '<Button variant="secondary">Cancel</Button>' }
    ]
  },
  systemName: 'MyDesignSystem',
  includeFrontmatter: true
})

// Response
{
  "componentName": "Button",
  "markdown": "---\ntitle: Button\n...\n## Overview\n...",
  "suggestedOutputPath": "docs/components/button.md"
}
```

## Cloud Mode Tools

### figma_pair_plugin

Generate a pairing code to connect the Desktop Bridge plugin to the cloud relay. Enables web AI clients (Claude.ai, v0, Replit, Lovable) to create and modify Figma designs.

```javascript
// Generate pairing code
figma_pair_plugin()

// Response
{
  "success": true,
  "code": "ABC123",
  "expiresIn": "5 minutes",
  "instructions": "Enter this code in the Desktop Bridge plugin's Cloud Mode section"
}
```

## Node Manipulation Tools

### figma_resize_node, figma_move_node, figma_clone_node

Basic node manipulation operations available in Local and Cloud modes.

```javascript
// Resize a node
figma_resize_node({
  nodeId: "123:456",
  width: 200,
  height: 100
})

// Move a node
figma_move_node({
  nodeId: "123:456",
  x: 100,
  y: 200
})

// Clone a node
figma_clone_node({
  nodeId: "123:456"
})
// Returns: { "success": true, "newNodeId": "123:789" }

// Delete a node
figma_delete_node({
  nodeId: "123:456"
})

// Rename a node
figma_rename_node({
  nodeId: "123:456",
  newName: "Header Section"
})

// Set text content
figma_set_text({
  nodeId: "123:456",
  characters: "Hello World"
})

// Set fill colors
figma_set_fills({
  nodeId: "123:456",
  fills: [{ type: "SOLID", color: "#FF0000" }]
})
```

## Comments Tools

### figma_get_comments, figma_post_comment

Manage comments on Figma files via REST API.

```javascript
// Get comments
figma_get_comments({
  fileUrl: 'https://figma.com/design/abc123xyz',
  include_resolved: false,
  as_md: true
})

// Post comment pinned to a node
figma_post_comment({
  fileUrl: 'https://figma.com/design/abc123xyz',
  message: 'Border-radius should be 8px per design spec.',
  node_id: '695:313'
})

// Reply to existing comment
figma_post_comment({
  fileUrl: 'https://figma.com/design/abc123xyz',
  message: 'Fixed in the latest update.',
  reply_to_comment_id: '1627922741'
})

// Delete comment
figma_delete_comment({
  fileUrl: 'https://figma.com/design/abc123xyz',
  comment_id: '1627922741'
})
```

## Summary

Figma Console MCP Server enables comprehensive AI-assisted design workflows spanning the full design-to-development lifecycle. Primary use cases include: (1) **Design System Extraction** using `figma_get_design_system_kit` to feed actual tokens, components, and visual specs to AI code generators; (2) **Design Creation** using `figma_execute` to programmatically create UI components, frames, and layouts through natural language; (3) **Variable Management** using batch tools to efficiently create and update design tokens with multi-mode support; (4) **Plugin Debugging** using console log capture and screenshot validation for Figma plugin development; and (5) **Design-Code Parity** validation to ensure implementations match design specifications.

Integration patterns center around the Desktop Bridge Plugin which provides the WebSocket connection for all write operations. For Local Mode setups (NPX or Git), configure the MCP server in your AI client's config file and run the plugin in Figma Desktop. For Cloud Mode, web-based AI clients can pair with the plugin using a 6-character code to gain write access without local Node.js installation. The server supports multiple simultaneous connections via automatic port fallback (9223-9232), enabling use across multiple Claude Desktop tabs or different MCP clients. For design system workflows, prefer `figma_get_design_system_kit` over individual extraction tools as it provides comprehensive data in a single optimized call.