Windows + WSL Setup

This guide covers the specific steps needed to set up Talk to Figma MCP on Windows using WSL, including important network configuration for cross-platform communication.

Prerequisites

Before you begin, ensure you have:

Windows 10 version 2004 or higher, or Windows 11
WSL 2 installed and configured
A Linux distribution installed (Ubuntu recommended)
Figma Desktop running on Windows (not in WSL)

WSL Installation

If you haven’t installed WSL yet:

Enable WSL

Open PowerShell as Administrator and run:

wsl --install

This installs WSL 2 and Ubuntu by default.

Restart your computer

After installation completes, restart Windows.

Set up your Linux user

When you first launch WSL, you’ll be prompted to create a username and password.

Installing Bun on Windows

For the WebSocket server to be accessible from Windows (where Figma runs), install Bun on Windows:

Open PowerShell

Open PowerShell (not as Administrator).

Install Bun

Run the Bun installation command:

powershell -c "irm bun.sh/install.ps1|iex"

This installs Bun natively on Windows.

Verify installation

bun --version

Project Setup

Clone the repository in Windows

In PowerShell:

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

Install dependencies

bun install

Run the setup script

bun setup

This creates the necessary MCP configuration files.

Critical: Configure WebSocket Server for WSL

The most important step for Windows + WSL setup is configuring the WebSocket server to listen on all network interfaces:

Open the socket configuration file

Edit src/socket.ts in your preferred editor.

Uncomment the hostname configuration

Find this section in the file (around line 43-44):

const server = Bun.serve({
  port: 3055,
  // uncomment this to allow connections in windows wsl
  // hostname: "0.0.0.0",

Uncomment the hostname line:

const server = Bun.serve({
  port: 3055,
  // uncomment this to allow connections in windows wsl
  hostname: "0.0.0.0",

This allows the server to accept connections from Windows (where Figma runs).

Save the file

Save your changes to src/socket.ts.

Without setting hostname: "0.0.0.0", the WebSocket server will only listen on localhost within WSL and won’t be accessible from Windows, causing connection failures.

Starting the WebSocket Server

Start the server

In PowerShell, from the project directory:

bun socket

You should see:

WebSocket server running on port 3055

Verify accessibility

The server should now be accessible at ws://localhost:3055 from both Windows and WSL.

MCP Server Configuration

For Cursor on Windows

If using Cursor on Windows:

Locate or create MCP config

The config file should be at:

C:\Users\YourUsername\.cursor\mcp.json

Or in your project root:

.cursor\mcp.json

Add the configuration

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

Restart Cursor

Restart Cursor to load the configuration.

For Cursor/Claude Code in WSL

If running your AI agent inside WSL:

Install Bun in WSL

Inside your WSL terminal:

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

Run setup in WSL

cd /mnt/c/path/to/talk-to-figma-mcp
bun setup

Configure MCP

Create .mcp.json in your WSL home directory or project root:

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

Figma Plugin Setup

Install the Figma plugin

Follow the standard Figma Plugin Setup guide to install the plugin in Figma Desktop on Windows.

Connect to WebSocket

In the plugin UI, use:

ws://localhost:3055

This works because the server is running on Windows with hostname: "0.0.0.0".

Join a channel

Enter a channel name and click “Join Channel”.

Network Architecture

Understanding the network flow in Windows + WSL:

Figma (Windows) ←→ WebSocket Server (Windows:3055) ←→ MCP Server (Windows/WSL) ←→ Cursor/Claude (Windows/WSL)

Key points:

Figma runs on Windows host
WebSocket server runs on Windows with 0.0.0.0 binding
MCP server can run on either Windows or WSL
AI agent (Cursor/Claude) can run on either Windows or WSL

Troubleshooting

Connection refused errors

Hostname not set to 0.0.0.0

This is the most common issue. Verify that you’ve uncommented:

hostname: "0.0.0.0",

in src/socket.ts.

Firewall blocking connection

Windows Firewall might block the connection. When you first run bun socket, Windows may prompt you to allow network access. Click “Allow”.If you missed the prompt:

Open Windows Defender Firewall
Click “Allow an app or feature through Windows Defender Firewall”
Find “bun” and ensure both Private and Public networks are checked

Wrong network interface

Ensure you’re using localhost or 127.0.0.1 in the Figma plugin, not WSL-specific IP addresses.

Performance issues

Slow file access

When working with files in /mnt/c/, WSL can be slow. Consider:

Cloning the repo in WSL’s native filesystem (~/projects/)
Running the WebSocket server on Windows instead

Network latency

WSL 2 uses a virtualized network. If you experience latency:

Run the WebSocket server on Windows
Keep the project files on the Windows filesystem

WSL version issues

Using WSL 1 instead of WSL 2

Check your WSL version:

wsl -l -v

Convert to WSL 2 if needed:

wsl --set-version Ubuntu 2

Best Practices for Windows + WSL

Run server on Windows

For best performance, run the WebSocket server on Windows where Figma is running.

Use Windows filesystem

Store project files on Windows filesystem (C:\) rather than WSL filesystem for better performance.

Install Bun on both

Install Bun on both Windows and WSL for maximum flexibility.

Always set hostname

Remember to set hostname: "0.0.0.0" in the WebSocket server configuration.

Recommended Setup

For optimal performance on Windows + WSL:

Project location: Windows filesystem (C:\Users\YourName\projects\talk-to-figma-mcp)
Bun installation: Windows (for running the server)
WebSocket server: Run on Windows with hostname: "0.0.0.0"
MCP server: Can run on either Windows or WSL
AI agent: Use Cursor on Windows for best performance

This setup minimizes cross-platform overhead and provides the smoothest experience.

Get Started

Core Concepts

Guides

Best Practices

Prerequisites

WSL Installation

Installing Bun on Windows

Project Setup

Critical: Configure WebSocket Server for WSL

Starting the WebSocket Server

MCP Server Configuration

For Cursor on Windows

For Cursor/Claude Code in WSL

Figma Plugin Setup

Network Architecture

Troubleshooting

Connection refused errors

Performance issues

WSL version issues

Best Practices for Windows + WSL

Run server on Windows

Use Windows filesystem

Install Bun on both

Always set hostname

Recommended Setup

Next Steps

Cursor Setup

Figma Plugin

​Prerequisites

​WSL Installation

​Installing Bun on Windows

​Project Setup

​Critical: Configure WebSocket Server for WSL

​Starting the WebSocket Server

​MCP Server Configuration

​For Cursor on Windows

​For Cursor/Claude Code in WSL

​Figma Plugin Setup

​Network Architecture

​Troubleshooting

​Connection refused errors

​Performance issues

​WSL version issues

​Best Practices for Windows + WSL

Run server on Windows

Use Windows filesystem

Install Bun on both

Always set hostname

​Recommended Setup

​Next Steps

Cursor Setup

Figma Plugin

Prerequisites

WSL Installation

Installing Bun on Windows

Project Setup

Critical: Configure WebSocket Server for WSL

Starting the WebSocket Server

MCP Server Configuration

For Cursor on Windows

For Cursor/Claude Code in WSL

Figma Plugin Setup

Network Architecture

Troubleshooting

Connection refused errors

Performance issues

WSL version issues

Best Practices for Windows + WSL

Recommended Setup

Next Steps