Quick Start

Overview

This guide will get you up and running with Talk to Figma MCP in just a few minutes. You’ll install dependencies, configure your AI agent, start the WebSocket server, and connect the Figma plugin.

This quick start uses the automated setup script. For manual installation and advanced configuration, see the Installation guide.

Prerequisites

Before you begin, make sure you have:

Bun installed (installation instructions)
Cursor or Claude Code installed
Figma Desktop App or browser access to Figma
Terminal access

Step 1: Install Bun

If you haven’t installed Bun yet, run:

curl -fsSL https://bun.sh/install | bash

Bun is a fast JavaScript runtime and toolkit that provides better performance than Node.js for this project.

Step 2: Run Automated Setup

Clone the repository and run the setup script:

git clone https://github.com/grab/cursor-talk-to-figma-mcp.git
cd talk-to-figma-mcp
bun setup

The setup script will:

Install Dependencies

Runs bun install to install all required packages

Configure Cursor

Writes MCP configuration to .cursor/mcp.json

Configure Claude Code

Writes MCP configuration to .mcp.json

You should see confirmation messages:

✓ Cursor MCP config written to .cursor/mcp.json
✓ Claude Code MCP config written to .mcp.json

Step 3: Start the WebSocket Server

In your terminal, start the WebSocket relay server:

bun socket

You should see:

WebSocket server running on port 3055

Keep this terminal window open. The WebSocket server must be running for the MCP server to communicate with Figma.

Windows + WSL Users

If you’re using Windows with WSL, you need to uncomment one line in src/socket.ts:

src/socket.ts

const server = Bun.serve({
  port: 3055,
  // uncomment this to allow connections in windows wsl
  hostname: "0.0.0.0", // Uncomment this line
  fetch(req: Request, server: Server) {
    // ...
  }
});

Step 4: Install Figma Plugin

You have two options for installing the Figma plugin:

Community Plugin (Recommended)
Local Development

Install directly from the Figma Community:

Open Figma

Launch Figma Desktop or go to figma.com

Visit Community Page

Go to the Talk to Figma MCP Plugin

Install Plugin

Click “Install” to add it to your Figma account

Install the plugin locally from the repository:

Open Figma

Launch Figma Desktop

Go to Plugins Menu

Click Plugins → Development → New Plugin

Link Existing Plugin

Choose “Link existing plugin”

Select Manifest

Navigate to and select: src/cursor_mcp_plugin/manifest.json

The plugin files are not bundled. The code.js file is used directly as the runtime artifact.

Step 5: Connect to Channel

Now connect the Figma plugin to the WebSocket server:

Open Plugin in Figma

In any Figma file, go to Plugins → Talk to Figma MCP Plugin (or your development plugin)

Join a Channel

In your AI agent (Cursor/Claude Code), run the join_channel tool:

Use the join_channel tool to connect to the default channel

Or specify a custom channel name:

{
  "channel": "my-design-session"
}

Verify Connection

You should see a confirmation message in the plugin UI and in your terminal

Terminal output should show:

✓ Client joined channel "default" (2 total clients)

Step 6: Test Your Setup

Let’s verify everything works by getting document information:

Open a Figma File

Make sure you have a Figma file open with some content

Get Document Info

In your AI agent, ask:

Get information about the current Figma document

The agent will use the get_document_info tool

Check Response

You should receive JSON with document details:

{
  "name": "My Design File",
  "id": "...",
  "type": "DOCUMENT",
  "children": [...]
}

Your First Design Automation

Now that everything is set up, try a simple design automation:

Example 1: Create a Rectangle

Create a blue rectangle at position (100, 100) with width 200 and height 150

The AI agent will use the create_rectangle tool:

{
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 150,
  "name": "Blue Rectangle",
  "fillColor": {
    "r": 0,
    "g": 0.5,
    "b": 1,
    "a": 1
  }
}

Colors in Figma use RGBA values in the 0-1 range, not 0-255.

Example 2: Read Selected Elements

Select some elements in your Figma file
Ask your AI agent:

Read my current selection and describe the elements

The agent will use get_selection or read_my_design to extract information about the selected nodes.

Example 3: Bulk Text Replacement

Scan all text nodes in the current page and replace "Product" with "Service"

The agent will:

