x-talk-to-figma-mcp

This workspace includes a local MCP server ("TalkToFigma") that talks to a Figma plugin via a local WebSocket relay.

Mental model

• •Figma plugin connects to a local WebSocket server (default localhost:3055) and joins a channel (by default: cursor).
• •TalkToFigma MCP server connects to the same WebSocket server and joins the same channel.
• •Cursor calls MCP tools; the MCP server forwards commands to the plugin; the plugin applies them to the open Figma file.

If any of the 3 pieces isn't running/connected, tool calls will fail or appear to do nothing.

One-time setup

1. Add the MCP server to Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bun",
      "args": [
        "/Users/audaciousaspen/brain/git/personal/cursor-talk-to-figma-mcp/src/talk_to_figma_mcp/server.ts"
      ],
      "disabled": false
    }
  }
}

Restart Cursor or reload MCP servers. Confirm TalkToFigma shows as connected (green dot) in Cursor Settings → MCP.

2. Install the Figma plugin (local development plugin)

In Figma:

1. •Click Plugins → Development → Import plugin from manifest...
2. •Select: ~/brain/git/personal/cursor-talk-to-figma-mcp/src/cursor_mcp_plugin/manifest.json

This registers the plugin locally. You only need to do this once per machine.

Per-session startup

1. Start the WebSocket relay

cd ~/brain/git/personal/cursor-talk-to-figma-mcp
bun socket

Keep this running in a terminal. It listens on port 3055.

2. Run the plugin in Figma

1. •Open the Figma file you want to work with
2. •Click Plugins → Development → Cursor MCP Plugin
3. •Confirm the plugin panel shows: "Connected to server on port 3055 in channel: cursor"

Preconditions (must be true before using tools)

• •The WebSocket relay is running (bun socket)
• •In Figma, the plugin is open and shows Connected to port 3055 in channel cursor
• •In Cursor, the MCP server TalkToFigma is enabled/connected (green dot)

First step: join the channel

Always join the channel before sending commands (or when reconnecting):

• •Tool: join_channel
• •Args: channel: "cursor" (or whatever the plugin is using)

Creating a "hello world" rectangle (example)

• •Tool: create_rectangle
• •Args:
  • •x, y, width, height (required)
  • •name (optional)

Typical example:

• •x: 100, y: 100, width: 240, height: 120, name: "hello world"

Adding centered text inside a rectangle (reliable workflow)

There isn't a single "center text in shape" command, so do it deterministically:

1. •Find the rectangle bounds

• •Tool: get_nodes_info
• •Args: nodeIds: ["<RECT_ID>"]
• •Use absoluteBoundingBox → { x, y, width, height }

1. •Create the text

• •Tool: create_text
• •Args (minimum):
  • •x, y (temporary; can be top-left of the rectangle)
  • •text: "hello world"
• •Optional but useful:
  • •fontSize (e.g. 24)
  • •fontWeight (e.g. 600)
  • •name (e.g. "hello world label")

1. •Measure the text

• •Tool: get_nodes_info
• •Args: nodeIds: ["<TEXT_ID>"]
• •Use its absoluteBoundingBox → { width, height }

1. •Move the text to center

• •Tool: move_node
• •Args:
  • •nodeId: "<TEXT_ID>"
  • •x: rectX + (rectW - textW)/2
  • •y: rectY + (rectH - textH)/2

This produces a visually centered result without guessing.

Debugging checklist (fast)

• •If calls fail with "must join channel" or timeouts:
  • •Run join_channel again (use the plugin's channel name).
• •If calls succeed but nothing changes in Figma:
  • •Confirm the plugin panel still shows connected to the same port and channel.
  • •Confirm you're editing the intended file/page in Figma.
• •If Cursor can't see the tools or they error immediately:
  • •Check Cursor MCP settings: TalkToFigma enabled/connected.
  • •Restart the MCP server and/or Cursor if it's stuck.