Installation - Talk to Figma MCP

Overview

This guide covers all installation methods for Talk to Figma MCP, including automated setup, manual configuration, and platform-specific instructions.

For a faster setup experience, see the Quick Start guide.

System Requirements

Required

Bun (recommended) or Node.js v18+
Figma Desktop App or Figma in Browser
Cursor or Claude Code with MCP support
Network Access: Localhost WebSocket (port 3055)

Platform Support

macOS

Full support with native Bun installation

Linux

Full support with native Bun installation

Windows

Requires additional WSL configuration

Installation Methods

Automated Setup (Recommended)
Manual Setup
NPM Package (Published)

The fastest way to get started:

Install Bun

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

Clone Repository

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

Run Setup Script

bun setup

This script will:

Install all dependencies with bun install
Create .cursor/mcp.json for Cursor
Create .mcp.json for Claude Code

Setup complete! Skip to Start WebSocket Server.

For advanced users who want full control:

Install Bun

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

Clone Repository

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

Install Dependencies

bun install

Build MCP Server

bun run build

This compiles TypeScript to JavaScript using tsup and outputs to dist/.

Configure MCP Clients

See MCP Configuration below.

Use the published npm package without cloning:

Install Bun

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

Configure MCP Client

Add to your MCP configuration:

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

Clone for WebSocket Server

You still need the repository for the WebSocket server:

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

The published package (cursor-talk-to-figma-mcp@latest) includes only the MCP server. The WebSocket relay and Figma plugin require the full repository.

MCP Configuration

Cursor Configuration

Create or edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

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

For local development, use the absolute path to server.ts, not a relative path.

Claude Code Configuration

You can configure Claude Code in two ways:

Option 1: Manual File Edit

Create or edit .mcp.json in your project root:

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

Option 2: CLI Command

Use the Claude Code CLI:

claude mcp add TalkToFigma -- bunx cursor-talk-to-figma-mcp@latest

Configuration Reference

command

string

required

The command to execute. Use bunx for published package or bun for local development.

args

array

required

Arguments passed to the command. For published package: ["cursor-talk-to-figma-mcp@latest"]. For local: ["/path/to/server.ts"].

env

object

Optional environment variables. Example:

{
  "env": {
    "PORT": "3055"
  }
}

Start WebSocket Server

The WebSocket relay must be running for the MCP server to communicate with Figma.

Basic Usage

In the repository directory:

bun socket

Expected output:

WebSocket server running on port 3055

Keep this terminal window open. The WebSocket server must run continuously while using Talk to Figma MCP.

Custom Port

To use a different port, set the PORT environment variable:

PORT=8080 bun socket

Development Mode

For development with auto-reload:

bun run dev

This runs the MCP server build in watch mode. Run bun socket in a separate terminal.

Figma Plugin Installation

Community Plugin (Recommended)

Visit Plugin Page

Go to the Figma Community page

Install Plugin

Click Install to add it to your Figma account

Run Plugin

In any Figma file: Plugins → Talk to Figma MCP Plugin

Local Development Plugin

For plugin development or customization:

Open Figma Desktop

The plugin development workflow requires Figma Desktop, not the browser version

Access Development Menu

Go to Plugins → Development → New Plugin

Link Existing Plugin

Choose “Link existing plugin”

Select Manifest

Navigate to the repository and select:

src/cursor_mcp_plugin/manifest.json

Plugin Available

The plugin is now available under Plugins → Development → Cursor MCP Plugin

The Figma plugin files are not bundled. The code.js file is used directly as the runtime artifact. Edit code.js and ui.html directly in the src/cursor_mcp_plugin/ directory.

Plugin Files

manifest.json

object

Plugin metadata including ID, permissions, and network access configuration

code.js

file

Plugin main thread that handles 30+ commands via a dispatcher

ui.html

file

Plugin UI for WebSocket connection management

Platform-Specific Setup

Windows + WSL

Windows users with WSL need an additional configuration step:

Install Bun in PowerShell

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

Modify socket.ts

Open src/socket.ts and uncomment the hostname line:

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) {
    // ...
  }
});

Start WebSocket Server

bun socket

Without setting hostname: "0.0.0.0", the WebSocket server won’t be accessible from Windows to WSL.

macOS

No additional configuration needed. Follow the standard installation steps.

Linux

No additional configuration needed. Follow the standard installation steps.

Verification

Verify your installation is working:

Check WebSocket Server

Terminal should show:

WebSocket server running on port 3055

Verify MCP Configuration

Open your AI agent (Cursor/Claude Code) and check that the TalkToFigma MCP server appears in the MCP servers list

Test Plugin Connection

Open Figma and run the plugin
In your AI agent, use the join_channel tool
Check terminal output for:

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

Test Basic Command

In your AI agent, ask:

Get information about the current Figma document

You should receive document details in JSON format

If all steps succeed, your installation is complete!

Troubleshooting

'bun: command not found'

Solution:

Restart your terminal after installing Bun
Verify installation: bun --version
Add Bun to PATH manually:

