System Architecture

Overview

Talk to Figma MCP uses a three-component pipeline architecture to enable seamless communication between AI agents (like Claude Code or Cursor) and Figma designs. This architecture ensures reliable, real-time interaction with Figma while maintaining the MCP protocol standard.

Architecture Diagram

Claude Code / Cursor ←(stdio)→ MCP Server ←(WebSocket)→ WebSocket Relay ←(WebSocket)→ Figma Plugin

Each component plays a specific role in the pipeline:

MCP Server

Protocol handler that exposes 50+ tools to AI agents

WebSocket Relay

Message router with channel-based isolation

Figma Plugin

In-canvas executor that modifies designs

MCP Server

The MCP server (src/talk_to_figma_mcp/server.ts) is the protocol adapter between AI agents and Figma. It implements the Model Context Protocol using @modelcontextprotocol/sdk.

Key Responsibilities

Tool Registration: Exposes 50+ tools for creating shapes, modifying text, managing layouts, exporting images, and more
Prompt Strategies: Provides AI prompts for design best practices and workflows
Request Management: Tracks all outgoing requests with UUIDs in a pendingRequests Map
Timeout Handling: Manages 30-second timeouts with progress update support
Protocol Translation: Converts MCP tool calls into WebSocket messages

Communication Flow

AI Agent sends tool request

The agent calls a tool like create_frame() via stdio

Server validates parameters

Zod schemas validate all input parameters

Server generates UUID

A unique request ID is created using uuidv4()

Server sends WebSocket message

The request is forwarded to the WebSocket relay

Server awaits response

The promise is stored in pendingRequests with timeout callbacks

Code Example: Request Lifecycle

server.ts

function sendCommandToFigma(
  command: FigmaCommand,
  params: unknown = {},
  timeoutMs: number = 30000
): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const id = uuidv4();
    const request = {
      id,
      type: "message",
      channel: currentChannel,
      message: {
        id,
        command,
        params: {
          ...params,
          commandId: id,
        },
      },
    };

    // Set timeout for request
    const timeout = setTimeout(() => {
      if (pendingRequests.has(id)) {
        pendingRequests.delete(id);
        reject(new Error('Request to Figma timed out'));
      }
    }, timeoutMs);

    // Store callbacks for later resolution
    pendingRequests.set(id, {
      resolve,
      reject,
      timeout,
      lastActivity: Date.now()
    });

    ws.send(JSON.stringify(request));
  });
}

Transport Layer

The MCP server uses stdio transport to communicate with AI agents:

server.ts

// All logs go to stderr to avoid interfering with MCP protocol
const logger = {
  info: (message: string) => process.stderr.write(`[INFO] ${message}\n`),
  debug: (message: string) => process.stderr.write(`[DEBUG] ${message}\n`),
  error: (message: string) => process.stderr.write(`[ERROR] ${message}\n`),
};

// Start server with stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

stdout is reserved for MCP protocol messages. All logging must go to stderr to prevent protocol corruption.

WebSocket Relay

The WebSocket relay (src/socket.ts) is a lightweight Bun-powered router that enables channel-based message isolation between multiple MCP servers and Figma plugins.

Why a Relay?

The relay solves a critical architectural challenge:

MCP servers communicate via stdio and need WebSocket connectivity
Multiple users may run servers simultaneously on the same machine
Channel isolation prevents messages from crossing between different sessions

Channel-Based Routing

Clients must join a channel before sending messages:

socket.ts

if (data.type === "join") {
  const channelName = data.channel;
  
  // Create channel if it doesn't exist
  if (!channels.has(channelName)) {
    channels.set(channelName, new Set());
  }
  
  // Add client to channel
  const channelClients = channels.get(channelName)!;
  channelClients.add(ws);
  
  console.log(`Client joined channel "${channelName}" (${channelClients.size} total clients)`);
}

Messages are broadcast only within the same channel:

socket.ts

if (data.type === "message") {
  const channelClients = channels.get(channelName);
  
  // Broadcast to all OTHER clients (not the sender)
  channelClients.forEach((client) => {
    if (client !== ws && client.readyState === WebSocket.OPEN) {
      client.send(JSON.stringify({
        type: "broadcast",
        message: data.message,
        sender: "peer",
        channel: channelName
      }));
    }
  });
}

Server Configuration

The relay runs on port 3055 by default (configurable via PORT env):

socket.ts

const server = Bun.serve({
  port: 3055,
  websocket: {
    open: handleConnection,
    message: handleMessage,
    close: handleClose
  }
});

console.log(`WebSocket server running on port ${server.port}`);

Start the relay with bun socket before connecting MCP servers or Figma plugins.

Figma Plugin

The Figma plugin (src/cursor_mcp_plugin/) runs inside Figma and executes design modifications in response to commands from the MCP server.

Plugin Components

code.js - Main Thread

The plugin main thread handles 30+ commands via a dispatcher pattern. It processes requests like create_frame, set_text_content, export_node_as_image, etc.No build step required — code.js is written directly as the runtime artifact.

