Documentation

Everything you need to get started with Figma Unified MCP and the Unified Design CLI. From setup to tool reference to real-world recipes.

What is Figma Unified MCP

Figma Unified MCP is an open-source MCP (Model Context Protocol) server that connects AI agents directly to your Figma files. It exposes 100+ tools that let you read designs, create nodes, modify styles, manage variables, build prototypes, and generate production code, all through natural language.

Instead of manually clicking through Figma menus or learning the Figma API, you simply describe what you want. The MCP server translates your words into Figma actions.

How it connects

Your MCP client (Claude Desktop, VS Code, Cursor) connects to the MCP server via stdio. The server then communicates with Figma through two channels:

• Figma REST API for reading files, styles, components, variables, comments, and team libraries. No plugin needed.
• WebSocket + companion plugin for writing to the canvas: creating frames, shapes, text, prototyping, code generation, and more.

What can it do?

• Read & inspect files, styles, components, variables, comments, team libraries, version history
• Create & build frames, shapes, text, components, instances, pages
• Modify & style fills, strokes, effects, auto-layout, constraints, typography
• Manage design tokens with variable collections, multi-mode values (light/dark), binding
• Build prototypes with interactions, flows, transitions, overlays, scroll behaviors
• Generate code as React, SwiftUI, HTML, CSS, Tailwind config, and developer handoff specs

What is Unified Design CLI

The Unified Design CLI (unified-design) is a standalone command-line tool that lets you interact with Figma directly from your terminal. It ships alongside the MCP server but works independently. No AI agent needed. Just you and your Figma files.

Setup

cd figma-unified-mcp
npm install
npm run build
npm link           # makes 'unified-design' available globally

export PATH="$(npm prefix -g)/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc

Authentication

# Option 1: Environment variable
export FIGMA_ACCESS_TOKEN=figd_xxx

# Option 2: Config file (~/.figmarc)
unified-design config set accessToken figd_xxx

# Option 3: Auto-discovery
# Reads from Claude Desktop / Cursor MCP config — no extra setup needed

Plugin Bridge — Coexisting with MCP Server

Canvas write commands (e.g. create-frame, set-fill) require the Figma plugin. The CLI automatically detects how to connect:

• MCP server running? → CLI connects as a client to the existing bridge (no port conflict)
• No server running? → CLI starts its own bridge and waits for the plugin

This means you can use the CLI alongside Claude Desktop / Cursor without stopping the MCP server.

Interactive REPL

Run unified-design with no arguments and you drop into an interactive shell. It shows your auth status, plugin connection, and default file at a glance. Tab completion and short aliases make it fast to navigate.

40+ commands across 10 categories

• Files — get-file, get-node, get-nodes, search, get-file-versions
• Styles & Variables — get-styles, get-components, get-variables, get-library-items-used
• Create — create-frame, create-rectangle, create-ellipse, create-text, create-component
• Modify — move-node, resize-node, set-fill, set-text, rename-node, delete-node, clone-node, set-opacity, set-visible, group-nodes, reparent-node
• Codegen — generate-css, generate-react, generate-html, generate-tokens
• Prototype — create-interaction, get-flows
• Variables (REST) — create-variable-collection, create-variable, set-variable-value, update-variable, delete-variable
• Export — get-images, screenshot, export-svg
• Audit — full design quality report (colors, fonts, spacing, naming, hidden layers, empty groups)
• Teams — get-team-components, get-team-styles, get-team-projects, get-project-files

Config management

Use unified-design config set accessToken figd_xxx to store your token in ~/.figmarc. Set a default file key so you never have to type --file-key again. The CLI also auto-discovers tokens from Claude Desktop, VS Code, and Cursor configs.

Why I Built This

I'm a designer. I've never taken a computer science class. My entire career has been spent inside Figma, not inside a code editor.

Then AI happened. And something clicked.

I started using AI as a coding partner, and within weeks I had built five Figma plugins from scratch, including one that adds audio to Figma files. I built an Instagram DM agent and deployed it on a real server. None of this should have been possible for someone with my background. But it was.