export PATH="$HOME/.bun/bin:$PATH"

Add this line to your .bashrc, .zshrc, or .profile

Port 3055 already in use

Solution:

Find the process using port 3055:

macOS/Linux

lsof -i :3055

Windows

netstat -ano | findstr :3055

Kill the process or use a different port:

PORT=8080 bun socket

WebSocket connection failed

Possible causes:

WebSocket server not running → Check bun socket is active
Firewall blocking port 3055 → Allow localhost connections
WSL without hostname config → Set hostname: "0.0.0.0"
Wrong channel name → Ensure MCP server and plugin use same channel

Debug steps:

Check server logs in terminal running bun socket
Open browser console: Plugins → Development → Open Console
Look for WebSocket connection errors

MCP server not showing in Cursor/Claude

Solution:

Verify configuration file location:
- Cursor: ~/.cursor/mcp.json or .cursor/mcp.json
- Claude: .mcp.json in project root
Check JSON syntax is valid
For local development, use absolute paths
Restart your AI agent

Build errors

Solution:

Clear dependencies and reinstall:

rm -rf node_modules
bun install

Verify Bun version:

bun --version

Should be v1.0.0 or higher.

Try building manually:

bun run build

Plugin not appearing in Figma

Solution:

For community plugin: Check you’re logged into Figma
For local plugin:
- Verify you selected the correct manifest.json file
- Check Plugins → Development menu
- Try relinking the plugin
Check plugin permissions in manifest.json:

"documentAccess": "dynamic-page",
"networkAccess": {
  "allowedDomains": ["ws://localhost:3055"]
}

Advanced Configuration

Custom WebSocket URL

The MCP server supports a custom WebSocket URL via command-line argument:

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": [
        "cursor-talk-to-figma-mcp@latest",
        "--server=myserver.com:8080"
      ]
    }
  }
}

Default: ws://localhost:3055

Environment Variables

PORT

string

default:"3055"

WebSocket server port

NODE_ENV

string

Set to development for additional logging

Example:

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

Multiple Instances

Run multiple independent instances using different channels:

Start WebSocket server once: bun socket
Configure multiple MCP servers with unique names
Join different channels for each instance

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

Then use join_channel with different channel names: "project1", "project2", etc.

Development Commands

For contributors and developers:

# Install dependencies
bun install

# Build MCP server (tsup → dist/)
bun run build

# Build in watch mode
bun run dev

# Start WebSocket relay
bun socket

# Run built MCP server
bun run start

# Full setup (install + config)
bun setup

# Publish to npm
bun run pub:release

There is no test suite or linter configured in this project.

Uninstallation

To remove Talk to Figma MCP:

Stop WebSocket Server

Press Ctrl+C in the terminal running bun socket

Remove MCP Configuration

Delete the TalkToFigma entry from:

~/.cursor/mcp.json (Cursor)
.mcp.json (Claude Code)

Remove Figma Plugin

In Figma: Plugins → Development → Right-click plugin → Unlink

Delete Repository

rm -rf talk-to-figma-mcp

Next Steps

Quick Start

Get up and running with hands-on examples

API Reference

Explore all 50+ available tools

Best Practices

Learn patterns for effective design automation

GitHub Repository

View source code and contribute

Get Help

If you encounter issues during installation:

Review the Quick Start guide for a simplified setup
Check the Troubleshooting section above
Open an issue on GitHub
Watch the video tutorial

Installation complete! Your Talk to Figma MCP is ready to use.

Get Started

Core Concepts

Guides

Best Practices

​Overview

​System Requirements

​Required

​Platform Support

macOS

Linux

Windows

​Installation Methods

​MCP Configuration

​Cursor Configuration

​Claude Code Configuration

​Option 1: Manual File Edit

​Option 2: CLI Command

​Configuration Reference

​Start WebSocket Server

​Basic Usage

​Custom Port

​Development Mode

​Figma Plugin Installation

​Community Plugin (Recommended)

​Local Development Plugin

​Plugin Files

​Platform-Specific Setup

​Windows + WSL

​macOS

​Linux

​Verification

​Troubleshooting

​Advanced Configuration

​Custom WebSocket URL

​Environment Variables

​Multiple Instances

​Development Commands

​Uninstallation

​Next Steps

Quick Start

API Reference

Best Practices

GitHub Repository

​Get Help

Build docs developers (and LLMs) love

Overview

System Requirements

Required

Platform Support

Installation Methods

MCP Configuration

Cursor Configuration

Claude Code Configuration

Option 1: Manual File Edit

Option 2: CLI Command

Configuration Reference

Start WebSocket Server

Basic Usage

Custom Port

Development Mode

Figma Plugin Installation

Community Plugin (Recommended)

Local Development Plugin

Plugin Files

Platform-Specific Setup

Windows + WSL

macOS

Linux

Verification

Troubleshooting

Advanced Configuration

Custom WebSocket URL

Environment Variables

Multiple Instances

Development Commands

Uninstallation

Next Steps

Get Help