Figma MCP Server

An MCP (Model Context Protocol) server that gives AI assistants like Claude full control over Figma — create frames, components, variables, export assets, and build complete UI designs through natural language.

How It Works

Claude / Cursor
      ↕ stdio (JSON-RPC)
  MCP Server (Node.js)
      ↕ WebSocket
  WS Bridge (127.0.0.1:9001)
      ↕ Plugin API
  Figma Plugin (Figma Desktop)

1. You ask Claude to create or modify a design

2. Claude calls an MCP tool — the MCP server validates the arguments

3. The server sends a command over a local WebSocket to the bridge

4. The bridge forwards it to the Figma plugin running in Figma Desktop

5. The plugin executes figma.* API calls and returns the result

6. Claude receives the result and continues building

Prerequisites

• Node.js v18 or later

• Figma Desktop — the web version does not support plugins with network access

• Claude Desktop or Cursor (or any MCP-compatible client)

Installation

1. Clone and install dependencies

git clone https://github.com/your-username/figma-mcp.git
cd figma-mcp
npm install

2. Build the project

npm run build

This compiles src/mcp-server/ and src/websocket-server/ to dist/. The Figma plugin (src/figma-plugin/) is plain JavaScript and needs no compilation.

3. Start the WebSocket bridge

npm run socket

For development with auto-reload:

npm run dev:socket

You should see:

{"level":"info","component":"bridge","msg":"Listening on 127.0.0.1:9001"}

4. Load the plugin in Figma Desktop

1. Open Figma Desktop

2. Go to Plugins → Development → Import plugin from manifest...

3. Select src/figma-plugin/manifest.json

4. Run it from Plugins → Development → Figma MCP Bridge

The plugin UI shows "Connected" when the bridge connection is established.

5. Connect your AI client

Claude Desktop

Add to claude_desktop_config.json (find it at ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp/dist/mcp-server/index.js"]
    }
  }
}

Cursor

Add to your MCP config (.cursor/mcp.json or via Cursor Settings → MCP):

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp/dist/mcp-server/index.js"]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/figma-mcp with the actual path to this repo.

Restart your AI client after saving the config. The Figma tools will appear automatically.

Available Tools

67 tools organized into categories:

Reading & Inspection

Creating Shapes & Elements

Modifying Nodes

Organizing Nodes

Components & Instances

Style System

Variables & Design Tokens

Images

Export

Pages & Sections

Workflow & Utility

Example Prompts

Landing Page Hero Section

"Create a 1440×900 hero section frame. Add a dark navy background, a large white heading 'Build faster with AI', a subtitle below it in lighter gray, and a blue rounded CTA button. Center everything with auto layout."

Card Component

"Create a card component — 320×400 frame, 12px corner radius, subtle drop shadow, 16px padding. Include a gray image placeholder at the top, a bold title, a description, and a 'Learn more' link at the bottom."

Design System Setup

"Set up a basic design system in this document. Create color styles for Primary (#4F46E5), Background (#F9FAFB), and Text (#111827). Create text styles for Heading H1 (32px bold Inter), Body (16px regular Inter), and Caption (12px regular Inter)."

Component with Variants

"Create a button component with three variants: Primary (blue fill, white text), Secondary (white fill, blue border), and Destructive (red fill, white text). Combine them into a variant set."

Dark/Light Theme with Variables

"Create a variable collection called 'Theme' with Light and Dark modes. Add a 'Background' color variable: white (#FFFFFF) in Light, dark gray (#1A1A2E) in Dark. Add a 'Text/Primary' color variable: dark (#111827) in Light, white (#F9FAFB) in Dark."

Image-Based Layout

"Create a 1200×600 feature section. Fetch the image from https://images.unsplash.com/photo-example and apply it to the left half. On the right half, add a heading and description with auto layout."

Configuration

Environment Variables

Copy .env.example to .env to customize the defaults:

Export Directory

Exported nodes are auto-saved to ./exports/ by default. Override with the FIGMA_EXPORT_DIR environment variable:

FIGMA_EXPORT_DIR=/my/designs/exports npm run socket

Development

# Build TypeScript
npm run build

# Watch mode (auto-reload bridge)
npm run dev:socket

# Run all tests
npm test

# Watch tests
npm run test:watch

# Coverage report (80% threshold)
npm run test:coverage

Project Structure

