talktofigma-desktop-mcp

TalkToFigma Desktop MCP

Skill by ara.so — Design Skills collection.

TalkToFigma Desktop is a cross-platform desktop application that bridges Figma and AI coding assistants through the Model Context Protocol (MCP). It provides 50+ MCP tools for reading and manipulating Figma designs, enabling AI agents to directly interact with design files through a WebSocket server and stdio-based MCP servers.

Architecture Overview

MCP Client (Cursor/Claude Code) → stdio MCP Server → WebSocket (port 3055) → Desktop App → Figma Plugin

The desktop app manages:

• WebSocket server on port 3055 for real-time communication
• stdio MCP servers spawned independently by each AI client
• Channel-based routing for multi-client support
• System tray interface for server management

Installation

1. Install Desktop Application

Download from GitHub Releases:

• macOS: TalkToFigma-v*.*.*.zip (Universal binary)
• Windows: TalkToFigma-v*.*.*.exe

First run on macOS: Right-click app → "Open" → "Open" (bypass Gatekeeper)

First run on Windows: SmartScreen → "More info" → "Run anyway"

2. Install Figma Plugin

Install the Talk to Figma MCP Plugin from Figma Community.

3. Configure MCP Client

For Cursor, Claude Code, or VS Code with Cline:

1. Launch TalkToFigma Desktop
2. Right-click tray icon → "Settings"
3. Copy the MCP configuration path shown
4. Add to your MCP client config:

macOS (~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "TalkToFigmaDesktop": {
      "command": "node",
      "args": [
        "/Users/yourname/Library/Application Support/TalkToFigma/mcp-server.cjs"
      ]
    }
  }
}

Windows Direct Install (%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json):

{
  "mcpServers": {
    "TalkToFigmaDesktop": {
      "command": "node",
      "args": [
        "%APPDATA%\\TalkToFigma\\mcp-server.cjs"
      ]
    }
  }
}

Windows Store/MSIX: Use the exact path from Settings page (usually under %LOCALAPPDATA%\Packages\...\LocalCache\Roaming\TalkToFigma\mcp-server.cjs)

Starting the Server

1. Launch TalkToFigma Desktop from Applications/Start Menu
2. Start WebSocket server: Right-click tray icon → "Start Server"
3. Verify status: Tray icon should show green (🟢 Active)
4. Open Figma: Run the Talk to Figma MCP plugin
5. Connect: Plugin should show "Connected" status

MCP Tools Reference

Core Connection Tools

join_channel

Join a Figma file channel to start interacting with it.

Parameters:

• channel (string): Format {file_key}:{page_id}:{view_id}

Usage:

// Extract from Figma URL: https://www.figma.com/design/ABC123/Project?node-id=1-2&t=xyz
// Format: ABC123:1:2
await use_mcp_tool("TalkToFigmaDesktop", "join_channel", {
  channel: "ABC123:1:2"
});

leave_channel

Leave the current Figma file channel.

await use_mcp_tool("TalkToFigmaDesktop", "leave_channel", {});

Reading Design Data

get_current_page

Get the currently active page in Figma.

const page = await use_mcp_tool("TalkToFigmaDesktop", "get_current_page", {});
// Returns: { id: "1:2", name: "Page 1", type: "PAGE" }

get_node_by_id

Retrieve a specific node by its ID.

const node = await use_mcp_tool("TalkToFigmaDesktop", "get_node_by_id", {
  nodeId: "123:456"
});
// Returns complete node data including children, properties, styles

get_all_nodes

Get all nodes in the current page with optional filtering.

const allFrames = await use_mcp_tool("TalkToFigmaDesktop", "get_all_nodes", {
  type: "FRAME"
});

const allComponents = await use_mcp_tool("TalkToFigmaDesktop", "get_all_nodes", {
  type: "COMPONENT"
});

search_nodes

Search for nodes by name or type.

const buttons = await use_mcp_tool("TalkToFigmaDesktop", "search_nodes", {
  query: "Button",
  type: "COMPONENT"
});

get_selection

Get currently selected nodes in Figma.

const selection = await use_mcp_tool("TalkToFigmaDesktop", "get_selection", {});
// Returns: [{ id: "123:456", name: "Selected Frame", type: "FRAME" }]

Creating and Modifying Nodes

create_rectangle

Create a rectangle node.

await use_mcp_tool("TalkToFigmaDesktop", "create_rectangle", {
  name: "Background",
  x: 0,
  y: 0,
  width: 375,
  height: 812,
  fills: JSON.stringify([{
    type: "SOLID",
    color: { r: 0.95, g: 0.95, b: 0.95 }
  }])
});

create_frame

Create a frame container.

await use_mcp_tool("TalkToFigmaDesktop", "create_frame", {
  name: "Mobile Screen",
  x: 100,
  y: 100,
  width: 375,
  height: 812
});

create_text

Create a text node.

await use_mcp_tool("TalkToFigmaDesktop", "create_text", {
  name: "Heading",
  characters: "Welcome to TalkToFigma",
  x: 20,
  y: 40,
  fontSize: 24,
  fontName: JSON.stringify({ family: "Inter", style: "Bold" })
});