So I kept going. I built a full MCP server that connects AI directly to Figma. It reads files, creates nodes, updates variables and styles, draws elements from prompts, generates code. 100+ tools. It runs on Mac and Windows. It works with Claude Desktop, Claude Code, and Cursor. I built all of it with AI as my partner.

People keep asking me: why build your own when other Figma MCPs exist?

Because I don't just want to use AI. I want to understand it. I want tools shaped around how designers actually think, not adapted from someone else's engineering workflow. Tools I can break apart, rebuild, and make my own.

That's what this project is. A designer's tool, built by a designer, for the way designers work.

Requirements

• Node.js 18+ to run the MCP server
• Figma Personal Access Token with read/write scopes
• MCP client such as Claude Desktop, VS Code + Copilot, Cursor, or any MCP-compatible client
• Figma companion plugin (optional) for canvas write operations

Installation

export PATH="$(npm prefix -g)/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc

Configuration

MCP client config

Add the following to your MCP client's config file:

Environment variables

Tool Profiles

Profiles control how many tools are exposed to the AI. Fewer tools = fewer tokens per message = lower cost and less confusion for the model. Every profile includes figma_run as an escape hatch to call any tool on demand.

Read & Inspect

Tools for reading files, querying styles, browsing components, and inspecting designs. All use the REST API — no plugin required.

Create & Build

Tools for creating new nodes on the canvas. All require the companion plugin.

Modify & Style

Tools for changing properties on existing nodes. All require the companion plugin.

Code Generation

Export designs as production-ready code. Available in the full profile (or via figma_run escape hatch).

Design Tokens

Variable and style CRUD via the REST API. No plugin required for most operations.

Prototyping

Build interactive prototypes. All require the companion plugin.

Utility Tools

Available in all profiles.

Recipes

Common multi-step workflows you can accomplish in a single conversation.

Figma Plugin

The companion plugin runs inside Figma and bridges WebSocket commands from the MCP server to the Figma Plugin API. For install and setup steps, see the Installation → Figma Plugin tab.

How it works

When you start the MCP server, it opens a WebSocket on port 18211 (configurable via FIGMA_WS_PORT). The plugin connects to this WebSocket when you run it in Figma. Commands from the MCP server are relayed through this bridge to the Figma Plugin API.

What requires the plugin

• Not needed: Reading files, styles, components, variables (REST API), posting comments, exporting images via REST
• Needed: Creating/modifying nodes, prototyping, screenshots, code generation, auto-layout, style application

Multiple files

The plugin connects per-file. If you switch to a different Figma file, you need to run the plugin again in that file. The server handles reconnection automatically.

Troubleshooting

"Plugin not connected" errors

• Make sure the plugin is running in your active Figma file
• Check that the MCP server is running and the WebSocket port isn't blocked
• Try figma_connect_plugin to manually reconnect
• Ensure no firewall is blocking localhost:18211

"Invalid access token"

• Verify your token at Figma → Settings → Personal access tokens
• Ensure the token has File content (Read) and File content (Write) scopes
• Check that you're using the full token string (starts with figd_)

"Tool not found" in minimal/standard profile

• Some tools are only in the full profile (e.g., code generation, boolean operations)
• Use figma_run to access any tool regardless of profile: "Use figma_run to call generate_react"
• Or switch to the full profile via TOOL_PROFILE=full

Server won't start

• Ensure Node.js 18+ is installed: node --version
• Run npm run build after pulling updates
• Check that the path in your MCP config is an absolute path
• Look at the MCP client logs for specific error messages

Batch operations timing out

• Large batches (20+ operations) may take time — the plugin executes them sequentially
• Split very large batches into smaller groups of 10–15 operations
• Complex code generation tools may take 10–30 seconds per call

Getting help

Open an issue on GitHub with:

• Your MCP client (Claude Desktop, VS Code, Cursor)
• Node.js version
• The full error message
• Whether the plugin was running when the error occurred