Use scan_text_nodes to find all text nodes
Filter nodes containing “Product”
Use set_multiple_text_contents to update them in batch

For large designs with 100+ nodes, operations are automatically chunked with progress updates to prevent Figma from freezing.

Common Commands

Here are some common commands to try:

Document Analysis

“Get document information”
“What’s currently selected?”
“Read the design structure”
“Show me all annotations”

Element Creation

“Create a frame at (0, 0) with size 375x812”
“Add a text node that says ‘Hello World’”
“Create a component instance from [component name]”

Text Operations

“Scan all text nodes in the current page”
“Replace all instances of ‘old text’ with ‘new text’”
“Update the text of node [id] to ‘new content’”

Layout & Styling

“Set this frame to horizontal auto-layout”
“Change the fill color to red”
“Add 16px padding to all sides”
“Set corner radius to 8px”

Best Practices

Always Join Channel First

Call join_channel before any other commands to establish the WebSocket connection

Get Context First

Use get_document_info and get_selection before making modifications to understand the structure

Use Batch Operations

For multiple updates, use batch tools like set_multiple_text_contents instead of individual calls

Verify Changes

Use get_node_info after modifications to confirm changes were applied correctly

Troubleshooting

WebSocket connection failed

Make sure bun socket is running in a terminal
Check that port 3055 is not blocked by a firewall
For WSL users, ensure hostname: "0.0.0.0" is uncommented in src/socket.ts

Plugin not responding

Verify the plugin is running in Figma
Check that you’ve called join_channel successfully
Look for error messages in the browser console (Plugins → Development → Open Console)

Command timeout

Operations timeout after 30 seconds by default
For large operations, progress updates reset the inactivity timer
Check the WebSocket server logs for error messages

'No other clients in channel' warning

This means the Figma plugin hasn’t joined the same channel
Make sure the plugin is running and has called join_channel
Verify both the MCP server and plugin are using the same channel name

Next Steps

API Reference

Explore all 50+ available tools and their parameters

Advanced Usage

Learn about prompts, chunking, and complex workflows

Examples

View real-world examples and use cases

Contributing

Contribute to the project on GitHub

Get Help

If you run into issues:

Check the Installation guide for detailed setup instructions
Review the Document & Selection API for tool documentation
Open an issue on GitHub
Watch the video tutorial

You’re now ready to automate your Figma workflows with AI! Start experimenting with different commands and explore the full API.

Get Started

Core Concepts

Guides

Best Practices

Overview

Prerequisites

Step 1: Install Bun

Step 2: Run Automated Setup

Step 3: Start the WebSocket Server

Windows + WSL Users

Step 4: Install Figma Plugin

Step 5: Connect to Channel

Step 6: Test Your Setup

Your First Design Automation

Example 1: Create a Rectangle

Example 2: Read Selected Elements

Example 3: Bulk Text Replacement

Common Commands

Best Practices

Always Join Channel First

Get Context First

Use Batch Operations

Verify Changes

Troubleshooting

Next Steps

API Reference

Advanced Usage

Examples

Contributing

Get Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Best Practices

​Overview

​Prerequisites

​Step 1: Install Bun

​Step 2: Run Automated Setup

​Step 3: Start the WebSocket Server

​Windows + WSL Users

​Step 4: Install Figma Plugin

​Step 5: Connect to Channel

​Step 6: Test Your Setup

​Your First Design Automation

​Example 1: Create a Rectangle

​Example 2: Read Selected Elements

​Example 3: Bulk Text Replacement

​Common Commands

​Best Practices

Always Join Channel First

Get Context First

Use Batch Operations

Verify Changes

​Troubleshooting

​Next Steps

API Reference

Advanced Usage

Examples

Contributing

​Get Help

Build docs developers (and LLMs) love

Overview

Prerequisites

Step 1: Install Bun

Step 2: Run Automated Setup

Step 3: Start the WebSocket Server

Windows + WSL Users

Step 4: Install Figma Plugin

Step 5: Connect to Channel

Step 6: Test Your Setup

Your First Design Automation

Example 1: Create a Rectangle

Example 2: Read Selected Elements

Example 3: Bulk Text Replacement

Common Commands

Best Practices

Troubleshooting

Next Steps

Get Help