create_component

Create a reusable component.

await use_mcp_tool("TalkToFigmaDesktop", "create_component", {
  name: "Button/Primary",
  x: 0,
  y: 0,
  width: 120,
  height: 44
});

set_properties

Modify properties of existing nodes.

await use_mcp_tool("TalkToFigmaDesktop", "set_properties", {
  nodeId: "123:456",
  properties: JSON.stringify({
    name: "Updated Button",
    x: 50,
    y: 50,
    fills: [{
      type: "SOLID",
      color: { r: 0.2, g: 0.4, b: 0.8 }
    }]
  })
});

delete_node

Delete a node by ID.

await use_mcp_tool("TalkToFigmaDesktop", "delete_node", {
  nodeId: "123:456"
});

Layout and Positioning

set_auto_layout

Apply auto layout to a frame.

await use_mcp_tool("TalkToFigmaDesktop", "set_auto_layout", {
  nodeId: "123:456",
  mode: "VERTICAL",
  padding: 16,
  spacing: 12,
  primaryAxisAlignItems: "MIN",
  counterAxisAlignItems: "CENTER"
});

group_nodes

Group multiple nodes together.

await use_mcp_tool("TalkToFigmaDesktop", "group_nodes", {
  nodeIds: JSON.stringify(["123:456", "123:457", "123:458"]),
  name: "Button Group"
});

Styles and Design Tokens

get_local_paint_styles

Get all local color styles.

const colors = await use_mcp_tool("TalkToFigmaDesktop", "get_local_paint_styles", {});
// Returns: [{ id: "S:...", name: "Primary/Blue", paints: [...] }]

get_local_text_styles

Get all local text styles.

const textStyles = await use_mcp_tool("TalkToFigmaDesktop", "get_local_text_styles", {});
// Returns: [{ id: "S:...", name: "Heading/H1", fontSize: 32, ... }]

create_paint_style

Create a new color style.

await use_mcp_tool("TalkToFigmaDesktop", "create_paint_style", {
  name: "Brand/Primary",
  paints: JSON.stringify([{
    type: "SOLID",
    color: { r: 0.2, g: 0.4, b: 0.8 }
  }])
});

apply_paint_style

Apply a color style to a node.

await use_mcp_tool("TalkToFigmaDesktop", "apply_paint_style", {
  nodeId: "123:456",
  styleId: "S:abc123..."
});

Export and Assets

export_node

Export a node as an image.

const imageData = await use_mcp_tool("TalkToFigmaDesktop", "export_node", {
  nodeId: "123:456",
  format: "PNG",
  scale: 2
});
// Returns base64-encoded image data

get_image_fills

Get image fill data from nodes.

const images = await use_mcp_tool("TalkToFigmaDesktop", "get_image_fills", {
  nodeId: "123:456"
});

Common Workflows

Extract Design Tokens

// 1. Join the Figma file
await use_mcp_tool("TalkToFigmaDesktop", "join_channel", {
  channel: "FILE_KEY:PAGE_ID:VIEW_ID"
});

// 2. Get all color styles
const colors = await use_mcp_tool("TalkToFigmaDesktop", "get_local_paint_styles", {});

// 3. Get all text styles
const typography = await use_mcp_tool("TalkToFigmaDesktop", "get_local_text_styles", {});