figma-mcp/
├── src/
│   ├── shared/                    # Wire protocol & constants (shared between server and bridge)
│   │   ├── constants.ts           # COMMAND_NAMES (single source of truth), defaults
│   │   ├── protocol.ts            # Message types, error codes
│   │   ├── index.ts               # Barrel re-export
│   │   └── logger/                # Structured logging (pino-based)
│   │       ├── logger.ts          # createLogger() factory
│   │       ├── metrics.ts         # MetricsCollector (counters, histograms)
│   │       └── redact.ts          # Sensitive field redaction
│   │
│   ├── mcp-server/                # MCP server (Claude ↔ bridge)
│   │   ├── index.ts               # Server setup, tool registration, server-side tools
│   │   ├── ws-client.ts           # WebSocket client with reconnect logic
│   │   ├── request-tracker.ts     # Promise-based request/response matching
│   │   └── tools/                 # Tool schemas split by category
│   │       ├── index.ts           # Merges all partial registries → TOOL_REGISTRY
│   │       ├── shared-schemas.ts  # Reusable Zod schemas (RGBAColor, Fill, Typography…)
│   │       ├── read-tools.ts
│   │       ├── create-tools.ts
│   │       ├── modify-tools.ts
│   │       ├── organize-tools.ts
│   │       ├── viewport-tools.ts
│   │       ├── style-tools.ts
│   │       ├── layout-tools.ts
│   │       ├── component-tools.ts
│   │       ├── style-system-tools.ts
│   │       ├── image-tools.ts
│   │       ├── export-tools.ts
│   │       ├── typography-tools.ts
│   │       ├── constraint-tools.ts
│   │       ├── batch-tools.ts
│   │       ├── vector-tools.ts
│   │       ├── page-tools.ts
│   │       ├── traversal-tools.ts
│   │       ├── variable-tools.ts
│   │       ├── workflow-tools.ts
│   │       ├── design-system-tools.ts
│   │       ├── manipulation-tools.ts
│   │       └── extra-shape-tools.ts
│   │
│   ├── websocket-server/          # WebSocket bridge (routes commands between MCP and plugin)
│   │   ├── index.ts               # FigmaBridge class and entry point
│   │   ├── config.ts              # BridgeConfig + loadConfig()
│   │   └── validation.ts          # Message validation, ProtocolError
│   │
│   └── figma-plugin/              # Figma plugin (plain JS, no build step)
│       ├── manifest.json          # Plugin manifest
│       ├── code.js                # Plugin sandbox — handles all figma.* API calls
│       └── ui.html                # Hidden iframe — holds the WebSocket connection
│
├── tests/
│   ├── mcp-server/
│   │   ├── tools.test.ts          # Zod schema validation for all tools
│   │   └── request-tracker.test.ts
│   ├── websocket-server/
│   │   └── bridge.test.ts         # Bridge routing and client management
│   ├── integration/
│   │   └── roundtrip.test.ts      # Full MCP → bridge → mock plugin round-trips
│   └── shared/
│       ├── logger.test.ts
│       └── metrics.test.ts
│
├── exports/                       # Auto-created when export_node is used
├── logs/                          # Optional log output directory
├── .env.example                   # Environment variable reference
├── package.json
├── tsconfig.json
└── vitest.config.ts

Troubleshooting

Plugin shows "Disconnected" or never connects

1. Make sure npm run socket is running and shows "Listening on 127.0.0.1:9001"

2. Confirm the plugin is active in Plugins → Development → Figma MCP Bridge

3. If port 9001 is in use by another process, change the port:

   WS_PORT=9002 npm run socket

   Then update WS_URL in .env to match.

Commands time out

1. Confirm the plugin shows "Connected" — commands cannot reach Figma without an active connection

2. Font operations (text nodes) load fonts asynchronously — the default 30s timeout handles most cases

3. For slow operations, increase the timeout: WS_TIMEOUT_MS=60000

4. Check that Figma Desktop is responsive and not showing any error dialogs

Bridge port already in use (EADDRINUSE)

A previous bridge process is still running. On macOS/Linux:

lsof -i :9001
kill <PID>

On Windows (PowerShell):

Get-Process -Id (Get-NetTCPConnection -LocalPort 9001).OwningProcess | Stop-Process

MCP tools do not appear in Claude / Cursor

1. Make sure npm run build completed without TypeScript errors

2. Verify the absolute path in your MCP config points to dist/mcp-server/index.js

3. Restart your AI client after every config change

4. Check your client's MCP logs for connection errors

Images not loading (set_image_from_url)

• The URL must be publicly accessible (no auth, no paywalls)

• Supported formats: PNG, JPEG, GIF, WebP, SVG

• Maximum file size: 5 MB (oversized images are auto-optimized before being sent)

Architecture Notes

• Security: The bridge binds to 127.0.0.1 only — it is never exposed to the network. The plugin's networkAccess.allowedDomains is set to none in production.

• Message size: Maximum WebSocket message is 8 MB to support high-resolution image fills.

• Reconnection: The plugin auto-reconnects with exponential backoff (1s base, 2× multiplier, 30s max) if the bridge restarts.

• Server-side tools: set_image_from_url and set_image_from_path run entirely in Node.js (fetch + encode) and forward to set_image_fill — they never require extra plugin code.

• Logging: All Node.js logs go to stderr to avoid corrupting MCP's JSON-RPC on stdout. Set LOG_PRETTY=true for readable development output.

Contributing

1. Add the command name to COMMAND_NAMES in src/shared/constants.ts

2. Create the tool schema in the appropriate file under src/mcp-server/tools/

3. Add the handler in src/figma-plugin/code.js

4. Add the command to ALLOWED_COMMANDS in both code.js and ui.html

5. Add tests in tests/mcp-server/tools.test.ts

See CLAUDE.md for the full contributor guide.