ui.html - Plugin UI

The plugin UI provides WebSocket connection management, allowing users to:

Connect to the relay server
Join channels
Monitor connection status

manifest.json - Permissions

Declares required permissions:

dynamic-page access for document manipulation
localhost network access for WebSocket connections

Command Execution

The plugin receives commands via WebSocket and executes them using Figma’s Plugin API:

code.js

// Example: Creating a frame
function createFrame(params) {
  const frame = figma.createFrame();
  frame.x = params.x;
  frame.y = params.y;
  frame.resize(params.width, params.height);
  frame.name = params.name || "Frame";
  
  if (params.fillColor) {
    frame.fills = [{
      type: 'SOLID',
      color: {
        r: params.fillColor.r,
        g: params.fillColor.g,
        b: params.fillColor.b
      },
      opacity: params.fillColor.a || 1
    }];
  }
  
  return {
    id: frame.id,
    name: frame.name
  };
}

Message Flow Example

Here’s how a complete request flows through the pipeline:

AI Agent calls tool

// User asks: "Create a blue frame"
create_frame({
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  fillColor: { r: 0, g: 0.5, b: 1, a: 1 }
})

MCP Server receives via stdio

Server validates parameters with Zod schema, generates UUID abc-123

MCP Server sends to relay

{
  "id": "abc-123",
  "type": "message",
  "channel": "my-channel",
  "message": {
    "id": "abc-123",
    "command": "create_frame",
    "params": {
      "x": 100,
      "y": 100,
      "width": 200,
      "height": 200,
      "fillColor": { "r": 0, "g": 0.5, "b": 1, "a": 1 }
    }
  }
}

Relay broadcasts to channel

Relay forwards message to all clients in my-channel except the sender

Figma Plugin receives and executes

Plugin creates the frame using Figma API and sends response

Response flows back

{
  "id": "abc-123",
  "result": {
    "id": "frame-456",
    "name": "Frame"
  }
}

MCP Server resolves promise

Server finds pending request by ID, clears timeout, resolves promise

AI Agent receives result

Created frame "Frame" with ID: frame-456

Key Design Patterns

Request Tracking

All requests are tracked in a Map with timeout and promise callbacks:

server.ts

const pendingRequests = new Map<string, {
  resolve: (value: unknown) => void;
  reject: (reason: unknown) => void;
  timeout: ReturnType<typeof setTimeout>;
  lastActivity: number;
}>();

Progress Updates

For long-running operations (like scanning 100+ nodes), the plugin sends progress updates that reset the inactivity timer:

server.ts

if (json.type === 'progress_update') {
  const request = pendingRequests.get(requestId)!;
  
  // Update last activity timestamp
  request.lastActivity = Date.now();
  
  // Reset the timeout
  clearTimeout(request.timeout);
  request.timeout = setTimeout(() => {
    // 60 second timeout for inactivity
    request.reject(new Error('Request timed out'));
  }, 60000);
}

Auto-Reconnection

The MCP server automatically reconnects to the relay if the connection drops:

server.ts

ws.on('close', () => {
  logger.info('Disconnected from relay');
  
  // Reject all pending requests
  for (const [id, request] of pendingRequests.entries()) {
    clearTimeout(request.timeout);
    request.reject(new Error("Connection closed"));
    pendingRequests.delete(id);
  }
  
  // Reconnect after 2 seconds
  setTimeout(() => connectToFigma(port), 2000);
});

Get Started

Core Concepts

Guides

Best Practices

Overview

Architecture Diagram

MCP Server

WebSocket Relay

Figma Plugin

MCP Server

Key Responsibilities

Communication Flow

Code Example: Request Lifecycle

Transport Layer

WebSocket Relay

Why a Relay?

Channel-Based Routing

Server Configuration

Figma Plugin

Plugin Components

Command Execution

Message Flow Example

Key Design Patterns

Request Tracking

Progress Updates

Auto-Reconnection

Next Steps

Channel Communication

WebSocket Relay

​Overview

​Architecture Diagram

MCP Server

WebSocket Relay

Figma Plugin

​MCP Server

​Key Responsibilities

​Communication Flow

​Code Example: Request Lifecycle

​Transport Layer

​WebSocket Relay

​Why a Relay?

​Channel-Based Routing

​Server Configuration

​Figma Plugin

​Plugin Components

​Command Execution

​Message Flow Example

​Key Design Patterns

​Request Tracking

​Progress Updates

​Auto-Reconnection

​Next Steps

Channel Communication

WebSocket Relay

Overview

Architecture Diagram

MCP Server

Key Responsibilities

Communication Flow

Code Example: Request Lifecycle

Transport Layer

WebSocket Relay

Why a Relay?

Channel-Based Routing

Server Configuration

Figma Plugin

Plugin Components

Command Execution

Message Flow Example

Key Design Patterns

Request Tracking

Progress Updates

Auto-Reconnection

Next Steps