// 4. Convert to design tokens
const tokens = {
  colors: colors.map(style => ({
    name: style.name.replace(/\//g, '-'),
    value: rgbToHex(style.paints[0].color)
  })),
  typography: typography.map(style => ({
    name: style.name.replace(/\//g, '-'),
    fontSize: style.fontSize,
    fontFamily: style.fontName.family,
    fontWeight: style.fontName.style
  }))
};

Build Component Library

// 1. Search for all components
const components = await use_mcp_tool("TalkToFigmaDesktop", "get_all_nodes", {
  type: "COMPONENT"
});

// 2. For each component, get detailed properties
for (const comp of components) {
  const details = await use_mcp_tool("TalkToFigmaDesktop", "get_node_by_id", {
    nodeId: comp.id
  });
  
  // 3. Generate React component code
  const componentCode = generateReactComponent(details);
  // Write to file system...
}

Sync Design Changes to Code

// 1. Get current selection in Figma
const selection = await use_mcp_tool("TalkToFigmaDesktop", "get_selection", {});

// 2. For each selected node
for (const node of selection) {
  const nodeData = await use_mcp_tool("TalkToFigmaDesktop", "get_node_by_id", {
    nodeId: node.id
  });
  
  // 3. Update corresponding code file
  const cssProperties = {
    width: `${nodeData.width}px`,
    height: `${nodeData.height}px`,
    backgroundColor: rgbToHex(nodeData.fills[0].color),
    borderRadius: `${nodeData.cornerRadius}px`
  };
  
  // Update CSS/styled-components...
}

Create UI from Specification

// 1. Join channel
await use_mcp_tool("TalkToFigmaDesktop", "join_channel", {
  channel: "FILE_KEY:PAGE_ID:VIEW_ID"
});

// 2. Create mobile frame
await use_mcp_tool("TalkToFigmaDesktop", "create_frame", {
  name: "Mobile/Login",
  x: 0,
  y: 0,
  width: 375,
  height: 812
});

// 3. Get the created frame
const frames = await use_mcp_tool("TalkToFigmaDesktop", "search_nodes", {
  query: "Mobile/Login",
  type: "FRAME"
});
const frameId = frames[0].id;

// 4. Set auto layout
await use_mcp_tool("TalkToFigmaDesktop", "set_auto_layout", {
  nodeId: frameId,
  mode: "VERTICAL",
  padding: 24,
  spacing: 16
});

// 5. Add heading
await use_mcp_tool("TalkToFigmaDesktop", "create_text", {
  name: "Title",
  characters: "Welcome Back",
  fontSize: 28,
  fontName: JSON.stringify({ family: "Inter", style: "Bold" })
});

// 6. Add input fields, buttons, etc.

Configuration

Environment Variables

TalkToFigma Desktop doesn't require API keys, but the stdio server path varies by platform:

# macOS
TALKTOFIGMA_STDIO_PATH="$HOME/Library/Application Support/TalkToFigma/mcp-server.cjs"

# Windows (Direct Install)
TALKTOFIGMA_STDIO_PATH="%APPDATA%\TalkToFigma\mcp-server.cjs"

# Windows (Store/MSIX)
# Check Settings page for exact path under LocalCache

WebSocket Port

Default port: 3055

To verify the server is running:

# macOS/Linux
lsof -i :3055

# Windows
netstat -ano | findstr :3055

Multi-Client Setup

Each AI client spawns its own stdio server process. All connect to the same WebSocket server (port 3055).

Cursor config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "TalkToFigmaDesktop": {
      "command": "node",
      "args": ["/path/to/mcp-server.cjs"]
    }
  }
}

Claude Code config (~/.claude/mcp.json):

{
  "mcpServers": {
    "TalkToFigmaDesktop": {
      "command": "node",
      "args": ["/path/to/mcp-server.cjs"]
    }
  }
}

Troubleshooting

Server Won't Start

Check logs:

1. Right-click tray icon → "Terminal"
2. Look for error messages

Common issues:

• Port 3055 already in use: Kill conflicting process or restart
• Firewall blocking: Allow TalkToFigma through firewall

macOS port check:

lsof -i :3055
kill -9 <PID>

Windows port check:

netstat -ano | findstr :3055
taskkill /PID <PID> /F

Plugin Can't Connect

Verify:

1. Desktop app is running (tray icon visible)
2. WebSocket server is active (green icon 🟢)
3. Figma plugin is running in the same file

Reset connection:

1. Right-click tray → "Stop Server"
2. Wait 5 seconds
3. Right-click tray → "Start Server"
4. Restart Figma plugin

MCP Client Can't Find Server

Check stdio path:

macOS:

ls -la ~/Library/Application\ Support/TalkToFigma/mcp-server.cjs

Windows:

dir "%APPDATA%\TalkToFigma\mcp-server.cjs"

If missing:

1. Restart TalkToFigma Desktop (installs stdio server on launch)
2. Check Settings page for correct path
3. Manually verify file exists

Channel Not Joined Error

Always call join_channel before any other operations:

// Extract channel from Figma URL
// https://www.figma.com/design/ABC123/Project?node-id=1-2
const channel = "ABC123:1:2";

await use_mcp_tool("TalkToFigmaDesktop", "join_channel", { channel });

// Now other operations work
const page = await use_mcp_tool("TalkToFigmaDesktop", "get_current_page", {});

Node ID Format Issues

Figma node IDs use format 123:456. Extract from:

• Plugin selection: figma.currentPage.selection[0].id
• URL parameters: node-id=123-456 → convert to 123:456

// Convert URL format to ID format
const nodeId = urlNodeId.replace(/-/g, ':'); // "123-456" → "123:456"

Building from Source

# Clone repository
git clone https://github.com/grab/TalkToFigmaDesktop.git
cd TalkToFigmaDesktop

# Install dependencies
npm install

# Development mode
npm start

# Build package
npm run package

# Create installer
npm run make

Output locations:

• Development: Electron starts with hot reload
• Package: out/TalkToFigma-{platform}-{arch}/
• Installers: out/make/

API Reference Summary

Tool	Purpose	Key Parameters
join_channel	Connect to Figma file	channel
get_current_page	Get active page	-
get_node_by_id	Fetch node details	nodeId
get_all_nodes	List all nodes	type (optional)
search_nodes	Search by name/type	query, type
get_selection	Get selected nodes	-
create_rectangle	Create rectangle	x, y, width, height
create_frame	Create frame	x, y, width, height
create_text	Create text	characters, fontSize
create_component	Create component	name, width, height
set_properties	Update node	nodeId, properties
delete_node	Remove node	nodeId
set_auto_layout	Apply auto layout	nodeId, mode, padding
get_local_paint_styles	Get color styles	-
get_local_text_styles	Get text styles	-
export_node	Export as image	nodeId, format, scale

Full tool list available in desktop app Terminal logs on startup.