# Technical Architecture
Source: https://docs.figma-console-mcp.southleft.com/architecture
Deep dive into Figma Console MCP's architecture, deployment modes, component details, and data flows.
# Figma Console MCP - Technical Architecture
## Overview
Figma Console MCP provides AI assistants with real-time access to Figma for debugging, design system extraction, and design creation. The server supports two deployment modes with different capabilities.
## Deployment Modes
### Remote Mode (SSE/OAuth)
**Best for:** Design system extraction, API-based operations, zero-setup experience
Remote Mode has two sub-modes depending on whether the Desktop Bridge plugin is paired:
#### Read-Only (REST API via OAuth/PAT)
```mermaid theme={null}
flowchart TB
AI[AI Assistant]
AI -->|SSE| WORKER
WORKER[Cloudflare Worker]
WORKER --> MCP[MCP Protocol]
MCP --> CLIENT[REST Client]
CLIENT -->|HTTPS| API[Figma API]
```
**Capabilities:**
* Design system extraction (variables, styles, components)
* File structure queries
* Component images
#### Read + Write (REST API + Cloud Write Relay)
When a user pairs the Desktop Bridge plugin via Cloud Mode, Remote Mode gains full write access through the cloud relay:
```mermaid theme={null}
flowchart TB
AI[AI Assistant]
AI -->|SSE| WORKER[Cloudflare Worker]
WORKER --> REST[REST Client]
WORKER --> RELAY[Plugin Relay DO]
REST -->|HTTPS| API[Figma API]
RELAY -->|WebSocket| PLUGIN[Desktop Bridge Plugin]
PLUGIN --> FILE[Design File]
```
**Additional Capabilities (with Cloud Relay):**
* Design creation via Plugin API
* Variable CRUD operations
* Component arrangement and organization
* Console log capture
***
### Local Mode (Desktop Bridge)
**Best for:** Plugin debugging, design creation, variable management, full capabilities
```mermaid theme={null}
flowchart TB
AI[AI Assistant]
AI -->|stdio| SERVER[Local MCP Server]
SERVER --> REST[REST Client]
SERVER --> WS[WebSocket Server]
REST -->|HTTPS| API[Figma API]
WS -->|"WebSocket :9223–9232"| PLUGIN[Desktop Bridge Plugin]
PLUGIN --> FILE[Design File]
```
**Transport:**
* **WebSocket + HTTP** — via Desktop Bridge Plugin on ports 9223–9232. No debug flags needed. Supports real-time selection tracking, document change monitoring, and console capture.
* The server tries port 9223 first, then automatically falls back through ports 9224–9232 if another instance is already running. Orphaned processes are automatically detected and terminated on startup.
* The HTTP server on the same port exposes `/health` for liveness checks.
* All 121 tools work through the WebSocket transport.
**Plugin distribution:**
* The Desktop Bridge plugin ships as `manifest.json`, `code.js`, and `ui.html` — the full UI (\~60 KB) is loaded directly by Figma at plugin-open time (no bootloader fetch).
* Plugin files are copied to `~/.figma-console-mcp/plugin/` on server startup so users have a stable import path; the MCP server keeps the copy in sync with the running build.
* Updating the plugin code requires re-importing `manifest.json` in Figma (Plugins → Manage plugins → re-import) because Figma caches plugin files at the application level. Closing and reopening the plugin window is enough for most edits; a full Figma restart is rarely needed.
**Capabilities:**
* Everything in Remote Mode, plus:
* Console log capture (real-time)
* Design creation via Plugin API
* Variable CRUD operations
* Component arrangement and organization
* Real-time selection and document change tracking (WebSocket)
* Zero-latency local execution
***
## Component Details
### MCP Server Core (`src/local.ts`)
The main server implements the Model Context Protocol with stdio transport for local mode.
**Key Responsibilities:**
* Tool registration (121 tools in Local Mode, 95 in Cloud Mode)
* Request routing and validation
* Figma API client management
* Desktop Bridge communication via WebSocket
**Tool Categories:**
| Category | Tools | Transport |
| - | - | - |
| Status & Diagnostics | `figma_get_status`, `figma_diagnose`, `figma_reconnect` | WebSocket |
| Console | `figma_get_console_logs`, `figma_watch_console`, `figma_clear_console` | WebSocket |
| Screenshots | `figma_take_screenshot`, `figma_capture_screenshot` | WebSocket |
| Design System | `figma_get_variables`, `figma_get_styles`, `figma_get_component` | REST API |
| Design Creation | `figma_execute`, `figma_create_component_set`, `figma_arrange_component_set` | WebSocket (Plugin) |
| Variables | `figma_create_variable`, `figma_update_variable`, etc. | WebSocket (Plugin) |
| Token Sync | `figma_export_tokens`, `figma_import_tokens` | Plugin read + Plugin write |
| Real-Time | `figma_get_selection`, `figma_get_design_changes` | WebSocket |
| Multi-File | `figma_list_open_files`, `figma_execute_across_files` | WebSocket (one plugin connection per file) |
| Parity & Docs | `figma_check_design_parity`, `figma_generate_component_doc` | REST API + WebSocket (Plugin) |
| Audits | `figma_lint_design`, `figma_audit_component_accessibility`, `figma_audit_design_system_report` | WebSocket (Plugin) + REST API |
| Codebase Extraction | `figma_ds_analyze` … `figma_ds_verify` (seven tools) | Local filesystem |
***
### Desktop Bridge Plugin
The Desktop Bridge is a Figma plugin that runs inside Figma Desktop and provides access to the full Figma Plugin API.
**Architecture:**
```mermaid theme={null}
flowchart TB
MSG[Message Handler]
MSG --> EXEC[Execute]
MSG --> VARS[Variables]
MSG --> COMP[Components]
EXEC --> API[Figma Plugin API]
VARS --> API
COMP --> API
```
**Communication Protocol:**
The MCP server communicates with the Desktop Bridge via WebSocket:
1. **MCP Server** sends JSON command via WebSocket (ports 9223–9232)
2. **Plugin UI** receives and forwards via `postMessage` to plugin code
3. **Plugin Code** executes Figma Plugin API calls
4. **Plugin Code** returns result via `figma.ui.postMessage`
5. **Plugin UI** sends response back via WebSocket
6. **MCP Server** receives correlated response
***
### Transport Layer
The MCP server uses a transport abstraction (`IFigmaConnector` interface) with two connector implementations:
| Connector | Class | Mode | Transport |
| - | - | - | - |
| Local WebSocket | `WebSocketConnector` | Local | `ws://localhost:9223–9232` |
| Cloud Relay | `CloudWebSocketConnector` | Remote | Fetch RPC to Durable Object |
(The local `FigmaDesktopConnector` / Puppeteer-CDP path that lived alongside `WebSocketConnector` for a transitional period was removed in Phase 3 of the cleanup branch — Local Mode now routes every tool through the WebSocket plugin bridge. Cloud Mode still uses Cloudflare's Browser Rendering API for `figma_navigate`, `figma_get_console_logs`, and `figma_take_screenshot`; write/plugin tools route through the Cloud Plugin Relay Durable Object instead.)
#### WebSocket Transport (Local)
The Desktop Bridge Plugin connects via WebSocket on ports 9223–9232. No special Figma launch flags needed.
**Features:**
* Real-time selection tracking (`figma_get_selection`)
* Document change monitoring (`figma_get_design_changes`)
* File identity tracking (file key, name, current page)
* Plugin-context console capture
* Instant availability check (no network timeout)
**Communication flow:**
```
MCP Server ←WebSocket (ports 9223–9232)→ Plugin UI (ui.html) ←postMessage→ Plugin Code (code.js) ←figma.*→ Figma
```
#### Cloud Relay Transport (Remote)
The `CloudWebSocketConnector` implements the same `IFigmaConnector` interface but routes commands via fetch RPC to the `PluginRelayDO` Durable Object. The DO maintains a persistent WebSocket connection to the Desktop Bridge plugin.
**Communication flow:**
```
Cloud MCP Server →fetch RPC→ PluginRelayDO ←WebSocket (wss://)→ Plugin UI (ui.html) ←postMessage→ Plugin Code (code.js) ←figma.*→ Figma
```
See [Cloud Write Relay](#cloud-write-relay) for full details.
#### Multi-Instance Support (v1.10.0+)
Multiple MCP server processes can run simultaneously (e.g., Claude Desktop Chat tab, Code tab, Cursor, etc.). Each server binds to the first available port in the range 9223–9232. The Desktop Bridge Plugin scans all ports in the range and connects to every active server.
#### Transport Detection
The MCP server checks if a WebSocket client is connected (instant, under 1ms). If connected, commands route through WebSocket. If no client is connected, setup instructions are returned.
All 121 tools work through the WebSocket transport.
***
### Figma REST API Client
Used for design system extraction and file queries.
**Endpoints Used:**
| Endpoint | Purpose |
| - | - |
| `GET /v1/files/:key` | File structure and metadata |
| `GET /v1/files/:key/nodes` | Specific node data |
| `GET /v1/files/:key/styles` | Style definitions |
| `GET /v1/files/:key/variables/local` | Variable collections (Enterprise) |
| `GET /v1/images/:key` | Rendered images |
**Authentication:**
* **Remote Mode:** OAuth 2.0 with automatic token refresh
* **Local Mode:** Personal Access Token via environment variable
***
## Data Flow Examples
### Design Creation Flow
```mermaid theme={null}
sequenceDiagram
participant U as User
participant A as AI
participant M as MCP
participant B as Bridge
participant F as Figma
U->>A: Create button
A->>M: figma_execute()
M->>B: Send code
B->>F: createComponent()
F-->>B: Node created
B-->>M: {nodeId}
A->>M: capture_screenshot()
M-->>A: Image
A-->>U: Done
```
### Variable Management Flow
```mermaid theme={null}
sequenceDiagram
participant U as User
participant A as AI
participant M as MCP
participant B as Bridge
participant F as Figma
U->>A: Create variable
A->>M: create_variable()
M->>B: Send command
B->>F: createVariable()
F-->>B: Created
B-->>M: Variable ID
M-->>A: Success
A-->>U: Done
```
### Console Debugging Flow
```mermaid theme={null}
sequenceDiagram
participant U as User
participant P as Plugin
participant B as Bridge
participant M as MCP
participant A as AI
U->>P: Run plugin
P->>B: console.log()
B->>M: Log via WebSocket
M->>M: Buffer entry
U->>A: Show logs
A->>M: get_console_logs()
M-->>A: Logs
A-->>U: Display
```
***
## Cloud Write Relay
The Cloud Write Relay enables web-based AI clients (Claude.ai, v0, Replit, Lovable) to send write commands to Figma through a Cloudflare Durable Object relay. This gives Remote Mode full write capabilities — design creation, variable management, and component arrangement — without requiring a local Node.js process.
### Architecture
```
AI Client (Claude.ai)
│
▼
Cloud MCP Server (/mcp endpoint on Cloudflare Worker)
│
├──► REST Client ──► Figma REST API (read operations)
│
└──► fetch RPC
│
▼
PluginRelayDO (Durable Object)
│
▼ WebSocket (wss://)
Desktop Bridge Plugin (ui.html)
│
▼ postMessage
Plugin Worker (code.js)
│
▼ figma.*
Figma Plugin API
```
### Key Components
| Component | File | Purpose |
| - | - | - |
| `PluginRelayDO` | `src/core/cloud-websocket-relay.ts` | Durable Object that brokers WebSocket between cloud server and plugin |
| `CloudWebSocketConnector` | `src/core/cloud-websocket-connector.ts` | `IFigmaConnector` implementation that routes commands via fetch RPC to the relay DO |
| `registerWriteTools()` | `src/core/write-tools.ts` | Shared tool registration function used by both local and cloud entry points |
### Pairing Flow
```
AI Client Cloud Server Relay DO Desktop Bridge Plugin
│ │ │ │
│ figma_pair_plugin │ │ │
│ ──────────────────────────► │ │ │
│ │ Create relay DO │ │
│ │ ─────────────────────► │ │
│ │ Store code in KV │ │
│ ◄─── 6-char code ──────── │ (5-min TTL) │ │
│ (shown to user) │ │ │
│ │ │ │
│ │ │ WebSocket connect │
│ │ │ wss://.../ws/pair?code= │
│ │ │ ◄──────────────────────────│
│ │ │ Code validated, paired │
│ │ │ ──────────────────────────►│
│ │ │ │
│ figma_execute(...) │ │ │
│ ──────────────────────────► │ fetch RPC │ │
│ │ ─────────────────────► │ forward via WebSocket │
│ │ │ ──────────────────────────►│
│ │ │ │ ──► figma.*
│ │ │ ◄─── result ─────────────│
│ │ ◄─── result ──────── │ │
│ ◄─── result ────────────── │ │ │
```
### Hibernation-Safe Design
The `PluginRelayDO` uses Cloudflare Durable Object hibernation-safe patterns to minimize costs during idle periods between AI turns:
* **WebSocket retrieval:** Uses `this.ctx.getWebSockets('plugin')` to retrieve active connections after hibernation wake-up, rather than storing WebSocket references in memory.
* **File info storage:** Connected file information is persisted to DO storage (`this.ctx.storage`), not held in instance variables that would be lost during hibernation.
* **Wake on message:** The DO wakes from hibernation when either the cloud server sends a fetch RPC or the plugin sends a WebSocket message.
### Tool Registration
`registerWriteTools()` is a shared function that registers all Plugin API write tools (design creation, variable CRUD, component arrangement). It is called from both entry points:
* **`src/local.ts`** — Local mode, tools route through the local `WebSocketConnector`
* **`src/index.ts`** — Remote/cloud mode, tools route through `CloudWebSocketConnector` to the relay DO
This ensures tool parity between local and cloud modes. The same set of write tools is available regardless of deployment path.
***
## Security Considerations
### Authentication
* **Personal Access Tokens:** Stored in environment variables, never logged
* **OAuth Tokens:** Encrypted at rest, automatic refresh
* **No credential storage:** Tokens passed per-request
### Sandboxing
* **Plugin Execution:** Runs in Figma's sandboxed plugin environment
* **Code Validation:** Basic validation before execution
* **No filesystem access:** Plugin code cannot access local files
### Cloud Relay Security
* **Pairing codes:** Single-use, 6-character codes with a 5-minute TTL stored in Cloudflare KV. Codes are consumed on first use and cannot be replayed.
* **Session scoping:** Each pairing creates a dedicated Durable Object instance. One plugin connects per relay — no cross-session leakage.
* **Transport encryption:** All cloud relay traffic uses TLS (`wss://` for the plugin WebSocket, HTTPS for fetch RPC).
* **Bearer token binding:** After pairing, the relay DO ID is stored in KV keyed by the bearer token (`relay:{bearerToken}`, 24h TTL). Only the authenticated AI client session can route commands to its paired relay.
* **No persistent data storage:** The relay passes commands through to the plugin and returns results. Design data is not stored in the Durable Object beyond the active session.
### Data Privacy
* **Console Logs:** Stored in memory only, cleared on restart
* **Screenshots:** Temporary files with automatic cleanup
* **No telemetry:** No data sent to external services
***
## Performance Considerations
### Latency Targets
| Operation | Target | Actual |
| - | - | - |
| Console log retrieval | under 100ms | \~50ms |
| Screenshot capture | under 2s | \~1s |
| Design creation | under 5s | 1-3s |
| Variable operations | under 500ms | \~200ms |
### Memory Management
* **Log Buffer:** Circular buffer, configurable size (default: 1000 entries)
* **Screenshots:** Disk-based with 1-hour TTL cleanup
* **Connection Pooling:** WebSocket connections reused
### Optimization Strategies
* Batch operations where possible
* Lazy loading of component data
* Efficient JSON serialization
* Connection keepalive for WebSocket
***
## Development
### Local Development
```bash theme={null}
# Install dependencies
npm install
# Run in development mode
npm run dev:local
# Build for production
npm run build:local
```
### Testing
```bash theme={null}
# Run all tests
npm test
# Run with coverage
npm run test:coverage
```
### Project Structure
```
figma-console-mcp/
├── src/
│ ├── local.ts # Main MCP server (local mode)
│ ├── index.ts # Cloudflare Workers entry (remote mode)
│ ├── core/
│ │ ├── cloud-websocket-relay.ts # PluginRelayDO Durable Object
│ │ ├── cloud-websocket-connector.ts # CloudWebSocketConnector (IFigmaConnector)
│ │ ├── write-tools.ts # Shared write tool registration
│ │ ├── websocket-connector.ts # Local WebSocketConnector (IFigmaConnector)
│ │ ├── websocket-server.ts # Local WebSocket server
│ │ └── figma-connector.ts # IFigmaConnector interface
│ └── types/ # TypeScript definitions
├── figma-desktop-bridge/
│ ├── code.js # Plugin worker (Figma API access)
│ ├── ui.html # Plugin UI (local + cloud mode)
│ └── manifest.json # Plugin manifest
├── docs/ # Documentation
└── tests/ # Test suites
```
# FigJam Support
Source: https://docs.figma-console-mcp.southleft.com/figjam
AI agents can now create and read FigJam boards — sticky notes, flowcharts, tables, code blocks, and more. A complete guide to the 10 FigJam tools.
# AI Meets Collaborative Whiteboarding
Figma Console MCP now extends beyond Figma Design files into **FigJam** — Figma's collaborative whiteboarding tool used by millions of teams for brainstorming, planning, diagramming, and retrospectives.
This is not a read-only integration. Your AI assistant can **create content on FigJam boards** and **read everything back** — turning FigJam into a programmable canvas for AI-assisted collaboration.
***
## What is FigJam?
FigJam is Figma's whiteboarding product, purpose-built for ideation and team collaboration. Teams use it for brainstorming sessions, user flow diagrams, sprint retrospectives, project planning, and technical architecture discussions. It features sticky notes, shapes, connectors, tables, and more — all in a free-form infinite canvas.
With Figma Console MCP, every one of those elements is now accessible to AI agents.
***
## What's Now Possible
AI assistants connected through Figma Console MCP can now interact with FigJam boards programmatically:
Place individual stickies or batch-create up to 200 at once, with 9 color options for categorization and visual grouping.
Create shapes (rectangles, diamonds, ellipses, engineering symbols) and connect them with labeled connectors to produce complete diagrams.
Create structured tables up to 100 rows by 50 columns, pre-populated with cell data — perfect for comparison matrices and planning grids.
Add code blocks with language-specific syntax highlighting directly to the board for technical reviews and documentation.
Organize elements into grid, horizontal, or vertical layouts with configurable spacing — no manual dragging required.
Retrieve all board elements with full type-specific serialization, including sticky text, shape types, table data, and connector graphs.
***
## The 10 FigJam Tools
Every tool is available in both **Local Mode** and **Cloud Mode**.
| Tool | Description |
| - | - |
| `figjam_create_sticky` | Create a single sticky note with text and optional color and position |
| `figjam_create_stickies` | Batch-create up to 200 sticky notes in a single call |
| `figjam_create_connector` | Connect two nodes with a connector line and optional text label |
| `figjam_create_shape_with_text` | Create a labeled shape for flowcharts and diagrams |
| `figjam_create_table` | Create a table with rows, columns, and pre-populated cell data |
| `figjam_create_code_block` | Add a code snippet with language syntax highlighting |
| `figjam_create_section` | Create a section to group related content on the board |
| `figjam_auto_arrange` | Arrange nodes in grid, horizontal, or vertical layouts |
| `figjam_get_board_contents` | Read all content from a FigJam board with type-specific data |
| `figjam_get_connections` | Read the full connection graph — edges, labels, and connected nodes |
### Supported Shapes
The `figjam_create_shape_with_text` tool supports the following shape types for building diagrams:
| Shape | Use Case |
| - | - |
| `ROUNDED_RECTANGLE` | Process steps, general-purpose nodes (default) |
| `DIAMOND` | Decision points in flowcharts |
| `ELLIPSE` | Start/end terminators |
| `TRIANGLE_UP` / `TRIANGLE_DOWN` | Directional indicators |
| `PARALLELOGRAM_RIGHT` / `PARALLELOGRAM_LEFT` | Input/output operations |
| `ENG_DATABASE` | Database references |
| `ENG_QUEUE` | Message queues and buffers |
| `ENG_FILE` | File operations |
| `ENG_FOLDER` | Directory or collection references |
### Sticky Note Colors
Nine color options for visual categorization: `YELLOW`, `BLUE`, `GREEN`, `PINK`, `ORANGE`, `PURPLE`, `RED`, `LIGHT_GRAY`, `GRAY`.
For full parameter details, default values, and return types, see the [FigJam Tools reference](/tools#figjam-tools).
***
## Use Cases
These are real-world scenarios where FigJam support transforms AI-assisted workflows. Each example includes a prompt you can try with your AI assistant.
### Affinity Mapping from Meeting Notes
Turn unstructured meeting notes into an organized affinity map — instantly.
```
Generate an affinity map from these meeting notes on a FigJam board.
Group related ideas using colored stickies: BLUE for product features,
GREEN for technical requirements, PINK for user feedback, and ORANGE
for open questions. Arrange each group in a grid layout.
```
The AI uses `figjam_create_stickies` to batch-create all notes, assigns colors by category, and calls `figjam_auto_arrange` to lay them out in clean groups.
### User Flow Diagrams
Build complete flowcharts from a verbal description of a user journey.
```
Create a user flow diagram for the checkout process on our FigJam board.
Start with "View Cart", then decision diamond "Has Account?", branching
to "Sign In" and "Guest Checkout", merging at "Enter Shipping", then
"Payment", and ending at "Order Confirmed".
```
The AI creates shapes with `figjam_create_shape_with_text` (rounded rectangles for steps, diamonds for decisions, ellipses for start/end) and wires them together with `figjam_create_connector` using descriptive labels like "Yes" and "No" on the branches.
### Sprint Retrospective Board
Set up a structured retro board in seconds, ready for the team to fill in.
```
Create a sprint retrospective board with three sections:
- GREEN stickies column: "What went well" with 3 placeholder items
- PINK stickies column: "What to improve" with 3 placeholder items
- BLUE stickies column: "Action items" with 3 placeholder items
Arrange each column vertically with clear spacing between groups.
```
### Summarize an Existing Board
Read a brainstorming board and extract actionable insights.
```
Read this FigJam brainstorming board and summarize the themes.
Group the sticky notes by topic, identify the most common ideas,
and list any action items or decisions that were captured.
```
The AI calls `figjam_get_board_contents` to retrieve all elements, then analyzes the text content to produce a structured summary — no manual reading required.
### Comparison Tables
Create structured decision matrices for stakeholder review.
```
Create a comparison table on this FigJam board for our 3 platform
options: AWS, GCP, and Azure. Include rows for: Compute pricing,
Database options, CDN performance, Developer experience, and
Enterprise support. Fill in what you know.
```
The AI uses `figjam_create_table` to generate a pre-populated table that the team can review and annotate collaboratively.
### Code Review on the Board
Share code directly on the whiteboard for collaborative technical discussion.
```
Add this TypeScript function to the FigJam board as a code block
so the team can review it during our architecture session:
async function processOrder(order: Order): Promise {
const validated = await validateOrder(order);
const payment = await chargePayment(validated);
return generateReceipt(payment);
}
```
The AI uses `figjam_create_code_block` with `TYPESCRIPT` syntax highlighting to render the snippet with proper formatting.
### Analyze a Flowchart
Understand the structure and relationships in an existing diagram.
```
What are all the connections in this flowchart? Show me the full
graph of how elements are connected, including any labels on
the connector lines.
```
The AI calls `figjam_get_connections` to return the complete edge list with start/end nodes and labels, then presents the graph structure in a readable format — useful for documenting existing flows or identifying missing connections.
***
## How It Works
### Editor Type Detection
The Desktop Bridge plugin reports `figma.editorType` when it connects to the MCP server. The 10 FigJam tools are always listed. When the plugin is running inside a FigJam board they act on the board. When it is running in a Figma Design file, a runtime guard in the plugin returns an error instead of changing anything.
There is no configuration toggle or mode switch.
### Same Plugin, New Canvas
FigJam support uses the **same Desktop Bridge plugin** you already have installed. There is no separate plugin for FigJam. Open any FigJam board, run the Desktop Bridge plugin, and the FigJam tools become available alongside the standard toolset.
### Runtime Safety
If a FigJam tool is called while connected to a Figma Design file, it returns a clear error message explaining that FigJam tools require a FigJam board. This prevents accidental misuse and gives the AI assistant enough context to guide the user.
### Compatibility
| Mode | FigJam Support |
| - | - |
| Local (NPX/Git) | Full support |
| Cloud Mode | Full support |
| Remote (Read-Only) | Not available (requires Desktop Bridge) |
***
## Getting Started
Open any FigJam board in Figma Desktop. You can create a new board from the Figma home screen or open an existing one.
Launch the Desktop Bridge plugin from **Plugins > Development > Figma Desktop Bridge**. The plugin connects to the MCP server and reports that the editor type is FigJam.
Start with a simple prompt like *"Create a yellow sticky note that says Hello from AI"* to verify the connection, then move on to more complex workflows like flowcharts, tables, and batch operations.
If you have not set up the Desktop Bridge plugin yet, follow the [Setup Guide](/setup) first. The same plugin installation works for both Figma Design files and FigJam boards.
***
## Community Contributors
FigJam support was built by the community and merged into the main project. Recognition goes to the contributors who made this possible:
* **klgral (G Klas)** — Authored the original FigJam write tools: sticky notes, batch stickies, connectors, shapes, tables, code blocks, and auto-arrange.
* **lukemoderwell (Luke Moderwell)** — Authored the FigJam read tools (`figjam_get_board_contents` and `figjam_get_connections`) and contributed documentation.
Figma Console MCP is open source. If you want to contribute new tools or improvements, visit the [GitHub repository](https://github.com/southleft/figma-console-mcp).
# Figma MCP vs. Figma Console MCP
Source: https://docs.figma-console-mcp.southleft.com/figma-mcp-vs-figma-console-mcp
How Figma's official MCP server and Figma Console MCP differ, where they overlap, and how to use them together.
Figma's official MCP server and Figma Console MCP both connect AI assistants to Figma, and both can read from and write to Figma files. They were built for different jobs, and many teams run both in the same MCP client.
* **The official Figma MCP server** is Figma's hosted server. It focuses on design-to-code context, Code Connect, and creating content in Figma: design files, FigJam diagrams, motion, and shaders.
* **Figma Console MCP** is an open-source server focused on design-system operations: deterministic audits and design-code parity checks, token sync with round-trip IDs, component documentation, version-history diffs, extracting a design system from a codebase, and plugin console debugging.
This page reflects both servers as of September 2026. Figma's server changes often, so check [Figma's documentation](https://developers.figma.com/docs/figma-mcp-server/) for its current capabilities.
***
## At a Glance
**Made by Figma.** A hosted server you sign in to with OAuth. It provides design context for code generation, Code Connect mappings, library search, and writes to Figma through `use_figma`, which runs Plugin API JavaScript. It can also create files, generate FigJam diagrams, and work with motion, shaders, and generative plugins.
Tool surface: about 40 as of September 2026, including Weave tools for running AI models and tools.
**Made by Southleft.** A design-system-focused server that runs on your machine (or in Cloud Mode) and talks to Figma through the Desktop Bridge plugin and the REST API. Most operations are dedicated, schema-validated tools rather than generated scripts, and it also runs arbitrary Plugin API code through `figma_execute`.
121 tools. Plugin API + REST API. Open source (MIT).
***
## Shared Ground
Both servers can do the following. How they do it differs: the official server usually does it through a general tool such as `use_figma` plus a skill, and Console MCP usually has a dedicated tool for it.
| Capability | Figma MCP | Console MCP |
| - | - | - |
| Read file structure, components, and styles | `get_metadata`, `get_design_context` | `figma_get_file_data`, `figma_get_component`, `figma_get_styles`, and others |
| Screenshots | `get_screenshot` | `figma_take_screenshot`, `figma_capture_screenshot` |
| Read variables | `get_variable_defs` | `figma_get_variables`, `figma_get_token_values` |
| Search design-system assets | `search_design_system`, `get_libraries` | `figma_search_components`, library component and variable tools |
| Run Plugin API JavaScript (writes to Figma) | `use_figma` | `figma_execute` |
| Read FigJam boards | `get_figjam` | `figjam_get_board_contents`, `figjam_get_connections` |
| Skills (markdown workflow guides for agents) | Yes (`get_figma_skill`, plus skills in Figma's plugin) | Yes |
***
## What the Official Figma MCP Is Built For
These are areas where the official server has first-party capabilities that Console MCP does not provide:
| Capability | Official tools |
| - | - |
| Design context for code generation | `get_design_context`, `get_metadata`, `get_screenshot` |
| Code Connect: map Figma components to code components | `get_code_connect_map`, `add_code_connect_map`, `get_code_connect_suggestions`, `send_code_connect_mappings`, and related tools |
| Create new Figma, FigJam, and Slides files | `create_new_file` |
| Generate FigJam diagrams from Mermaid | `generate_diagram` |
| Motion context and video export | `get_motion_context`, `export_video` |
| Create and edit shaders | `create_shader`, `update_shader`, `get_shader`, `list_shaders`, `list_file_shaders` |
| Generative plugins | `create_generative_plugin`, `update_generative_plugin`, and related tools |
| Upload and download assets | `upload_assets`, `download_assets` |
| Hosted by Figma, OAuth sign-in, no local install | — |
Code Connect is the main reason to reach for the official server when generating code. It tells the AI which code component corresponds to each Figma component, so generated code uses your real components instead of recreating them.
***
## What Figma Console MCP Is Built For
Console MCP concentrates on operating a design system across Figma and code. Each of these has dedicated tools:
### Deterministic checks
Rule-based checks that return the same result for the same input, so they can gate a merge or a release:
* **Accessibility**: `figma_lint_design` (WCAG checks on the canvas), `figma_audit_component_accessibility` (state, focus, and color-blind scorecard for a component), and `figma_scan_code_accessibility` (axe-core scan of HTML, Local Mode).
* **Design-code parity**: `figma_check_design_parity` compares a Figma component with its code implementation and reports each discrepancy.
* **Design-system health**: `figma_audit_design_system_report` scores naming, token architecture, component metadata, accessibility, consistency, and coverage, and says which findings the MCP can fix.
* **Extracted-system fidelity**: `figma_ds_verify` checks that tokens extracted from a codebase parse, resolve, and are ready to import into Figma.
### Bidirectional token sync
* `figma_export_tokens` writes Figma variables to 10 formats: DTCG JSON (legacy or 2025.10 dialect), CSS custom properties, Tailwind v4 and v3, SCSS, TypeScript, flat and nested JSON, Style Dictionary v3, and Tokens Studio.
* `figma_import_tokens` applies DTCG JSON back to Figma: value updates, new collections and variables, renames matched by the Figma variable ID stored in `$extensions`, alias writes, and deletes only under `strategy: "replace"`.
* Export refuses to overwrite a token file generated from a different Figma file, or one that would lose tokens the export doesn't manage.
### Variables on any Figma plan
Figma's Variables REST API requires an Enterprise plan. Console MCP reads and writes variables through the Plugin API in the Desktop Bridge plugin, so variable tools work on every plan, including batch creates and updates of up to 100 variables per call.
### Component documentation and history
* `figma_generate_component_doc` produces markdown documentation from Figma and your code: anatomy, per-variant color, spacing, and typography tokens, annotations, a design-code parity section, and (with the `history` option) a changelog built from Figma version history and `git log`.
* Version-history tools (`figma_get_file_versions`, `figma_diff_versions`, `figma_generate_changelog`, `figma_blame_node`) diff snapshots and find when, and by whom, a property or variant was introduced.
### Codebase → design system → Figma
Seven `figma_ds_*` tools (Local Mode) analyze a production codebase, extract its styling as DTCG tokens with per-token provenance, scaffold a design-system package with Storybook, and verify it. The extracted tokens import into Figma variables with `figma_import_tokens`.
### Plugin debugging and live file awareness (Local Mode)
Console log capture from the Desktop Bridge plugin (`figma_get_console_logs`, `figma_watch_console`), the current selection (`figma_get_selection`), buffered document changes (`figma_get_design_changes`), multi-file targeting and `figma_execute_across_files`, and a plain-language health check (`figma_diagnose`).
### Other dedicated tools
Structured tools for variables, components and component sets (`figma_create_component_set`), Slots, node editing, annotations, comments, FigJam, and Slides. See the [Tools Reference](/tools).
***
## Structured Tools and Scripted Writes
Both servers can change a Figma file by running Plugin API code: `use_figma` on the official server, `figma_execute` in Console MCP. Console MCP also provides dedicated tools for common operations. For example, `figma_batch_create_variables` takes a JSON array of variables, and `figma_create_component_set` builds a variant set from an axes matrix. Their inputs are schema-validated and their errors name the problem.
Neither approach is universally better. A script is flexible and handles one-off changes. A dedicated tool is predictable and easier to review, which matters most for repeated design-system operations such as syncing hundreds of tokens across modes.
***
## How They Connect to Figma
| | Figma MCP | Console MCP |
| - | - | - |
| **Runs where** | Hosted by Figma | Your machine (`npx` or a git clone), Southleft's hosted Cloud Mode, or your own Cloudflare deployment |
| **Connection to Figma** | Figma's service | Desktop Bridge plugin over WebSocket, plus the Figma REST API |
| **Authentication** | OAuth | Personal access token; OAuth for the hosted remote endpoints |
| **Web AI clients** | Any client that supports remote MCP servers | Cloud Mode: Yes (96 tools) after pairing the Desktop Bridge plugin |
| **Source code** | Operated by Figma | Open source (MIT), self-hostable |
For Figma's current plan requirements and usage limits, see [Figma's documentation](https://developers.figma.com/docs/figma-mcp-server/). Figma Console MCP is free. It calls the Figma REST API with your own token, so Figma's REST API rate limits apply.
***
## Who Should Use Which
**The official Figma MCP** fits when:
* You want design context for implementing a screen or component
* You use Code Connect to map Figma components to your codebase
* You want a hosted server with no local install
**Figma Console MCP** fits when:
* You need to check whether coded components match their Figma specs
* You want design tokens exported to your stack's format, or code-side token edits pushed back to Figma
* You want generated component documentation with token mappings and a design and code changelog
* You want to self-host or read the source
**The official Figma MCP** fits when:
* You want an agent to create designs, files, or FigJam diagrams
* You work with motion or shaders
**Figma Console MCP** fits when:
* You maintain token collections with many modes and want batch, schema-validated variable operations
* You want repeatable accessibility and design-system health audits
* You want to audit design-code drift
* You want version-history diffs, changelogs, or blame for components
* You want to read or write annotations, or post review comments on components
Both servers can be configured in the same MCP client. One workflow:
1. **Set up the system** with Console MCP: token collections and modes, component sets with variable bindings, and a health audit.
2. **Generate code** with the official server's `get_design_context` and Code Connect.
3. **Check the result** with Console MCP's parity and accessibility tools, then fix discrepancies with either server.
4. **Document** components with `figma_generate_component_doc`.
***
## Quick Reference
| Question | Figma MCP | Console MCP |
| - | - | - |
| *Can it read my designs?* | Yes | Yes |
| *Can it write to my designs?* | Yes (`use_figma`) | Yes (dedicated tools and `figma_execute`) |
| *Does it have Code Connect?* | Yes | No |
| *Can it create new files?* | Yes (`create_new_file`) | No |
| *Does it export tokens to code formats and import them back?* | Not as dedicated tools | Yes (10 export formats, DTCG import) |
| *Does it compare a Figma component with its code?* | Not as a dedicated tool | Yes (`figma_check_design_parity`) |
| *Where does it run?* | Hosted by Figma | Your machine, Cloud Mode, or your own deployment |
| *Is the source available?* | See Figma's documentation | Yes (MIT) |
| *Who makes it?* | Figma | Southleft |
***
## How This Page Has Changed
When this comparison was first written, the official Figma MCP was read-only and focused on design-to-code, and write access was the main difference between the two servers. That is no longer true. The official server now writes to Figma, creates files, and covers motion, shaders, and diagrams. Console MCP's focus has narrowed to design-system operations. This page was rewritten in September 2026 to reflect both.
**Figma Console MCP** is an open-source project built by [Southleft](https://southleft.com). It is not a Figma product and is not supported by Figma. The official **Figma MCP server** is built and maintained by Figma.
***
## Get Started
Full 121 tool access in about 10 minutes.
Figma's documentation for its MCP server.
# Figma Console MCP
Source: https://docs.figma-console-mcp.southleft.com/index
A design-system-focused MCP server for Figma: bidirectional Figma-code sync, writes to Figma, and deterministic checks for parity, accessibility, and design-system health.
**Accuracy & safety fixes (latest v1.40.9):** Nine patches since v1.40.0's Design System Extraction, driven by community reports. Generated component docs now describe every variant accurately — backgrounds, hidden layers and the properties that show them, per-corner radius and border tokens, typography and layer structure across variants, and source links pinned to a commit. `figma_export_tokens` can no longer overwrite a token file from the wrong Figma file, overrides in extended variable collections are visible, min/max sizing survives every JSON extraction path, colors set to another color at an opacity export and import with their link intact, and the published package passes `npm audit` cleanly. Server-only — no plugin re-import needed. [See what's new →](https://github.com/southleft/figma-console-mcp/blob/main/CHANGELOG.md#1409---2026-10-02)
# Your Design System as an API
Design systems shouldn't be static documents locked in a visual tool. They should be **queryable**, **programmable**, and **always in sync** with your codebase.
Figma Console MCP is a design-system-focused MCP server. It connects AI assistants to Figma through the Desktop Bridge plugin and the REST API, so they can read your design system, change it, and check it against your code.
Figma ⇄ code. Export variables to 10 token formats and import DTCG edits back with round-trip IDs, extract a design system from an existing codebase, and compare components with their code.
Variables, components and component sets, Slots, annotations, FigJam boards, and Slides, plus any Plugin API code through `figma_execute`.
Rule-based checks that return the same result every run: design-code parity, accessibility on the canvas and in code, and design-system health.
Exact token names and values, variants, variable bindings, and states as structured, verifiable data. The server doesn't prescribe a framework or house style, so the AI writes code in your team's own stack and conventions instead of guessing values from a screenshot.
***
## The Problem
Every time a developer opens Figma, eyeballs the padding, and writes `margin: 16px` instead of `var(--spacing-md)`—that's design system debt.
Every design token manually transcribed to CSS, every component spec described in a Slack message, every "just check Figma" that leads to approximation—it compounds.
**What if your design system was queryable?**
```
"Get the Button component specs and implement it in React with our design tokens."
```
Real component data. Real token values. Real code that uses your actual design system.
***
## Three Workflows
### Make Your Work Programmable
Your design system is a product. Developers are your users. Give them an API.
Create tokens and components as you normally would
Design tokens export to CSS, Tailwind, or Sass automatically
Single source of truth that developers can query directly
**Result:** Developers stop guessing at values. Design debt decreases. Documentation stays accurate.
### Query Design Systems Directly
Stop treating Figma as a screenshot machine.
Add the MCP server to your AI assistant
Ask for token values, component specs, or visual references
Get code that uses your actual design system variables
**Result:** Implement components correctly the first time. Auto-generate token files. Debug plugins without Figma's dev tools.
### Design from Any AI Chat
Use Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no local install needed.
Run the Desktop Bridge plugin in your file
Say "Connect to my Figma plugin" — enter the pairing code in the plugin
Create components, update variables, and manipulate designs through natural language
**Result:** Full write access from any web-based AI client. Variables on any Figma plan. No Node.js required.
***
## Capabilities
Extract variables, styles, and components as structured data. Export to CSS custom properties, Tailwind config, Sass variables, or JSON.
* `figma_get_design_system_kit` — **Full design system in one call** — tokens, components, styles, visual specs, and resolved values
* `figma_get_variables` — Design tokens with multi-format export
* `figma_get_styles` — Color, text, and effect styles
* `figma_get_component` — Component metadata or reconstruction spec
* `figma_get_design_system_summary` — Overview of entire system
Turn a production codebase into a design system — analyze, tokenize, scaffold, port, verify. Local Mode only (these tools read and write your local filesystem). The extracted tokens import straight into Figma variables via `figma_import_tokens`.
* `figma_ds_analyze` — Scan one or more app codebases: framework/styling/vendor detection, usage-ranked component inventory (vendored / wrapped / pure-vendor / bespoke), variant inference from real call sites, duplicate detection, and architecture classification (atomic levels, specializations, missing primitives)
* `figma_ds_extract_tokens` — Mine styling into DTCG tokens with per-token provenance: multi-mode CSS custom properties, SCSS variables, Tailwind config values, shadcn HSL triples, utility-class frequency mining
* `figma_ds_scaffold` — Generate the design-system package: token files, token/typography/iconography showcase pages, framework peer deps
* `figma_ds_setup_storybook` — Wire a fresh Storybook workshop to the extraction: the app's real theme layers and fonts, plus a theme toolbar from the extracted modes
* `figma_ds_extract_component` — Per-component porting manifest with a ready-to-adapt CSF3 story scaffold
* `figma_ds_verify` — Deterministic fidelity evals + Figma round-trip readiness
* `figma_ds_status` — Porting progress persisted across sessions
Score your design system's health with a deterministic six-category audit — naming & semantics, token architecture, component metadata, accessibility, consistency, and coverage — from any MCP client.
* `figma_audit_design_system_report` — Scored report as data: bounded summary, per-category chunked drill-down, clamped full JSON. Live-first fileKey-verified data with the source disclosed; 5-minute cache; every finding states whether this MCP can auto-fix it (with the exact tools) or needs a design decision
* `figma_audit_design_system` — The same audit as a visual dashboard (MCP Apps hosts with `ENABLE_MCP_APPS=true`)
Inspect components and variables from team libraries the current file has subscribed — without needing the library file's URL or an Enterprise plan.
* `figma_get_library_component_by_key` — **Resolve any component key to full props + variants + visual specs.** Tries `/v1/component_sets/{key}` then falls back to `/v1/components/{key}`. Returns `componentPropertyDefinitions`, every variant with its published key, and per-variant visual specs.
* `figma_get_library_components` — Discover all components in a library file (requires the library file URL/key)
* `figma_get_library_variables` — **List library tokens.** Plugin API path works on every Figma plan; filter by `libraryName`, `collectionName`, or `resolvedType`.
* `figma_import_library_variable` — Import a library variable into the current file. Returns a local `id` ready for `figma_set_fills` or any variable-binding tool.
Real-time console log capture from your Figma plugins. No more console.log archaeology.
* `figma_get_console_logs` — Retrieve logs with filtering
* `figma_watch_console` — Real-time log streaming
* `figma_take_screenshot` — Capture UI state for debugging
Execute Figma Plugin API code directly. Build, modify, and organize components programmatically.
* `figma_execute` — Run any Plugin API code, optionally in a specific connected file via `fileKey` (Local Mode)
* `figma_execute_across_files` — Run the same script in several connected files at once (Local Mode)
* `figma_create_component_set` — Build a full variant set from an axes matrix (or combine existing components) in one call — variant keys returned, ready to instantiate
* `figma_arrange_component_set` — Organize variants with labels
* `figma_create_slot` / `figma_append_to_slot` — Add slots to components and populate them on instances (Figma Slots, GA at Config 2026), plus `figma_get_slots`, `figma_reset_slot`, and `figma_add_slot_property`
* `figma_create_variable` — Add design tokens
* Plus dedicated tools for creating, moving, resizing, cloning, renaming, and deleting nodes, and for text, fills, strokes, image fills, instance properties, and component properties
Compare a Figma component with its code implementation and generate documentation from both.
* `figma_check_design_parity` — Deterministic comparison of a Figma component with its code: visual properties, spacing, typography, token usage, component API, accessibility, and metadata, with a parity score and a fix list
* `figma_generate_component_doc` — Markdown component documentation: anatomy, per-variant color, spacing, and typography tokens, annotations, and a parity section. The optional `history` parameter adds a changelog from Figma version history and `git log`
* `figma_get_component_for_development_deep` / `figma_analyze_component_set` — Full component trees with resolved token names, and variant sets as state machines with CSS pseudo-class mappings
Work with a file's Figma version history.
* `figma_get_file_versions` / `figma_get_file_at_version` — List versions and snapshot a file or node at a past version
* `figma_diff_versions` / `figma_get_changes_since_version` — Structured diffs, including component property and binding changes
* `figma_generate_changelog` — Markdown changelog for release notes
* `figma_blame_node` — Find when, and by whom, a property or variant was introduced
Bidirectional design token synchronization — a full code⇄Figma round-trip that replaces Style Dictionary and Tokens Studio's export pipeline.
* `figma_export_tokens` — Export variables to DTCG JSON (legacy hex or DTCG 2025.10 object dialect via `dtcgDialect`), CSS custom properties, Tailwind v4/v3, SCSS, TypeScript, JSON, Style Dictionary v3, or Tokens Studio. Round-trip safe via `$extensions["figma-console-mcp"]`; scopes and codeSyntax metadata included.
* `figma_import_tokens` — Push code-side edits back with a **full apply phase**: value updates, creates for missing collections/variables, renames matched by variable ID, real `VARIABLE_ALIAS` writes, and deletes gated strictly behind `strategy: "replace"`. Accepts both DTCG dialects; dry-run previews.
* `figma_setup_design_tokens` — Bootstrap a collection + modes + variables atomically, with alias values via DTCG brace references (`"{color.blue.600}"`)
AI sees your components visually and as structured data. Implementation guidance that matches the design.
* `figma_get_component_for_development` — Visual reference + specs
* `figma_capture_screenshot` — Node-specific renders
* `figma_get_component_image` — Export as PNG/SVG
Create and read FigJam collaborative whiteboards. Build affinity maps, flowcharts, retrospective boards, and more.
* `figjam_create_sticky` / `figjam_create_stickies` — Single or batch sticky notes with 9 colors
* `figjam_create_connector` — Connect nodes with labeled lines for flowcharts
* `figjam_create_shape_with_text` — Diamonds, ellipses, and engineering shapes
* `figjam_create_table` — Structured tables with cell data
* `figjam_get_board_contents` / `figjam_get_connections` — Read everything on the board
[Full FigJam Guide →](/figjam)
Manage entire Figma Slides presentations. Create, edit, reorder, and navigate slides programmatically.
* `figma_list_slides` / `figma_get_slide_content` — Read slide data and content trees
* `figma_create_slide` / `figma_duplicate_slide` / `figma_delete_slide` — Slide lifecycle
* `figma_set_slide_transition` — 22 transition styles with 8 easing curves
* `figma_reorder_slides` — Restructure presentation order
* `figma_add_text_to_slide` / `figma_add_shape_to_slide` — Add content to slides
[Full Slides Guide →](/slides)
Full-spectrum WCAG coverage across design and code:
* **Design-side lint** — 14 WCAG checks with AA/best-practice level tagging: contrast, non-text contrast, color-only, focus indicators, disabled context, spacing, alt text, heading hierarchy, reflow, reading order, token misuse
* **Component audit** — State coverage scoring, focus indicator quality, color-blind simulation (protanopia, deuteranopia, tritanopia)
* **Code-side scan** — axe-core with 104 rules via JSDOM: ARIA, labels, landmarks, semantics, headings
* **Parity bridge** — 9 checks ensuring design accessibility intent survives code implementation
[Full Accessibility Guide →](/tools#-accessibility-tools)
***
## Choose Your Setup
**Full capabilities — 121 tools**
All tools including real-time monitoring. Requires Node.js and a Figma token.
**Web AI clients — 96 tools**
Full write access from Claude.ai, v0, Replit, or Lovable. Pair with a code — no Node.js needed.
**Quick exploration — read-only**
Zero setup, just paste a URL. Read design data and take screenshots.
### Quick Start: NPX Setup (Recommended)
Visit [figma.com/developers/api#access-tokens](https://www.figma.com/developers/api#access-tokens) and create a Personal Access Token
Add the server to your MCP client config (Claude Code, Cursor, Windsurf, Claude Desktop, etc.):
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "figma-console-mcp@latest"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
}
}
}
}
```
Install the Desktop Bridge Plugin — one-time import, no debug flags needed. Run it in your Figma file to connect.
Restart your MCP client to load the new config
Detailed instructions for NPX, Cloud Mode, Local Git, and Remote installation across all AI clients.
***
## Resources
New to MCP? Start here.
AI-powered whiteboarding — stickies, flowcharts, tables
AI-powered presentations — create, transition, navigate
Real scenarios and workflows
Complete reference for 121 tools
Common issues and solutions
***
**Open Source** — MIT licensed. Self-host for enterprise requirements or contribute on [GitHub](https://github.com/southleft/figma-console-mcp).
**Support this project** — Figma Console MCP is free and open source. If it's improved your workflow, consider [sponsoring its development](https://github.com/sponsors/southleft).
# What is Figma Console MCP?
Source: https://docs.figma-console-mcp.southleft.com/introduction
A beginner's guide to understanding MCP, Figma Console MCP, and how AI assistants can transform your design workflow.
# Understanding Figma Console MCP
New to AI-powered design tools? This guide explains everything you need to know—no technical background required.
***
## What is an MCP?
**MCP** stands for **Model Context Protocol**. Think of it as a universal translator that lets AI assistants (like Claude, GitHub Copilot, Cursor, or ChatGPT) communicate with external tools and services.
Without MCP, AI assistants are limited to what they already know. With MCP, they can:
* **Connect** to tools like Figma, GitHub, or databases
* **Read** real data from your actual projects
* **Take action** on your behalf (with your permission)
**Simple analogy:** If an AI assistant is like a helpful colleague, MCPs are like giving them access to your tools. Instead of describing your Figma file over chat, they can actually *look at it*.
***
## What is Figma Console MCP?
**Figma Console MCP** is an MCP server for working with design systems in Figma. It does four things:
1. **Works in both directions.** It moves design tokens from Figma to code and back, turns an existing codebase into a design system you can bring into Figma, and compares Figma components with their code.
2. **Writes to Figma.** It creates and edits variables, components, component sets, Slots, annotations, FigJam boards, and Slides, and can run any Figma Plugin API code.
3. **Runs deterministic checks.** Rule-based checks for design-code parity, accessibility, and design-system health give the same result every time, so you can rely on them before a release.
4. **Gives the AI facts to write code from.** It returns exact token names and values, variants, variable bindings, and states as structured data. It doesn't push a framework or coding style, so the code the AI writes follows your team's own stack and conventions.
### What it enables:
Pull design tokens, components, and styles as structured data
Bidirectional token sync between Figma and your codebase (10 export formats, DTCG import)
Build UI components and layouts directly in Figma through conversation
Accessibility scanning with WCAG checks, component scorecards, and code analysis
### In plain English:
Instead of manually copying values from Figma, you can ask:
```
"What's the padding on the Button component?"
```
Instead of transcribing tokens to CSS, you can say:
```
"Export all color variables as CSS custom properties"
```
Instead of building UI by hand, you can describe:
```
"Create a card component with an image, title, and action button"
```
The AI reads your actual design system, uses your real tokens, and generates accurate code—or creates designs directly in Figma.
***
## Why Does This Matter?
### The Problem
Every time a developer opens Figma, eyeballs the padding, and writes `margin: 16px` instead of `var(--spacing-md)`—that's design system debt.
**Common pain points:**
* Design tokens manually transcribed to CSS (and often wrong)
* Component specs described in Slack messages
* "Just check Figma" that leads to guesswork and approximation
* Designs and code drift apart over time
### The Solution
**What if your design system was queryable?**
Figma Console MCP makes this real. Your design system becomes:
* **Programmable** — Tokens export to CSS, Tailwind, or Sass automatically
* **Queryable** — AI can look up any value, any component, any style
* **Alive** — Single source of truth that developers can access directly
* **Creative** — AI can create designs using your actual tokens and components
**Result:** Developers stop guessing at values. Design debt decreases. Designs and code stay in sync.
***
## Who Is This For?
### Make Your Design System Programmable
Your design system is a product. Developers are your users. Give them an API.
**With Figma Console MCP, you can:**
* Export design tokens in any format (CSS, Tailwind, Sass, JSON)
* Generate documentation automatically
* Let developers query component specs directly
* Create consistent UI through AI-assisted design
**Example prompt:**
```
"Generate a style guide from my color and typography variables"
```
### Query Design Systems, Don't Guess
Stop treating Figma as a screenshot machine.
**With Figma Console MCP, you can:**
* Get exact token values without opening Figma
* Implement components with accurate specs
* Auto-generate token files from source
* Stay in sync with design updates
**Example prompt:**
```
"Get the Button component specs and implement it in React using our design tokens"
```
### Full-Spectrum Accessibility Scanning
WCAG coverage across design and code, without maintaining a rule database.
**With Figma Console MCP, you can:**
* Lint designs for 14 WCAG checks with AA/best-practice level tagging
* Audit components for state coverage, focus quality, and color-blind safety
* Scan HTML code with axe-core (104 rules) for ARIA, labels, and semantics
* Compare design intent vs code implementation with parity checks
**Example prompt:**
```
"Run an accessibility audit on the Button component and scan the code for issues"
```
### Manage Large Token Libraries Effortlessly
Scale your design system management with AI assistance.
**With Figma Console MCP, you can:**
* Audit token usage across components
* Batch create variables for new themes
* Document components automatically
* Ensure consistency across large libraries
**Example prompt:**
```
"Add a Dark mode to all color variables with appropriate values"
```
***
## How Do I Get Started?
**First, decide what you want to do:**
| I want to... | Setup | Time |
| - | - | - |
| **Create and modify designs with AI** | NPX Setup (Recommended) | \~10 min |
| **Design from Claude.ai, v0, Replit, or Lovable** | Cloud Mode | \~5 min |
| **Just explore my design data** (read-only) | Remote Mode | \~2 min |
### Recommended: NPX Setup (Full Capabilities)
Get all 121 tools including design creation, variable management, and component instantiation.
Visit [Figma Help](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) and create a Personal Access Token
Add the server config with your token to Claude Code, Cursor, Windsurf, Claude Desktop, or any MCP client
Install the Desktop Bridge Plugin — one-time import, no debug flags needed. Run it in your Figma file to connect.
Restart your MCP client to load the new config
### Cloud Mode (Web AI Clients)
Using Claude.ai, v0, Replit, or Lovable? Get full write access (96 tools) without installing Node.js.
Open the plugin in Figma Desktop (Plugins → Development → Figma Desktop Bridge)
Say "Connect to my Figma plugin" — your AI generates a 6-character pairing code
Toggle Cloud Mode in the plugin, enter the code, and click Connect
### Remote Mode (Read-Only)
If you just want to explore or evaluate the tool, use Remote Mode. It's read-only but requires zero setup.
Claude menu → Settings → Connectors
Name: `Figma Console (Read-Only)` / URL: `https://figma-console-mcp.southleft.com/sse`
**Remote mode without pairing is read-only.** For write access from web AI clients, use Cloud Mode above. For full capabilities with real-time monitoring, use NPX Setup.
Detailed step-by-step instructions for all setup methods and AI clients.
***
## What Can I Do With It?
Here are real prompts you can try right now:
### Design System Extraction
```
Get all design variables from https://figma.com/design/YOUR_FILE_ID
```
```
Export color styles as Tailwind config
```
```
Show me the Button component with a visual reference image
```
### Component Implementation
```
Get the Card component specs and help me implement it in React
```
```
What's the spacing between elements in the navigation bar?
```
### Accessibility Scanning
```
Run an accessibility check on this page and show me all WCAG violations
```
```
Audit the Button component for accessibility completeness and color-blind safety
```
### Design Creation (Local & Cloud Mode)
```
Create a notification toast with icon, title, and dismiss button
```
```
Build a user profile card using the Avatar and Button components
```
***
## Three Ways to Connect
Figma Console MCP offers three connection tiers with different capabilities:
| Feature | Local (NPX/Git) | Cloud Mode | Remote (Read-Only) |
| - | - | - | - |
| **Total tools** | **121** | **96** after pairing | Read-only subset |
| **Setup** | \~10 minutes | \~5 minutes | \~2 minutes |
| **Create designs** | ✅ | ✅ | ❌ |
| **Edit designs** | ✅ | ✅ | ❌ |
| **Manage variables** | ✅ | ✅ | ❌ |
| **Read design data** | ✅ | ✅ | ✅ |
| **Accessibility scanning** | ✅ | ✅ | ❌ |
| **Variables on any plan** | ✅ | ✅ | Enterprise only |
| **Requires Node.js** | Yes | No | No |
**Start with NPX Setup** for the complete experience. **Use Cloud Mode** to design from any web AI client without local installs. **Use Remote** for quick read-only exploration.
Understand the technical differences and choose the right setup.
***
## Frequently Asked Questions
No! You interact through natural language. Just describe what you want in plain English, and the AI handles the technical details.
Yes. Remote mode uses OAuth (the same secure login as "Sign in with Google"). Your credentials are never shared with the MCP server—only temporary access tokens. Local mode keeps everything on your machine.
No. They're complementary, and you can run both in the same client. Figma's official MCP server focuses on design-to-code context, Code Connect, and creating content in Figma. Figma Console MCP focuses on design-system operations: token sync, parity and accessibility checks, health audits, component documentation, and version history. See [Figma MCP vs. Figma Console MCP](/figma-mcp-vs-figma-console-mcp).
Any MCP-compatible client: Claude Desktop, Claude Code, GitHub Copilot (VS Code 1.102+), Cursor, Windsurf, Zed, and others. Web-based clients like Claude.ai, v0, Replit, and Lovable work via Cloud Mode. If your AI tool supports MCP servers, it works with Figma Console MCP.
Only for Local Mode (NPX/Git). Cloud Mode runs entirely in Cloudflare Workers — you just need Figma Desktop with the Desktop Bridge plugin. Remote read-only mode needs nothing at all.
Yes! Figma Console MCP is open-source (MIT license). The hosted remote server is free to use. You can also self-host if you prefer.
***
## Next Steps
Connect your AI assistant in minutes
Real-world examples and workflows
Complete reference for 121 tools
***
**Open Source** — Figma Console MCP is MIT licensed. Contribute, customize, or self-host for enterprise requirements on [GitHub](https://github.com/southleft/figma-console-mcp).
# MCP Apps
Source: https://docs.figma-console-mcp.southleft.com/mcp-apps
Interactive UI experiences powered by the MCP Apps protocol extension. Browse design tokens, inspect components, and more — rendered inline in your AI assistant.
MCP Apps are rich, interactive UI panels that render directly inside your AI assistant. Instead of receiving plain text responses, you get fully interactive applications — with search, filtering, click-to-copy, and real-time data refresh.
**Experimental** — MCP Apps use the [ext-apps protocol extension](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps) and require an MCP client with ext-apps support. The protocol may evolve.
***
## How MCP Apps Work
MCP Apps extend the Model Context Protocol with a UI layer. When an AI tool returns a result, it can also include an interactive HTML application that renders inline in the conversation.
```mermaid theme={null}
sequenceDiagram
participant U as User
participant A as AI Assistant
participant M as MCP Server
participant App as MCP App UI
U->>A: Browse my design tokens
A->>M: figma_browse_tokens()
M-->>A: Summary text
M-->>App: Token data (via app tool)
App->>App: Render interactive UI
Note over App: Search, filter, click-to-copy
App->>M: token_browser_refresh()
M-->>App: Fresh data
```
**Key concepts:**
* **Server-side tools** register with the MCP server and handle data fetching
* **App-only tools** are hidden from the AI model and callable only from the UI
* **Resource URIs** point the host to the HTML application to render
* **App SDK** (`@modelcontextprotocol/ext-apps`) handles the lifecycle, theming, and communication
***
## Available Apps
### Token Browser
Browse all design tokens from your Figma file in an interactive table.
**Features:**
* Organized by variable collection with expandable sections
* Filter by type (Colors, Numbers, Strings) and search by name
* Per-collection mode columns (Light, Dark, Custom) matching Figma's layout
* Color swatches with hex/rgba values and alias reference resolution
* Click any token name or value to copy it to your clipboard
**Usage:**
```
Browse the design tokens in the current file
```
The AI calls `figma_browse_tokens` which returns a brief summary to the conversation and renders the full interactive Token Browser inline. The tool uses the file currently connected through the Desktop Bridge plugin — no URL required.
### Design System Dashboard
Audit your design system with a Lighthouse-style health scorecard rendered inline.
**Features:**
* Overall weighted score (0–100) with six category gauges: Naming, Tokens, Components, Accessibility, Consistency, Coverage
* Expandable category sections with individual findings, severity indicators, and actionable details
* Diagnostic locations linking findings to specific variables, components, or collections
* Tooltips explaining each check's purpose and scoring criteria
* Refresh button to re-run the audit without consuming AI context
**Usage:**
```
Audit the design system in the current file
```
The AI calls `figma_audit_design_system` which returns a brief text summary and renders the full interactive dashboard inline. The tool uses the file currently connected through the Desktop Bridge plugin — no URL required. The same scoring engine is available without MCP Apps as `figma_audit_design_system_report`, which returns the report as data to any MCP client. The dashboard scores six categories:
| Category | Weight | What it checks |
| - | - | - |
| Naming & Semantics | 25% | Semantic variable naming, component naming conventions |
| Token Architecture | 20% | Alias usage, depth layering, mode support, descriptions |
| Component Metadata | 20% | Descriptions, variant structure, standalone vs. set ratio |
| Accessibility | 10% | Contrast-ready tokens, focus state components, readable naming |
| Consistency | 15% | Delimiter usage, casing patterns, scale adherence, mode naming |
| Coverage | 10% | Token type coverage, core component presence, variable count |
***
## Enabling MCP Apps
MCP Apps are gated behind an environment variable and only available in Local Mode.
```json theme={null}
{
"mcpServers": {
"figma-console-local": {
"command": "node",
"args": ["/path/to/figma-console-mcp/dist/local.js"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}
```
When `ENABLE_MCP_APPS` is not set or set to `"false"`, no app tools are registered and existing functionality is completely unaffected.
***
## Architecture
Each MCP App follows a modular structure:
```
src/apps//
server.ts # Tool + resource registration (compiled by tsc)
ui/
mcp-app.html # HTML shell with styles (bundled by Vite)
mcp-app.ts # App logic using ext-apps SDK (inlined into HTML)
```
**Build pipeline:**
1. **TypeScript** compiles `server.ts` to `dist/apps//server.js`
2. **Vite** bundles the UI into a single self-contained `dist/apps//mcp-app.html`
3. The server registers a resource URI that serves the built HTML file
4. The host renders the HTML inline when the tool is called
Apps use the official [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) SDK for lifecycle management, host theming, and server communication.
***
## Building Apps
The build system supports multiple apps via the `APP_NAME` environment variable:
```bash theme={null}
# Build a specific app
cross-env APP_NAME=token-browser vite build
# Build all apps (runs as part of npm run build)
npm run build:apps
```
Adding a new app requires:
1. Create `src/apps//server.ts` with tool and resource registration
2. Create `src/apps//ui/mcp-app.html` and `mcp-app.ts`
3. Add a `cross-env APP_NAME= vite build` entry to the `build:apps` script
4. Register the app in `src/local.ts` inside the `ENABLE_MCP_APPS` gate
***
## Roadmap
Planned MCP Apps:
* **Component Gallery** — Visual browser for searching and previewing components with variant exploration
* **Style Inspector** — Interactive panel for exploring color, text, and effect styles with live previews
* **Variable Diff Viewer** — Side-by-side comparison of token values across modes and branches
***
## Learn More
* [MCP Apps Protocol Extension](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps) — Official specification
* [`@modelcontextprotocol/ext-apps` on npm](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) — Client and server SDK
* [Architecture](/architecture) — How Figma Console MCP works under the hood
# Mode Comparison
Source: https://docs.figma-console-mcp.southleft.com/mode-comparison
Understand the differences between Remote, Cloud Mode, Local, and NPX installation methods and when to use each.
# Installation Methods & Execution Modes - Complete Comparison
This document clarifies the differences between installation methods and execution modes to help you choose the right setup.
## Understanding the Architecture
The MCP server has **three execution modes** and **four setup methods**:
### Execution Modes (Where Code Runs)
1. **Remote Mode** - Runs in Cloudflare Workers (cloud, read-only)
2. **Cloud Mode** - Runs in Cloudflare Workers + Cloud Write Relay (cloud, read/write)
3. **Local Mode** - Runs on your machine (Node.js, full capabilities)
### Setup Methods (How You Connect)
1. **Remote SSE/HTTP** - URL-based connection (uses Remote Mode, read-only)
2. **Cloud Mode** - Remote endpoint + Cloud Write Relay via Desktop Bridge plugin (uses Cloud Mode)
3. **NPX** - npm package distribution (uses Local Mode)
4. **Local Git** - Source code clone (uses Local Mode)
### Authentication Methods (How You Authenticate)
1. **OAuth** - Automatic browser-based auth (Remote SSE only)
2. **Personal Access Token (PAT)** - Bearer token (Remote `/mcp` endpoint, Cloud Mode)
3. **Personal Access Token (PAT)** - Environment variable (NPX + Local Git)
4. **Pairing Code** - 6-character code to connect Desktop Bridge plugin to cloud relay (Cloud Mode only)
**Key Insight:** Your choice of mode determines both capability level and setup complexity.
## 🎯 Quick Decision Guide
### ⚠️ Critical: Tool Count Differences
| Mode | Tools Available | Write Access | Needs Node.js | Real-time |
| - | - | - | - | - |
| **Local Mode** (NPX or Git) | **121** | Yes | Yes | Yes |
| **Cloud Mode** (Remote + Relay) | **96** | Yes | No | No |
| **Remote Mode** (read-only) | Read-only subset | No | No | No |
> **Bottom line:** Remote mode is read-only until you pair the plugin. Cloud Mode adds write access (96 tools) without Node.js. Local has everything (121 tools) including real-time monitoring.
> **Two hosted endpoints.** The Cloud Mode count is for the `/mcp` endpoint that web AI clients use. The `/sse` endpoint that Claude Desktop and Claude Code connect to also lists the console-log, screenshot, navigation, status, and reload tools, which need a headless browser session that only `/sse` keeps open. Remote mode is either endpoint before you pair the plugin.
### Use NPX Setup (Recommended for Most Users)
* ✅ **All 121 tools** including design creation and real-time monitoring
* ✅ Automatic updates with `@latest`
* ✅ Desktop Bridge Plugin support (recommended connection — no debug flags needed)
* ✅ Variables without Enterprise plan
* ⚠️ Requires Node.js 18+ and `FIGMA_ACCESS_TOKEN` (manual, one-time)
### Use Cloud Mode (Web AI Clients)
* ✅ **96 tools** — full write access (create, edit, delete) plus REST API reads
* ✅ No Node.js required — only Figma Desktop with the Desktop Bridge plugin
* ✅ Works with Claude.ai, v0, Replit, Lovable, any MCP-capable web platform
* ✅ Variables without Enterprise plan (via Plugin API)
* ⚠️ Requires pairing the Desktop Bridge plugin via a 6-character code
* ❌ No real-time selection tracking, document changes, or console streaming
### Use Local Git (For Contributors)
* ✅ **All 121 tools** including design creation
* ✅ Full source code access
* ✅ Modify and test changes
* ⚠️ Requires `FIGMA_ACCESS_TOKEN` (manual)
* ⚠️ Manual updates via `git pull && npm run build`
### Use Remote Mode (Read-Only Exploration)
* ✅ **TRUE zero-setup** - Just paste a URL
* ✅ **OAuth authentication** - No manual tokens
* ✅ Works without Figma Desktop restart
* ❌ **Read-only** — cannot create or modify designs
* ❌ Cannot use Desktop Bridge plugin
* ❌ Variables require Enterprise plan
***
## Setup Methods Comparison
| Aspect | Remote (read-only) | Cloud Mode | NPX | Local Git |
| - | - | - | - | - |
| **Execution** | Cloudflare Workers | Cloudflare Workers + Relay | Local Node.js | Local Node.js |
| **Code** | `src/index.ts` | `src/index.ts` + relay | `dist/local.js` (npm) | `dist/local.js` (source) |
| **Authentication** | OAuth (automatic) | PAT + pairing code | PAT (manual) | PAT (manual) |
| **Setup Complexity** | ⭐ Zero-setup | Moderate (plugin + pairing) | Manual token + plugin install | Manual token + plugin install |
| **Distribution** | URL only | URL + plugin | npm package | git clone |
| **Updates** | Automatic (server-side) | Automatic (server-side) | `@latest` auto-updates | Manual `git pull + build` |
| **Figma Desktop** | Not required | Required (Desktop Bridge) | Required (Desktop Bridge) | Required (Desktop Bridge) |
| **Desktop Bridge** | ❌ Not available | ✅ Required for relay | ✅ Available | ✅ Available |
| **Node.js Required** | No | No | Yes | Yes |
| **Source Access** | No | No | No | Yes |
| **Tools** | Read-only subset | 96 (read/write) | 121 (full) | 121 (full) |
| **Use Case** | Quick evaluation | Web AI clients | Most users | Developers |
***
## Feature Availability Matrix
| Feature | Remote (read-only) | Cloud Mode | Local Mode | Notes |
| - | - | - | - | - |
| **Read Design Data** | ✅ | ✅ | ✅ | All modes use Figma REST API |
| **Design Creation (write)** | ❌ | ✅ | ✅ | Cloud via relay, Local via WebSocket |
| **Variable Management** | ⚠️ | ✅ | ✅ | Remote requires Enterprise. Cloud/Local use Plugin API (any plan) |
| **Screenshots** | ✅ | ✅ | ✅ | All use Figma REST API |
| **Design System Reads** | ✅ | ✅ | ✅ | Variables, components, styles via Figma API |
| **Codebase → Design System Extraction** (`figma_ds_*`) | ❌ | ❌ | ✅ | Local-only — reads and writes your local filesystem |
| **Design-System Health Report** (`figma_audit_design_system_report`) | ❌ | ❌ | ✅ | Local-only |
| **Component Search & Summaries** (`figma_search_components`, `figma_get_component_details`, `figma_get_design_system_summary`, `figma_get_token_values`) | ❌ | ❌ | ✅ | Local-only; Cloud Mode can use `figma_get_design_system_kit` and the library tools |
| **Multi-File Execution** (`figma_execute_across_files`, `fileKey` targeting) | ❌ | ❌ | ✅ | Cloud Mode pairs with one plugin instance |
| **Desktop Bridge Plugin** | ❌ | ✅ (required) | ✅ | Plugin required for Cloud relay and Local write access |
| **Real-time Selection Tracking** | ❌ | ❌ | ✅ | Local-only — requires persistent WebSocket |
| **Document Change Monitoring** | ❌ | ❌ | ✅ | Local-only — requires persistent WebSocket |
| **Console Log Streaming** | ❌ | ❌ | ✅ | Local-only — zero-latency via WebSocket |
| **Console Logs (on-demand)** | ✅ | ✅ | ✅ | Remote uses Browser Rendering API; Cloud + Local use the Desktop Bridge plugin |
| **OAuth Authentication** | ✅ | ❌ | ❌ | Remote SSE only |
| **Zero Setup** | ✅ | ❌ | ❌ | Remote: just paste URL |
| **No Node.js Required** | ✅ | ✅ | ❌ | Cloud Mode only needs Figma Desktop + plugin |
| **Reliable Component Descriptions** | ⚠️ | ✅ | ✅ | API has bugs; plugin method is reliable |
| **Works Behind Corporate Firewall** | ⚠️ | ⚠️ | ✅ | Remote/Cloud require internet, Local works offline |
| **Multi-User Shared Token** | ✅ | ❌ | ❌ | Remote uses per-user OAuth |
### Legend
* ✅ Available
* ❌ Not Available
* ⚠️ Limited/Conditional
***
## Architecture Comparison
### Remote Mode Architecture (Read-Only)
```
Claude Desktop/Code
↓ (SSE over HTTPS)
Cloudflare Workers MCP Server
↓ (Browser Rendering API)
Headless Browser (in CF Workers)
↓ (HTTPS)
Figma Web App
↓ (REST API)
Figma Files & Design Data
```
**Key Points:**
* Headless browser runs in Cloudflare's infrastructure (Browser Rendering API)
* Cannot access `localhost` on your machine
* OAuth tokens stored in Cloudflare KV
* \~10-30s cold start for first request
* Read-only tools (REST API reads, console/screenshot/navigate via headless browser)
### Cloud Mode Architecture (Read/Write via Relay)
```
Claude.ai / v0 / Replit / Lovable
↓ (Streamable HTTP)
Cloudflare Workers MCP Server (/mcp)
↓ (fetch RPC)
Plugin Relay Durable Object
↓ (WebSocket)
Desktop Bridge Plugin (ui.html)
↓ (postMessage)
Plugin Worker (code.js)
↓ (Plugin API)
Figma Design Data
```
**Key Points:**
* No Node.js required — relay runs entirely in Cloudflare Workers
* Desktop Bridge plugin connects to the cloud relay via WebSocket
* Pairing flow: AI generates 6-character code → user enters in plugin → connected
* 96 tools available after pairing — write/manipulation + REST API reads + design system + slides + figjam + annotations + comments + version history
* Variables work on any Figma plan (uses Plugin API, not Enterprise REST API)
* Pairing code expires after 5 minutes
### Local Mode Architecture (Full Capabilities)
```
Claude Desktop/Code/Cursor/Windsurf
↓ (stdio transport)
Local MCP Server (Node.js)
↓ (WebSocket, ports 9223–9232)
Figma Desktop Bridge Plugin
↓ (Plugin API)
Variables & Components Data
```
**Key Points:**
* Install the Desktop Bridge Plugin once — no debug flags needed
* Server automatically selects an available port (9223–9232) for multi-instance support
* All 121 tools work through WebSocket
* Plugin can access local variables (no Enterprise API needed)
* Instant console log capture via WebSocket
* Real-time selection tracking and document change monitoring
***
## Tool Availability by Mode
### Core Tools Available in Both Modes
| Tool | Remote | Local | Notes |
| - | - | - | - |
| `figma_navigate` | ✅ | ✅ | Remote navigates the cloud headless browser; Local switches the active file among connected plugins |
| `figma_get_console_logs` | ✅ | ✅ | Both capture logs, Local has lower latency |
| `figma_watch_console` | ✅ | ✅ | Real-time log streaming |
| `figma_take_screenshot` | ✅ | ✅ | Both use Figma REST API |
| `figma_reload_plugin` | ✅ | ✅ | Reloads current page |
| `figma_clear_console` | ✅ | ✅ | Clears log buffer |
| `figma_get_status` | ✅ | ✅ | Check connection status |
| `figma_get_design_system_kit` | ✅ | ✅ | Full design system in one call — tokens, components, styles, visual specs |
| `figma_get_variables` | ✅\* | ✅\*\* | \*Enterprise API required. \*\*Can use Desktop Bridge plugin |
| `figma_get_component` | ✅\* | ✅\*\* | \*Descriptions may be missing. \*\*Reliable via plugin |
| `figma_get_styles` | ✅ | ✅ | Both use Figma REST API |
| `figma_get_file_data` | ✅ | ✅ | Both use Figma REST API |
| `figma_get_component_image` | ✅ | ✅ | Both use Figma REST API |
| `figma_get_component_for_development` | ✅ | ✅ | Both use Figma REST API |
| `figma_get_file_for_plugin` | ✅ | ✅ | Both use Figma REST API |
### Key Differences
**Variables API:**
* **Remote Mode:** Requires Figma Enterprise plan for Variables API
* **Local Mode:** Can bypass Enterprise requirement using Desktop Bridge plugin
**Component Descriptions:**
* **Remote Mode:** Figma REST API has known bugs (descriptions often missing)
* **Local Mode:** Desktop Bridge plugin uses `figma.getNodeByIdAsync()` (reliable)
***
## Prerequisites & Setup Time
### Remote (Read-Only)
**Prerequisites:** None
**Setup Time:** 2 minutes
**Steps:**
1. Open Claude Desktop → Settings → Connectors
2. Click "Add Custom Connector"
3. Paste URL: `https://figma-console-mcp.southleft.com/sse`
4. Done ✅ (OAuth happens automatically on first API use)
### Cloud Mode
**Prerequisites:**
* Figma Desktop installed
* Desktop Bridge plugin imported and running in your file
* A web AI client connected to `https://figma-console-mcp.southleft.com/mcp` (with Figma PAT as Bearer token)
**Setup Time:** 5 minutes
**Steps:**
1. Connect your web AI client to the `/mcp` endpoint with your Figma PAT
2. Tell your AI to connect to your Figma plugin (natural language)
3. AI generates a 6-character pairing code
4. In the Desktop Bridge plugin, toggle "Cloud Mode" and enter the code
5. Done ✅ — 96 tools with full write access
### NPX
**Prerequisites:**
* Node.js 18+
* Figma Desktop installed
* Figma Personal Access Token ([get one](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens))
**Setup Time:** 10 minutes
**Steps:**
1. Get Figma Personal Access Token
2. Add to MCP config with `FIGMA_ACCESS_TOKEN` env var
3. Install the Desktop Bridge Plugin (one-time — Plugins → Development → Import from manifest)
4. Restart your MCP client
### Local Git
**Prerequisites:**
* Node.js 18+
* Git
* Figma Desktop installed
* Figma Personal Access Token ([get one](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens))
**Setup Time:** 15 minutes
**Steps:**
1. Clone repository: `git clone https://github.com/southleft/figma-console-mcp.git`
2. Run `npm install && npm run build:local`
3. Get Figma Personal Access Token
4. Configure MCP client JSON config with path to `dist/local.js`
5. Set `FIGMA_ACCESS_TOKEN` environment variable
6. Install the Desktop Bridge Plugin (one-time — Plugins → Development → Import from manifest)
7. Restart your MCP client
***
## Authentication Comparison
### Remote SSE - OAuth (Automatic) ⭐ Simplest
**Method:** Remote read-only mode (SSE endpoint)
**How it works:**
1. First design system tool call triggers OAuth
2. Browser opens automatically to Figma authorization page
3. User authorizes app (one-time)
4. Token stored in Cloudflare KV (persistent across sessions)
5. Automatic token refresh when expired
**Benefits:**
* ✅ **TRUE zero-setup** - No manual token creation
* ✅ Per-user authentication
* ✅ Automatic token refresh
* ✅ Works with Free, Pro, and Enterprise Figma plans
**Limitations:**
* ⚠️ Requires internet connection
* ⚠️ Initial authorization flow required (one-time)
* ❌ Read-only — no write access
### Cloud Mode - PAT + Pairing Code
**Method:** Cloud Mode with write relay
**How it works:**
1. User creates PAT and provides it as Bearer token when connecting to `/mcp` endpoint
2. AI generates a 6-character pairing code (valid for 5 minutes)
3. User enters code in Desktop Bridge plugin (Cloud Mode toggle)
4. Relay authenticates the plugin-to-cloud connection
5. All write operations flow through the authenticated relay
**Benefits:**
* ✅ Write access without Node.js
* ✅ Pairing code adds a second factor of trust (plugin must be in the right file)
* ✅ Variables on any Figma plan via Plugin API
**Limitations:**
* ❌ Manual PAT creation required
* ❌ Pairing code expires after 5 minutes
* ⚠️ Must re-pair if connection drops
### NPX + Local Git - Personal Access Token (Manual)
**Method:** Both NPX and Local Git modes
**How it works:**
1. User creates PAT at [https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens)
2. Set as `FIGMA_ACCESS_TOKEN` environment variable in MCP config
3. MCP server uses PAT for all API calls
4. No automatic refresh (token valid for 90 days)
**Benefits:**
* ✅ Works offline (for console debugging)
* ✅ No browser-based OAuth flow
* ✅ Simpler for single-user setups
* ✅ Full 121 tools including real-time monitoring
**Limitations:**
* ❌ **Manual token creation required**
* ❌ Must manually refresh every 90 days
* ❌ Single shared token (no per-user auth)
* ❌ **Requires Desktop Bridge Plugin** (one-time import)
**Why NPX ≠ Simpler:** Despite being distributed via npm, NPX has identical authentication complexity to Local Git. The only difference is distribution method, not setup complexity.
***
## Figma Desktop Bridge Plugin
### Required for Both Local Mode and Cloud Mode
The Desktop Bridge Plugin is the bridge between Figma and the MCP server. It communicates via WebSocket — no special Figma launch flags needed, and it persists across Figma restarts.
* **Local Mode:** Plugin connects directly to the local MCP server via WebSocket (ports 9223-9232)
* **Cloud Mode:** Plugin connects to the Cloudflare relay via WebSocket after pairing with a 6-character code
**Plugin Setup:**
1. Open Figma Desktop (normal launch — no debug flags needed)
2. Go to **Plugins → Development → Import plugin from manifest...**
3. Select `figma-desktop-bridge/manifest.json` from the figma-console-mcp directory
4. Run the plugin in your Figma file — it auto-connects via WebSocket
> **One-time import.** Once imported, the plugin stays in your Development plugins list.
**What the plugin provides:**
| Feature | Without Plugin | With Plugin (Cloud Mode) | With Plugin (Local Mode) |
| - | - | - | - |
| Variables API | Enterprise plan required | ✅ Free/Pro plans work | ✅ Free/Pro plans work |
| Variable data | REST API (limited) | ✅ Full local variables | ✅ Full local variables |
| Component descriptions | Often missing (API bug) | ✅ Always present | ✅ Always present |
| Design creation (write) | ❌ | ✅ Via cloud relay | ✅ Via local WebSocket |
| Data freshness | Cache + API limits | Per-request via relay | ✅ Real-time from Figma |
| Selection tracking | ❌ | ❌ | ✅ Real-time via WebSocket |
| Document change monitoring | ❌ | ❌ | ✅ Real-time via WebSocket |
**Local Mode Transport:** The server automatically selects an available port in the range 9223–9232, supporting multiple simultaneous MCP instances. All 121 tools work through the WebSocket transport.
**Cloud Mode Transport:** The plugin connects to the Cloudflare relay after pairing. Write operations are relayed from the cloud MCP server through the Durable Object to the plugin. 96 tools are available.
### Plugin Does NOT Work with Remote Read-Only Mode
Remote read-only mode runs in Cloudflare Workers which cannot connect to `localhost` on your machine. The Desktop Bridge Plugin requires either a local MCP server (NPX or Local Git) or Cloud Mode pairing.
***
## When to Switch Modes
### Switch from Remote (read-only) → Cloud Mode if:
* ❌ You need to create or modify designs from a web AI client
* ❌ You need variables but don't have Enterprise plan
* ❌ Component descriptions are missing in API responses
### Switch from Remote (read-only) → NPX/Local Git if:
* ❌ You need real-time selection tracking or document change monitoring
* ❌ You're developing Figma plugins (need console log streaming)
* ❌ You need the full Local Mode tool set
* ❌ You need offline access
### Switch from Cloud Mode → NPX/Local Git if:
* ❌ You need real-time selection tracking or document changes
* ❌ You need console log streaming
* ❌ You need MCP Apps (Token Browser, Design System Dashboard)
* ❌ You want to extract a design system from a codebase (`figma_ds_*` tools)
* ❌ You need the design-system health report, component search, or multi-file execution
* ❌ Connection drops between AI turns are disruptive to your workflow
### Switch from NPX/Local Git → Cloud Mode if:
* ✅ You want to use web AI clients (Claude.ai, v0, Replit, Lovable)
* ✅ You don't need real-time monitoring features
* ✅ You can't or don't want to install Node.js
### Switch from NPX/Local Git → Remote (read-only) if:
* ✅ You got Enterprise plan (Variables API now available)
* ✅ You're no longer developing plugins
* ✅ You want zero-maintenance OAuth setup
* ✅ You want per-user authentication
* ✅ You only need read access
### Switch from NPX → Local Git if:
* ✅ You want to modify source code
* ✅ You want to test unreleased features
* ✅ You're developing the MCP server itself
### Switch from Local Git → NPX if:
* ✅ You don't need source code access
* ✅ You want automatic updates
* ✅ You want simpler distribution (no git operations)
***
## Cost Comparison
All setup methods are completely free:
### Remote / Cloud Mode (Free - Hosted by Project)
* ✅ Free to use
* ✅ Hosted on Cloudflare Workers
* ✅ No infrastructure costs for users
* ⚠️ Shared rate limits (fair use)
### NPX (Free - Self-Hosted)
* ✅ Free to use
* ✅ Runs on your machine
* ✅ No external dependencies after setup
* ⚠️ Uses your CPU/memory
### Local Git (Free - Self-Hosted)
* ✅ Free to use
* ✅ Runs on your machine
* ✅ Full source code access
* ⚠️ Uses your CPU/memory
***
## Troubleshooting by Mode
### Remote Mode Common Issues
* **"OAuth authentication failed"** → Try re-authenticating via auth\_url
* **"Browser connection timeout"** → Cold start (wait 30s, try again)
* **"Variables API 403 error"** → Enterprise plan required (use Cloud Mode or Local Mode instead)
### Cloud Mode Common Issues
* **Pairing code expired** → Ask your AI to generate a new pairing code (codes expire after 5 minutes)
* **Connection drops between AI turns** → Re-pair by asking your AI to reconnect and entering a fresh code in the plugin
* **"Cloud Mode" toggle not visible** → Re-import the manifest from `~/.figma-console-mcp/plugin/manifest.json` to refresh Figma's cached plugin code (Cloud Mode was added in v1.12.0)
* **Plugin shows "Disconnected" in Cloud Mode** → Check your internet connection; the relay requires both the plugin and the cloud server to be online
* **Write operations not working** → Verify the Desktop Bridge plugin is running in the file you want to modify
### Local Mode Common Issues
* **"Failed to connect to Figma Desktop"** → Install the Desktop Bridge Plugin (Plugins → Development → Import from manifest) and run it in your file
* **"No plugin UI found"** → Make sure the Desktop Bridge Plugin is running in your Figma file
* **"Variables cache empty"** → Close and reopen Desktop Bridge plugin
* **Plugin shows "Disconnected"** → Make sure the MCP server is running (start/restart your MCP client)
***
## Summary
**For most users: Start with NPX Setup** ⭐
* All 121 tools including design creation and real-time monitoring
* Automatic updates with `@latest`
* Desktop Bridge plugin support
* Variables without Enterprise plan
**Use Cloud Mode when:**
* You use web AI clients (Claude.ai, v0, Replit, Lovable)
* You need write access but can't install Node.js
* You don't need real-time selection/document tracking
**Use Local Git when:**
* You're developing the MCP server
* You want to modify source code
* You need unreleased features
* You're testing changes before contributing
**Use Remote (read-only) when:**
* You just want to explore/evaluate the tool
* You only need read-only access to design data
* You want zero-setup experience
* You don't need design creation capabilities
**Key Takeaway:** The three modes offer a clear capability progression:
* **Remote (read-only):** view data, screenshots, design system extraction
* **Cloud Mode:** 96 tools — adds full write access (create, edit, delete) via relay
* **Local Mode (NPX/Git):** 121 tools — adds real-time monitoring (selection, changes, console)
The difference is not just authentication, but **fundamental capabilities**:
* **Remote:** Cannot create, modify, or delete anything in Figma
* **Cloud:** Full design creation and variable management via the Desktop Bridge relay
* **Local:** Everything in Cloud, plus real-time selection tracking, document change monitoring, and console log streaming
# OAuth Setup
Source: https://docs.figma-console-mcp.southleft.com/oauth-setup
Configure OAuth authentication for the Figma Console MCP server, enabling automatic browser-based authentication.
# OAuth Setup Guide
This guide explains how to set up OAuth authentication for the Figma Console MCP server, allowing users to authenticate with their own Figma accounts.
## Overview
OAuth authentication enables:
* ✅ **Per-user authentication** - Each user authenticates with their own Figma account
* ✅ **Secure token storage** - Tokens stored securely in Cloudflare Workers KV (encrypted at rest)
* ✅ **No credential sharing** - No need to share personal access tokens
* ✅ **Browser-based flow** - Seamless authentication experience
* ✅ **Automatic token management** - Tokens managed transparently
## Architecture
```
User → Claude Code → Remote MCP Server
↓
Browser OAuth Flow → Figma Authorization
↓
Token stored in Workers KV (per-session)
↓
All API calls use user's personal token
```
***
## For Server Administrators
### Step 1: Create a Figma OAuth App
1. Go to [Figma Developers](https://www.figma.com/developers)
2. Click **"My Apps"** → **"Create new app"**
3. Fill in app details:
* **App name**: `Figma Console MCP` (or your preferred name)
* **App description**: `AI-powered Figma debugging and design system tools`
* **App website**: `https://github.com/southleft/figma-console-mcp`
4. Add **Redirect URL**:
```
https://figma-console-mcp.southleft.com/oauth/callback
```
Replace `figma-console-mcp.southleft.com` with your actual deployment URL.
5. **Save** and copy:
* ✅ **Client ID** (public)
* ✅ **Client Secret** (private - only shown once!)
### Step 2: Configure Cloudflare Secrets
Set the OAuth credentials as Cloudflare Workers secrets:
```bash theme={null}
# Set Client ID
wrangler secret put FIGMA_OAUTH_CLIENT_ID
# Paste your Client ID when prompted
# Set Client Secret
wrangler secret put FIGMA_OAUTH_CLIENT_SECRET
# Paste your Client Secret when prompted
```
**Important**: Never commit these secrets to version control!
### Step 3: Deploy Your MCP Server
```bash theme={null}
npm run deploy
```
Or via Cloudflare Dashboard:
1. Go to **Workers & Pages** → **figma-console-mcp**
2. Navigate to **Settings** → **Variables**
3. Add encrypted environment variables:
* `FIGMA_OAUTH_CLIENT_ID`
* `FIGMA_OAUTH_CLIENT_SECRET`
### Step 4: Verify Configuration
Check your deployment's health endpoint:
```bash theme={null}
curl https://figma-console-mcp.southleft.com/health
```
Response should include:
```json theme={null}
{
"status": "healthy",
"oauth_configured": true,
"endpoints": ["/oauth/authorize", "/oauth/callback", ...]
}
```
***
## For End Users
### Installation
Users simply connect to your remote MCP server - no OAuth setup needed on their end!
```bash theme={null}
claude mcp add --transport sse figma-console https://figma-console-mcp.southleft.com/sse
```
### Authentication Flow
1. **First API Call**: When a user calls a Figma API tool for the first time, they'll receive an error with an authentication URL
2. **Browser Opens**: Their browser automatically opens the Figma OAuth page
3. **User Authorizes**: User logs in with Figma and authorizes the app
4. **Success**: Browser shows success message and closes automatically
5. **All Set**: Subsequent API calls work seamlessly with their personal token
### Example User Experience
```
User: "Get variables from my Figma file"
Claude: Authentication required. Opening browser...
[Browser opens → User logs in → Success!]
Claude: ✅ Retrieved 247 design variables from your file
```
***
## Security Considerations
### Token Storage
* Tokens stored in Cloudflare Workers KV (encrypted at rest)
* Scoped per-session (not shared between users)
* Automatically cleaned up when tokens expire (90-day TTL)
### OAuth Scopes
Currently requesting:
* `file_content:read` - Read access to Figma file content
* `library_content:read` - Read access to library/component content
* `file_variables:read` - Read access to design variables (for Enterprise accounts)
### Token Refresh
* ✅ Automatic token refresh implemented
* Tokens are automatically refreshed when expired using the refresh token
* Users only need to re-authenticate if refresh fails or after extended inactivity
### Best Practices
✅ **DO**:
* Keep Client Secret confidential
* Use HTTPS for all OAuth callbacks
* Rotate secrets periodically
* Monitor OAuth usage via Figma dashboard
❌ **DON'T**:
* Commit secrets to version control
* Share Client Secret publicly
* Use OAuth for untrusted deployments
***
## Troubleshooting
### "OAuth not configured" Error
**Symptom**: Users see `OAuth not configured` error
**Solution**: Ensure `FIGMA_OAUTH_CLIENT_ID` and `FIGMA_OAUTH_CLIENT_SECRET` are set in Cloudflare Workers secrets
```bash theme={null}
# Check if secrets are set
wrangler secret list
# Set missing secrets
wrangler secret put FIGMA_OAUTH_CLIENT_ID
```
### "Invalid redirect\_uri" Error
**Symptom**: OAuth callback fails with redirect URI mismatch
**Solution**: Ensure redirect URL in Figma app settings exactly matches your deployment URL:
```
https://your-domain.com/oauth/callback
```
### Token Expired
**Symptom**: Users see "Token expired. Please re-authenticate."
**Solution**: User needs to call any Figma API tool to trigger re-authentication flow
### Debugging OAuth Flow
Enable debug logging:
```bash theme={null}
# Check Cloudflare Workers logs
wrangler tail
```
***
## Migration from Personal Access Tokens
If you're currently using `FIGMA_ACCESS_TOKEN` (deprecated):
1. Set up OAuth as described above
2. Keep `FIGMA_ACCESS_TOKEN` for backward compatibility
3. New users will automatically use OAuth
4. Existing token-based users can continue until tokens expire
5. Eventually remove `FIGMA_ACCESS_TOKEN` when all users migrated
***
## OAuth App Settings
### Scopes Requested
* `file_content:read` - Read Figma file content
* `library_content:read` - Read library/component data
* `file_variables:read` - Read design variables (Enterprise)
### Webhook Configuration (Optional)
Future enhancement: Set up webhooks for token revocation notifications
***
## Support
* **Documentation**: [https://github.com/southleft/figma-console-mcp](https://github.com/southleft/figma-console-mcp)
* **Issues**: [https://github.com/southleft/figma-console-mcp/issues](https://github.com/southleft/figma-console-mcp/issues)
* **Figma OAuth Docs**: [https://www.figma.com/developers/api#oauth2](https://www.figma.com/developers/api#oauth2)
# Reconstruction Format
Source: https://docs.figma-console-mcp.southleft.com/reconstruction-format
Generate node tree specifications for programmatic component creation with the Figma Component Reconstructor plugin.
# Reconstruction Format Guide
The reconstruction format generates node tree construction specifications compatible with the Figma Component Reconstructor plugin, enabling programmatic component creation.
## Overview
### Two Export Formats
**Metadata Format (Default)**
* Comprehensive documentation of component properties
* Ideal for style guides, design systems, and documentation
* Includes variant information, design tokens, and quality metrics
**Reconstruction Format** ⭐ NEW
* Complete node tree specification for programmatic creation
* All properties needed to recreate components in Figma
* Compatible with Figma Component Reconstructor plugin
## Usage
### Basic Usage
```javascript theme={null}
// Get reconstruction specification
const result = await figma_get_component({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '123:456',
format: 'reconstruction'
});
```
### Output Structure
The reconstruction format returns the node specification directly at the root level (compatible with Figma Component Reconstructor plugin):
```json theme={null}
{
"name": "Badge Success Dot",
"type": "ELLIPSE",
"width": 8,
"height": 8,
"x": 0,
"y": 0,
"fills": [{
"type": "SOLID",
"color": { "r": 0.21, "g": 0.70, "b": 0.44, "a": 1.0 },
"opacity": 1,
"visible": true
}],
"strokes": [],
"effects": [],
"opacity": 1,
"blendMode": "NORMAL",
"children": []
}
```
Auto-layout frames also carry their layout and sizing, including min/max constraints, and each child's position relative to its parent:
```json theme={null}
{
"name": "Card",
"type": "COMPONENT",
"x": 0, "y": 0, "width": 320, "height": 56,
"layoutMode": "HORIZONTAL",
"primaryAxisSizingMode": "AUTO",
"counterAxisSizingMode": "AUTO",
"itemSpacing": 12,
"paddingLeft": 16, "paddingRight": 16, "paddingTop": 8, "paddingBottom": 8,
"layoutSizingHorizontal": "HUG",
"minWidth": 320,
"maxWidth": 640,
"children": [
{ "name": "Body", "type": "FRAME", "x": 16, "y": 8, "width": 252, "height": 40,
"layoutSizingHorizontal": "FILL", "minHeight": 40, "maxHeight": 200 }
]
}
```
The reconstruction format always reads the node tree from the Figma REST API, so it needs a Figma access token even when the Desktop Bridge plugin is connected.
**Note:** Unlike the metadata format which wraps the response with `fileKey`, `nodeId`, and `source` fields, the reconstruction format returns the raw spec for direct plugin compatibility.
## Supported Node Types
The reconstruction format supports all major Figma node types:
* **Layout Containers**: `FRAME`, `COMPONENT`, `COMPONENT_SET`, `INSTANCE`, `GROUP`, `SECTION`
* **Shapes**: `RECTANGLE`, `ELLIPSE`, `POLYGON`, `STAR`, `VECTOR`, `LINE`
* **Text**: `TEXT` (with font properties)
* **Special**: `BOOLEAN_OPERATION`, `SLICE`
## Properties Extracted
### Common Properties (All Nodes)
* `name` - Node name
* `type` - Node type
* `x`, `y` - Position
* `width`, `height` - Dimensions
* `opacity` - Opacity (0-1)
* `blendMode` - Blend mode
* `visible` - Visibility flag
* `locked` - Lock status
* `description` - Node description
* `constraints` - Layout constraints
### Visual Properties
* `fills` - Fill paints (solid, gradient, image)
* `strokes` - Stroke paints
* `strokeWeight` - Stroke thickness
* `strokeAlign` - Stroke alignment
* `effects` - Shadow and blur effects
* `cornerRadius` - Corner radius
* `rectangleCornerRadii` - Individual corner radii
### Layout Properties (Frames/Components)
* `layoutMode` - Auto-layout mode (`NONE`, `HORIZONTAL`, `VERTICAL`)
* `paddingLeft`, `paddingRight`, `paddingTop`, `paddingBottom` - Padding
* `itemSpacing` - Gap between items
* `primaryAxisAlignItems` - Main axis alignment
* `counterAxisAlignItems` - Cross axis alignment
* `clipsContent` - Clipping flag
### Text Properties
* `characters` - Text content
* `fontSize` - Font size
* `fontName` - Font family and style
* `textAlignHorizontal` - Horizontal alignment
* `textAlignVertical` - Vertical alignment
* `lineHeight` - Line height
* `letterSpacing` - Letter spacing
## Color Format
Colors are in Figma's normalized 0-1 RGB format (NOT 0-255):
```json theme={null}
{
"color": {
"r": 0.21, // Red: 0.0 to 1.0
"g": 0.70, // Green: 0.0 to 1.0
"b": 0.44, // Blue: 0.0 to 1.0
"a": 1.0 // Alpha: 0.0 to 1.0
}
}
```
## Working with Component Sets
For `COMPONENT_SET` nodes (variants), the response includes available variants:
```json theme={null}
{
"spec": {
"type": "COMPONENT_SET",
"name": "Button",
"children": [...]
},
"availableVariants": [
"Type=Primary, Size=Medium",
"Type=Secondary, Size=Medium",
"Type=Primary, Size=Large"
],
"note": "This is a COMPONENT_SET with multiple variants..."
}
```
To extract a specific variant, you can filter the children array or use a custom implementation.
## Validation
Reconstruction specs are validated server-side against plugin requirements. Invalid specs will return error messages. The spec itself doesn't include validation fields - it's just the raw node specification.
### Validation Checks
* ✅ Required fields (name, type)
* ✅ Valid node types
* ✅ Dimension constraints (width/height ≥ 0)
* ✅ Opacity range (0-1)
* ✅ Color value range (0-1 for RGB)
* ✅ Recursive validation of children
## Use Cases
### 1. Version Control for Components
Export component specifications to JSON files for version control:
```bash theme={null}
# Export component spec
figma_get_component --format reconstruction > button-v1.json
# Track changes over time
git add button-v1.json
git commit -m "Update button component"
```
### 2. Component Migration
Migrate components between files or projects:
```javascript theme={null}
// Export from source file
const sourceSpec = await figma_get_component({
fileUrl: 'https://figma.com/design/source',
nodeId: '123:456',
format: 'reconstruction'
});
// Import to target file using Figma Component Reconstructor plugin
// Use sourceSpec.spec with the plugin
```
### 3. Programmatic Component Generation
Generate components from code or design systems:
```javascript theme={null}
// Generate button variants programmatically
const variants = ['primary', 'secondary', 'tertiary'];
const sizes = ['small', 'medium', 'large'];
for (const variant of variants) {
for (const size of sizes) {
const spec = generateButtonSpec(variant, size);
// Use spec with Figma Component Reconstructor plugin
}
}
```
### 4. Design System Synchronization
Keep design systems in sync between tools:
```javascript theme={null}
// Export design system components
const components = ['Button', 'Input', 'Card', 'Badge'];
const specs = {};
for (const component of components) {
specs[component] = await figma_get_component({
nodeId: componentIds[component],
format: 'reconstruction'
});
}
// Store or sync with external design system
await designSystem.sync(specs);
```
## Comparison: Metadata vs Reconstruction
| Feature | Metadata Format | Reconstruction Format |
| - | - | - |
| **Purpose** | Documentation, references | Programmatic creation |
| **Enrichment** | ✅ Design tokens, quality metrics | ❌ Not applicable |
| **File Size** | Larger (includes metadata) | Smaller (spec only) |
| **Color Format** | Various formats | Normalized 0-1 RGB |
| **Validation** | ❌ Not validated | ✅ Validated against plugin |
| **Use With** | Style guides, docs | Component Reconstructor plugin |
| **Best For** | Understanding, documenting | Building, migrating |
## Limitations
### Current Limitations
1. **Font Loading**: TEXT nodes may require font availability in target file
2. **Image References**: IMAGE fills reference images by URL (may need re-uploading)
3. **Plugin Data**: Custom plugin data is not included in reconstruction spec
4. **Complex Vectors**: Complex vector paths may lose some detail
5. **Instances**: INSTANCE nodes reference component IDs (must exist in target)
### Best Practices
* ✅ Test reconstruction with simple shapes first (RECTANGLE, ELLIPSE)
* ✅ Verify color values are in 0-1 range
* ✅ Check validation output before using spec
* ✅ Handle COMPONENT\_SET children appropriately
* ✅ Ensure fonts are available when reconstructing TEXT nodes
* ✅ Store specs in version control for tracking changes
## Examples
### Simple Shape
```javascript theme={null}
// Export a simple rectangle
const rect = await figma_get_component({
nodeId: '1:2',
format: 'reconstruction'
});
// Output spec
{
"name": "Background",
"type": "RECTANGLE",
"width": 200,
"height": 100,
"x": 0,
"y": 0,
"fills": [{
"type": "SOLID",
"color": { "r": 0.95, "g": 0.95, "b": 0.95, "a": 1 },
"opacity": 1,
"visible": true
}],
"cornerRadius": 8
}
```
### Auto-Layout Frame
```javascript theme={null}
// Export a frame with auto-layout
const frame = await figma_get_component({
nodeId: '2:3',
format: 'reconstruction'
});
// Output spec
{
"name": "Card",
"type": "FRAME",
"width": 320,
"height": 200,
"layoutMode": "VERTICAL",
"paddingTop": 16,
"paddingBottom": 16,
"paddingLeft": 16,
"paddingRight": 16,
"itemSpacing": 12,
"primaryAxisAlignItems": "MIN",
"counterAxisAlignItems": "CENTER",
"fills": [{
"type": "SOLID",
"color": { "r": 1, "g": 1, "b": 1, "a": 1 },
"opacity": 1,
"visible": true
}],
"effects": [{
"type": "DROP_SHADOW",
"color": { "r": 0, "g": 0, "b": 0, "a": 0.1 },
"offset": { "x": 0, "y": 2 },
"radius": 8,
"visible": true
}],
"children": [...]
}
```
## Support
For issues or questions about the reconstruction format:
1. Check validation errors in the response
2. Verify node types are supported
3. Ensure color values are in 0-1 range
4. Review [Figma Component Reconstructor plugin documentation](https://github.com/southleft/figma-console-mcp)
5. [Open an issue](https://github.com/southleft/figma-console-mcp/issues) with example spec
## Future Enhancements
Planned improvements:
* [ ] Support for variant property extraction
* [ ] Advanced vector path reconstruction
* [ ] Image embedding options
* [ ] Component property definitions
* [ ] Instance overrides support
* [ ] Batch export for multiple components
# Security & Privacy
Source: https://docs.figma-console-mcp.southleft.com/security
Security architecture, data handling, and compliance information
Figma Console MCP is designed with security as a priority. The project is **fully open source** (MIT licensed), allowing complete code auditing by security teams.
## Architecture Security
### Deployment Modes
**Recommended for security-sensitive environments**
* Runs entirely on localhost via stdio
* Zero external network calls
* All communication stays local
**For browser-based MCP clients**
* SSE transport via Cloudflare Workers
* OAuth tokens handled server-side
* All traffic encrypted (HTTPS)
### Data Handling
| Aspect | Details |
| - | - |
| **Data Storage** | None. No design data is persisted or cached to disk. |
| **Telemetry** | None. No analytics, tracking, or usage data collection. |
| **Logging** | Local only. Logs stay on your machine. |
| **Credentials** | Stored in your local MCP config, never transmitted to third parties. |
## Authentication
Figma Console MCP uses **Figma's native authentication**:
* Generated in Figma account settings
* Stored locally in your MCP client config
* Never transmitted except to `api.figma.com`
* Scoped permissions based on token configuration
* Uses Figma's official OAuth 2.0 flow
* Tokens managed via Figma's authorization servers
* No custom credential handling
## Code Execution (`figma_execute`)
The `figma_execute` tool runs JavaScript in Figma's plugin context:
Code runs in Figma's **plugin sandbox**, not your system. It cannot access your filesystem, network, or other applications.
**Sandbox limitations:**
* No filesystem access
* No network access outside Figma's plugin APIs
* Cannot access other browser tabs or system resources
* Can only modify the currently open Figma file
**Mitigations:**
* Desktop Bridge must be manually started
* All execution is user-initiated
* Changes covered by Figma's version history
## Data Access Scope
| Data Type | Access |
| - | - |
| Variables/Tokens | Read |
| Components | Read |
| Styles | Read |
| File Structure | Read |
| Console Logs | Read |
| Design Modifications | Write (via Desktop Bridge) |
* Your filesystem
* Other applications
* Browser data
* Network resources outside Figma
* Other Figma files (only current file)
## Network Security
All network communication is limited to:
* `api.figma.com` — Figma's official REST API (HTTPS)
* `localhost:9223–9232` — WebSocket Bridge (Desktop Bridge Plugin communication, port range for multi-instance support)
* `*.workers.dev` — Remote mode only (HTTPS)
### WebSocket Bridge Security
* **Localhost-only binding** — The WebSocket server binds to `localhost` only, not accessible from external networks
* **No authentication required** — Since it's localhost-only, the attack surface is limited to local processes
* **Request/response correlation** — Each command uses a unique correlation ID to prevent response confusion
* **Per-file isolation** — Multiple connected Figma files maintain independent state (selection, changes, console logs)
**No external dependencies at runtime** — No third-party analytics, CDNs, or external API calls beyond Figma.
## Vendor Trust & Compliance
### Vendor Identity
Figma Console MCP is built and maintained by **Southleft, LLC**. For security or legal inquiries that require a direct contact (vendor questionnaires, DPAs, procurement reviews), email **[info@southleft.com](mailto:info@southleft.com)**. For vulnerability reports, prefer the [private security advisory](https://github.com/southleft/figma-console-mcp/security/advisories/new) flow.
### Formal Attestations
Southleft does **not currently hold SOC 2, ISO 27001, or equivalent third-party attestations** for Figma Console MCP. The product is intentionally designed so that — particularly in Local mode — there is no vendor-side data processing that would require such attestations:
* No Southleft-hosted service in the data path
* No data persistence, telemetry, or analytics
* No accounts, no user database, no logs leaving your machine
The complete source is MIT-licensed and available for audit on [GitHub](https://github.com/southleft/figma-console-mcp). Releases are published to npm as [`figma-console-mcp`](https://www.npmjs.com/package/figma-console-mcp).
### Data Processing & DPA
| Mode | Southleft's Role | DPA Applicability |
| - | - | - |
| **Local Mode** | Not a data processor. Southleft has no access to design data, credentials, or user information. All traffic is between your machine and Figma. | A DPA is not applicable — Southleft does not receive or process customer data. |
| **Remote Mode** | Operates the Cloudflare Worker that brokers OAuth and proxies requests to Figma. No design data is persisted. | A DPA can be provided on request. Email [info@southleft.com](mailto:info@southleft.com). |
### Sub-processors
| Mode | Sub-processors |
| - | - |
| **Local Mode** | None. |
| **Remote Mode** | Cloudflare (Workers hosting, traffic transit), Figma (authentication and design API). |
Figma is always in scope as the upstream platform regardless of mode, since Figma Console MCP is a client to the Figma API.
### Compliance Posture
| Standard | Status |
| - | - |
| **SOC 2 / ISO 27001** | Not currently attested. Minimal surface in Local mode (no vendor-side data storage or processing). |
| **GDPR** | No personal data collected or processed by Southleft. Customers remain controllers of any data they choose to send to Figma via the tool. |
| **HIPAA** | Not applicable. The product is not designed for or marketed to handle PHI. |
## Enterprise Considerations
### Recommended Enterprise Setup
Deploy with stdio transport for zero external network calls
Run your own Cloudflare Worker instance. See [Self-Hosting Guide](/self-hosting).
Only `api.figma.com` needs network access
Complete source available on [GitHub](https://github.com/southleft/figma-console-mcp)
## Vulnerability Reporting
To report a security vulnerability:
1. Open a [private security advisory](https://github.com/southleft/figma-console-mcp/security/advisories/new) on GitHub
2. Include steps to reproduce and potential impact
3. We aim to respond within 48 hours
Please use GitHub's private security advisory feature rather than public issues.
## Security Checklist
* Open source and auditable (MIT license)
* No data persistence or storage
* No telemetry or analytics
* Platform-native authentication (Figma OAuth/PATs)
* Code execution sandboxed in Figma plugin environment
* Local-only deployment option available
* All network traffic encrypted (HTTPS)
* No third-party runtime dependencies
## Questions?
For security inquiries, open a [GitHub Discussion](https://github.com/southleft/figma-console-mcp/discussions) or use the [private security advisory](https://github.com/southleft/figma-console-mcp/security/advisories/new) feature for sensitive matters.
# Self-Hosting
Source: https://docs.figma-console-mcp.southleft.com/self-hosting
Deploy your own instance of Figma Console MCP on Cloudflare Workers for enterprise requirements or custom configurations.
# Self-Hosting Guide
Deploy your own instance of Figma Console MCP on Cloudflare Workers.
## Why Self-Host?
**Use the public server** (`https://figma-console-mcp.southleft.com`) for most use cases.
**Self-host when:**
* You need guaranteed uptime/SLA
* You want custom rate limits
* You need enterprise security/compliance
* You want to modify the code
* You're processing sensitive design data
## Quick Deploy
[](https://deploy.workers.cloudflare.com/?url=https://github.com/southleft/figma-console-mcp)
Or via CLI:
```bash theme={null}
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run deploy
```
## Prerequisites
1. **Cloudflare Account** (free or paid)
* Sign up at [https://dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)
2. **Wrangler CLI** (installed automatically via `npm install`)
* Cloudflare's deployment tool
3. **Browser Rendering API Access** (required for cloud-mode console/screenshot/navigate tools)
* **Free tier:** 10 minutes/day, 3 concurrent browsers
* **Paid tier:** 10 hours/month, then \$0.09/browser hour
* Automatically available on Workers
4. **Figma OAuth App** (for per-user authentication)
* Create one at [https://www.figma.com/developers/apps](https://www.figma.com/developers/apps)
* Set `FIGMA_OAUTH_CLIENT_ID` and `FIGMA_OAUTH_CLIENT_SECRET` as Wrangler secrets
## Step-by-Step Deployment
### 1. Clone and Install
```bash theme={null}
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
```
### 2. Authenticate Wrangler
```bash theme={null}
npx wrangler login
```
This opens a browser to authenticate with Cloudflare.
### 3. Configure Your Deployment
Edit `wrangler.jsonc` (optional):
```jsonc theme={null}
{
"name": "figma-console-mcp", // Change to your preferred name
"main": "dist/index.js",
"compatibility_date": "2024-01-01",
"browser": {
"binding": "BROWSER"
},
"limits": {
"cpu_ms": 30000 // Adjust if needed
}
}
```
### 4. Set Environment Variables
#### Required: Figma Access Token
```bash theme={null}
npx wrangler secret put FIGMA_ACCESS_TOKEN
# Paste your token when prompted
```
Get your token at: [https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens)
#### Optional: Custom Configuration
```bash theme={null}
# Log level (default: info)
npx wrangler secret put LOG_LEVEL
# Enter: trace, debug, info, warn, error, or fatal
# Browser timeout (default: 120000ms)
npx wrangler secret put BROWSER_TIMEOUT
# Enter milliseconds
```
### 5. Build and Deploy
```bash theme={null}
# Build for production
npm run build:cloudflare
# Deploy to Cloudflare Workers
npm run deploy
```
Expected output:
```
( Built successfully!
Uploading...
( Deployment complete!
https://figma-console-mcp..workers.dev
```
### 6. Test Your Deployment
```bash theme={null}
# Health check
curl https://figma-console-mcp..workers.dev/health
# Should return:
{
"status": "healthy",
"service": "Figma Console MCP",
"version": "1.25.0",
"endpoints": {
"mcp": ["/sse", "/mcp"],
"oauth_mcp_spec": ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],
"oauth_legacy": ["/oauth/authorize", "/oauth/callback"],
"utility": ["/health"]
},
"oauth_configured": true
}
```
### 7. Configure Your MCP Client
Update your AI client config to use your instance:
**Claude Desktop:**
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["mcp-remote", "https://figma-console-mcp..workers.dev/sse"]
}
}
}
```
**Important:** Replace `` with your actual Cloudflare Workers subdomain.
***
## Custom Domain (Optional)
### 1. Add Custom Domain in Cloudflare Dashboard
1. Go to Workers & Pages � figma-console-mcp
2. Click "Custom Domains"
3. Click "Add Custom Domain"
4. Enter your domain (e.g., `mcp.example.com`)
5. Cloudflare handles DNS automatically
### 2. Update MCP Client Config
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.example.com/sse"]
}
}
}
```
***
## Environment Configuration
### All Available Secrets
Set these via `npx wrangler secret put SECRET_NAME`:
| Secret | Required | Default | Description |
| - | - | - | - |
| `FIGMA_ACCESS_TOKEN` | Yes | - | Your Figma API token |
| `LOG_LEVEL` | No | `info` | Logging verbosity (trace/debug/info/warn/error/fatal) |
| `BROWSER_TIMEOUT` | No | `120000` | Browser operation timeout (ms) |
| `MAX_CONSOLE_LOGS` | No | `1000` | Max console logs to buffer |
### Setting Secrets
```bash theme={null}
# Interactive (recommended)
npx wrangler secret put FIGMA_ACCESS_TOKEN
# Via file (less secure)
echo "figd_your_token" | npx wrangler secret put FIGMA_ACCESS_TOKEN
```
### Viewing Secrets
```bash theme={null}
# List all secrets (values hidden)
npx wrangler secret list
```
### Deleting Secrets
```bash theme={null}
npx wrangler secret delete SECRET_NAME
```
***
## Monitoring & Logs
### Real-Time Logs
```bash theme={null}
# Tail production logs
npx wrangler tail
# Filter for errors
npx wrangler tail --format pretty | grep ERROR
# Filter by level
npx wrangler tail --status error
```
### Analytics
View analytics in Cloudflare Dashboard:
1. Go to Workers & Pages � figma-console-mcp
2. Click "Analytics" tab
3. See:
* Request count
* Error rate
* CPU time used
* Duration percentiles
***
## Costs
### Browser Rendering API
The cloud-mode console/screenshot/navigate tools launch a headless browser via Cloudflare's Browser Rendering API.
* **Free Tier:** 10 minutes/day, 3 concurrent browsers
* **Paid Tier:** 10 hours/month included, then \$0.09/browser hour
### Workers + Durable Objects
The deployment also uses Workers, two Durable Object classes (the MCP session and the plugin relay), and two KV namespaces for OAuth state.
* **Workers Free Tier:** 100,000 requests/day — fine for personal use.
* **Workers Paid Tier (\$5/month):** 10 million requests/month, plus Durable Objects + KV included.
**Estimated monthly cost for typical usage:**
* Solo developer: **\$0** (free tier)
* Small team (5 people): **\$5–15/month**
* Medium team (20 people): **\$20–50/month**
***
## Updating Your Deployment
### Update Code
```bash theme={null}
cd figma-console-mcp
git pull origin main
npm install
npm run build:cloudflare
npm run deploy
```
### Rollback to Previous Version
```bash theme={null}
npx wrangler rollback
```
### View Deployment History
```bash theme={null}
npx wrangler deployments list
```
***
## Security Best Practices
### 1. Protect Your Secrets
* Use `wrangler secret put` (encrypted at rest)
* L Don't commit secrets to git
* L Don't put secrets in `wrangler.jsonc`
### 2. Token Permissions
* Use a dedicated Figma access token for the MCP
* Scope token to minimum required permissions
* Rotate tokens periodically
### 3. Rate Limiting (Advanced)
For rate limiting, use Cloudflare's built-in Rate Limiting rules:
1. Go to Cloudflare Dashboard → **Security** → **WAF** → **Rate limiting rules**
2. Create a rule to limit requests per IP (e.g., 100 requests/minute)
3. Apply to your worker's route
Alternatively, use Cloudflare's **Rate Limiting binding** for programmatic control - see [Cloudflare Rate Limiting docs](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/).
### 4. Access Control (Advanced)
Add authentication:
```typescript theme={null}
// Require API key
const authKey = request.headers.get('X-API-Key');
if (authKey !== env.API_KEY) {
return new Response('Unauthorized', { status: 401 });
}
```
Then set the API key:
```bash theme={null}
npx wrangler secret put API_KEY
```
***
## Troubleshooting
### Deployment Fails
**Error:** "Authentication required"
```bash theme={null}
npx wrangler login
```
**Error:** "Browser Rendering not enabled"
1. Go to Cloudflare Dashboard
2. Workers & Pages → Settings
3. Enable Browser Rendering
4. Try deploying again
**Error:** OAuth secrets missing
1. Confirm `wrangler secret list` shows both `FIGMA_OAUTH_CLIENT_ID` and `FIGMA_OAUTH_CLIENT_SECRET`
2. If missing, set them via `wrangler secret put FIGMA_OAUTH_CLIENT_ID` and re-deploy
### Browser Launch Fails
**Check logs:**
```bash theme={null}
npx wrangler tail --format pretty
```
**Common issues:**
* Browser Rendering API quota exceeded → Upgrade plan
* KV namespace IDs mismatch — verify `wrangler.jsonc` against your account's KV bindings
* Cold start delay — normal, wait and retry
* Plugin relay disconnected — Cloud Mode users need to re-pair the Desktop Bridge plugin
### High Costs
**Check usage:**
```bash theme={null}
npx wrangler metrics --worker figma-console-mcp
```
**Reduce costs:**
* Implement request caching
* Add rate limiting
* Reduce browser timeout
* Close browser sessions faster
***
## Advanced Configuration
### Custom Worker Name
```jsonc theme={null}
// wrangler.jsonc
{
"name": "my-custom-mcp", // Change this
"main": "dist/index.js",
...
}
```
### Multiple Environments
**Production:**
```bash theme={null}
npx wrangler deploy --env production
```
**Staging:**
```bash theme={null}
npx wrangler deploy --env staging
```
**Configure in `wrangler.jsonc`:**
```jsonc theme={null}
{
"name": "figma-console-mcp",
"env": {
"production": {
"name": "figma-console-mcp-prod",
"vars": {
"ENVIRONMENT": "production"
}
},
"staging": {
"name": "figma-console-mcp-staging",
"vars": {
"ENVIRONMENT": "staging"
}
}
}
}
```
### Durable Objects (Persistent Sessions)
For multi-user sessions, enable Durable Objects:
```jsonc theme={null}
// wrangler.jsonc
{
"durable_objects": {
"bindings": [
{
"name": "SESSIONS",
"class_name": "BrowserSession",
"script_name": "figma-console-mcp"
}
]
},
"migrations": [
{
"tag": "v1",
"new_classes": ["BrowserSession"]
}
]
}
```
***
## CI/CD Integration
### GitHub Actions
Create `.github/workflows/deploy.yml`:
```yaml theme={null}
name: Deploy to Cloudflare Workers
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci
- run: npm run build:cloudflare
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
```
Set secrets in GitHub:
* `CLOUDFLARE_API_TOKEN`
* `CLOUDFLARE_ACCOUNT_ID`
***
## Support
For self-hosting issues:
* \=� [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
* \=� [GitHub Discussions](https://github.com/southleft/figma-console-mcp/discussions)
* \= [Report Issues](https://github.com/southleft/figma-console-mcp/issues)
For Cloudflare-specific issues:
* [Cloudflare Community](https://community.cloudflare.com/)
* [Cloudflare Support](https://support.cloudflare.com/)
# Setup Guide
Source: https://docs.figma-console-mcp.southleft.com/setup
Complete setup instructions for connecting Figma Console MCP to Claude Desktop, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, and other AI clients.
# Figma Console MCP - Setup Guide
Complete setup instructions for connecting Figma Console MCP to various AI clients including Claude Desktop, OpenAI Codex, GitHub Copilot (VS Code), Cursor, Windsurf, and more.
***
## 🎯 Choose Your Setup
**First, decide what you want to do:**
| I want to... | Setup Method | Time |
| - | - | - |
| **Create, modify, and develop with AI** | [NPX Setup](#-npx-setup-recommended) (Recommended) | \~10 min |
| **Design from Claude.ai, v0, Replit, or Lovable** | [Cloud Mode](#-cloud-mode-web-ai-clients) | \~5 min |
| **Full capabilities with manual update control** | [Local Git Setup](#-local-git-setup-alternative) | \~15 min |
| **Set up with OpenAI Codex** (GUI config) | [Codex Setup](#-openai-codex) | \~5 min |
| **Just explore my design data** (read-only) | [Remote Mode](#-remote-mode-read-only-exploration) | \~2 min |
### ⚠️ Important: Capability Differences
| Capability | NPX / Local Git | Cloud Mode | Remote (read-only) |
| - | - | - | - |
| Read design data | ✅ | ✅ | ✅ |
| **Create components & frames** | ✅ | ✅ | ❌ |
| **Edit existing designs** | ✅ | ✅ | ❌ |
| **Manage design tokens/variables** | ✅ | ✅ | ❌ |
| Screenshot validation | ✅ | ✅ | ✅ |
| Desktop Bridge plugin | ✅ | ✅ (required) | ❌ |
| Variables without Enterprise | ✅ | ✅ | ❌ |
| Real-time selection/change tracking | ✅ | ❌ | ❌ |
| Console log streaming | ✅ | ❌ | ❌ |
| Codebase → design system extraction (`figma_ds_*`) | ✅ | ❌ | ❌ |
| Requires Node.js | Yes | No | No |
| **Total tools available** | **121** | **96** after pairing | Read-only subset |
> **Bottom line:** Remote mode is **read-only** until you pair the plugin. Cloud Mode adds **write access** (96 tools) without Node.js. Local (NPX/Git) has **everything** (121 tools) including real-time monitoring.
***
## 🎓 Community Setup Guides
New to MCP servers, JSON configs, and terminal commands? These designer-friendly guides walk through the full NPX setup process step by step — created by designers, for designers.
### Joey Banks — Video Walkthrough
[Joey Banks](https://www.linkedin.com/in/joeyabanks) walks through setting up Figma Console MCP and using it to programmatically create 242 color swatches with linked variables, hex values, and RGB info — a task that would take hours manually.
> *"This to me is incredible. This is such an awesome way to visualize all of the colors or the crayons that we have to work with."* — Joey Banks
[View on LinkedIn →](https://www.linkedin.com/posts/joeyabanks_if-youve-been-curious-about-getting-started-activity-7430645064974106624-cRk6)
### Sergei Zhukov — Designer's Installation Guide
[Sergei Zhukov](https://www.linkedin.com/in/friendlyunit) created a comprehensive 17-page guide covering the entire setup process — from installing Homebrew and Node.js to configuring Claude Desktop and the Desktop Bridge Plugin. Includes pro tips on building design library context and creating automation workflows.
> *"Automate routine. Craft exceptional."* — Sergei Zhukov
[View on Figma Community →](https://www.figma.com/community/file/1606560040358762787/figma-mcp-console-setup-guide) · [View on LinkedIn →](https://www.linkedin.com/posts/friendlyunit_claude-figma-console-mcp-designers-guide-activity-7430399317426720768-KiBy)
Sergei also built [Design Agent Lab](https://designagentlab.com/), which includes a dedicated [Figma Console MCP skill](https://designagentlab.com/figma-console-mcp) for Claude — an interactive setup assistant that walks you through installation and configuration step by step.
***
## 🚀 NPX Setup (Recommended)
**Best for:** Anyone who wants full AI-assisted design and development capabilities with automatic updates.
**What you get:** All 121 tools including design creation, variable management, component instantiation, design-to-code workflows, and Desktop Bridge plugin support.
### Prerequisites Checklist
Before starting, verify you have:
* [ ] **Node.js 18+** installed — Check with `node --version` ([Download](https://nodejs.org))
* [ ] **Figma Desktop** installed (not just the web app)
* [ ] **An MCP client** installed (Claude Desktop, Claude Code, Cursor, Windsurf, etc.)
### Step 1: Get Your Figma Token (\~2 min)
1. Go to [Manage personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) in Figma Help
2. Follow the steps to **create a new personal access token**
3. Enter description: `Figma Console MCP`
4. **Set the following scopes:**
| Scope | Access | Why |
| - | - | - |
| **File content** | ✅ Read only | Read design data, components, styles, and render images |
| **Variables** | ✅ Read only | Read design tokens/variables (Enterprise plans only) |
| **Comments** | ✅ Read and write | Read and post comments on files |
> 💡 **No other scopes are needed.** Leave Webhooks, Dev resources, and Library analytics as "No access".
5. Click **"Generate token"**
6. **Copy the token immediately** — you won't see it again!
> 💡 Your token starts with `figd_` — if it doesn't, something went wrong.
### Step 2: Configure Your MCP Client (\~3 min)
> 💡 **Using OpenAI Codex?** Skip to the dedicated [Codex setup section](#-openai-codex) — it uses a graphical interface instead of JSON config files.
#### Claude Code (CLI)
**Option A: CLI command (quickest)**
```bash theme={null}
claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
```
**Option B: Edit the config file**
If you prefer editing the JSON config file directly:
* **macOS / Linux:** `~/.claude.json`
* **Windows:** `%USERPROFILE%\.claude.json`
Add the following to your `~/.claude.json` (create the file if it doesn't exist):
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "figma-console-mcp@latest"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}
```
> 💡 If `~/.claude.json` already exists with other MCP servers, just add the `"figma-console"` entry inside the existing `"mcpServers"` object.
#### Cursor / Windsurf / Other MCP Clients
Find your client's MCP config file and add:
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "figma-console-mcp@latest"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}
```
#### Claude Desktop
1. Open Claude Desktop
2. Go to **Settings** → **Developer** → **Edit Config** (or manually edit the config file)
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
3. Add the same JSON configuration shown above
4. **Save the file**
### Step 3: Connect to Figma Desktop (\~2 min)
#### Install the Desktop Bridge Plugin
The Desktop Bridge Plugin connects via WebSocket — no special Figma launch flags needed, and it persists across Figma restarts.
> **Stable import path:** The MCP server automatically copies plugin files to `~/.figma-console-mcp/plugin/` on startup. Import from this path — it never changes between npm updates.
1. **Open Figma Desktop** (normal launch, no special flags)
2. In Figma, go to **Plugins** → **Development** → **Import plugin from manifest...**
3. Navigate to `~/.figma-console-mcp/plugin/manifest.json` and select it
4. Click **"Open"** — the plugin appears in your Development plugins list
5. **Run the plugin** in your Figma file (Plugins → Development → Figma Desktop Bridge)
6. The plugin scans ports 9223–9232 on launch, connects to the first available MCP server, and shows `Local · ready` (or `Cloud · ready`, or `Local + Cloud · ready` if you also pair to cloud) in its status pill.
> **About plugin updates.** Figma caches plugin files (`code.js` and `ui.html`) at the application level. The MCP server keeps the stable path at `~/.figma-console-mcp/plugin/` in sync with the running build on every startup, but Figma uses its cached copy until you re-import.
>
> **Re-importing is *required* only when the release notes call it out** (typically when the plugin adds a new method the server needs — e.g. v1.22.4 and v1.10.0). The plugin files last changed in v1.39.0; if your imported plugin predates that, re-import once. The plugin shows an update banner when the server bundles a newer plugin than the one running. For wire-compatible upgrades, re-importing is optional and only refreshes plugin-side cosmetic touches (status-pill copy, `pluginVersion` reporting). When you do re-import: Plugins → Manage plugins → re-import `~/.figma-console-mcp/plugin/manifest.json`.
> **Alternative path:** If `~/.figma-console-mcp/plugin/` doesn't exist yet (first run), you can find the path by running `npx figma-console-mcp@latest --print-path` or checking the `pluginPath` field in `figma_get_status`.
**📖 [Desktop Bridge Plugin Documentation](https://github.com/southleft/figma-console-mcp/tree/main/figma-desktop-bridge)**
#### Multi-Instance / Port Conflicts
Multiple MCP clients (e.g., Claude Desktop Chat + Code tabs, Claude + Cursor) are handled automatically:
* Each MCP server claims the next available port in the range 9223–9232
* The plugin connects to **all** active servers simultaneously
* Orphaned server processes from closed tabs are automatically detected and terminated on startup
* No manual port management needed (the plugin scans the whole range automatically)
### Step 4: Restart Your MCP Client (\~1 min)
1. **Restart your MCP client** (quit and reopen Claude Code, Cursor, Windsurf, Claude Desktop, etc.)
2. Verify the MCP server is connected (e.g., in Claude Desktop look for the 🔌 icon showing "figma-console: connected")
### Step 5: Test It! (\~2 min)
Try these prompts to verify everything works:
```
Check Figma status
```
→ Should show connection status with active WebSocket transport
```
Search for button components
```
→ Should return component results from your open Figma file
```
Create a simple frame with a blue background
```
→ Should create a frame in your Figma file (this confirms write access!)
**🎉 You're all set!** You now have full AI-assisted design capabilities.
***
## 🔧 Local Git Setup (Alternative)
**Best for:** Users who want more control over when updates happen, or developers who want to contribute to the project.
**What you get:** Same 121 tools as NPX. Updates are manual — you pull and rebuild when you're ready.
### Prerequisites
* [ ] Node.js 18+ installed
* [ ] Git installed
* [ ] Figma Desktop installed
* [ ] An MCP client installed (Claude Desktop, Claude Code, Cursor, Windsurf, etc.)
### Step 1: Clone and Build
```bash theme={null}
# Clone the repository
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
# Install dependencies
npm install
# Build for local mode
npm run build:local
```
### Step 2: Get Figma Token
Same as [NPX Step 1](#step-1-get-your-figma-token-2-min) above.
### Step 3: Configure Your MCP Client
#### Claude Code (CLI)
**Option A: CLI command (quickest)**
```bash theme={null}
claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- node /absolute/path/to/figma-console-mcp/dist/local.js
```
**Option B: Edit the config file**
* **macOS / Linux:** `~/.claude.json`
* **Windows:** `%USERPROFILE%\.claude.json`
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "node",
"args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}
```
#### Other MCP Clients (Cursor, Windsurf, Claude Desktop, etc.)
Edit your client's MCP config file:
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "node",
"args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}
```
**Important:**
* Replace `/absolute/path/to/figma-console-mcp` with the actual path where you cloned the repo
* Use forward slashes `/` even on Windows
### Step 4: Connect to Figma Desktop
Same as [NPX Step 3](#step-3-connect-to-figma-desktop-2-min) above — install the Desktop Bridge Plugin.
### Step 5: Restart Your MCP Client and Test
Same as [NPX Steps 4 & 5](#step-4-restart-your-mcp-client-1-min) above.
### Updating
To get the latest changes:
```bash theme={null}
cd figma-console-mcp
git pull
npm install
npm run build:local
```
Then restart Claude Desktop.
***
## ☁️ Cloud Mode (Web AI Clients)
**Best for:** Claude.ai, v0, Replit, Lovable, and any MCP-capable web platform that needs to create and modify Figma designs.
**What you get:** 96 tools — full write access (create frames, components, variables, edit designs) plus REST API reads, design system extraction, comments, version history, slides, FigJam, and annotations. This is Remote Mode upgraded with the Cloud Write Relay.
**What you don't get vs Local:** Real-time selection tracking, document change monitoring, and console log streaming (these require a local WebSocket connection).
### Prerequisites
* [ ] **Figma Personal Access Token** — [Create one here](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) (starts with `figd_`)
* [ ] **Figma Desktop** with the Desktop Bridge plugin installed and running in your file
* [ ] A web AI client that supports MCP (Claude.ai, Lovable, v0, Replit, etc.)
> No Node.js required. The relay runs entirely in Cloudflare Workers.
### Step 1: Add the MCP Connector to Your Platform (\~1 min)
Add the Figma Console MCP endpoint to your AI platform's MCP settings:
**Endpoint URL:** `https://figma-console-mcp.southleft.com/mcp`
**Authentication:** Your Figma Personal Access Token as a Bearer token
How to add this depends on your platform:
| Platform | Where to Add |
| - | - |
| **Claude.ai** | Settings → Connectors → Add Custom Connector → Name: `Figma Console` / URL: `https://figma-console-mcp.southleft.com/mcp` |
| **Lovable** | Project Settings → Integrations → Add MCP Server → paste the URL and add your Figma PAT as Bearer token |
| **v0** | Settings → MCP Servers → Add Server → Streamable HTTP → paste URL → select **Bearer** auth → paste your Figma PAT (not OAuth) |
| **Replit** | Tools → MCP → Add Server → paste URL, set Authorization header to `Bearer figd_YOUR_TOKEN` |
| **Other clients** | Look for "Add MCP Server", "Custom Tool", or "Integrations" in your platform's settings. Provide the URL above and your Figma PAT as the Bearer token. |
### Step 2: Run the Desktop Bridge Plugin in Figma (\~30 sec)
1. Open **Figma Desktop** and navigate to your design file
2. Run the plugin: **Plugins → Development → Figma Desktop Bridge**
3. You should see the status pill showing the active transport: `Local · ready`, `Cloud · ready`, or `Local + Cloud · ready` (when paired with both)
> **First time?** Import the plugin once: In Figma go to Plugins → Development → Import plugin from manifest → select `~/.figma-console-mcp/plugin/manifest.json`. After future MCP server updates, re-importing is optional — only required when release notes specifically call for it (e.g. when the plugin adds a new method the server needs). Most upgrades stay wire-compatible with the previous plugin.
### Step 3: Pair via Cloud Mode (\~30 sec)
1. **Tell your AI to connect to your Figma plugin** using natural language:
* "Connect to my Figma plugin"
* "Pair with my design file"
* "I want to create designs in Figma"
2. **Your AI generates a 6-character pairing code** (expires in 5 minutes)
3. **In the Desktop Bridge plugin:**
* Toggle **"Cloud Mode"** (the small chevron below the status bar)
* Enter the pairing code
* Click **Connect**
4. **Done.** Your AI now has full write access to the open Figma file through the cloud relay.
### What You Can Do (93 Tools)
* ✅ Create frames, shapes, and components
* ✅ Edit existing designs (resize, reposition, restyle)
* ✅ Create and manage variables on any Figma plan (via Plugin API)
* ✅ Instantiate components and set instance properties
* ✅ Clone, delete, and rename nodes
* ✅ Set fills, strokes, and text content
* ✅ Set image fills on nodes
* ✅ Read design data, take screenshots, extract design systems
### What's Local-Only (Not Available in Cloud Mode)
* ❌ Real-time selection tracking
* ❌ Document change monitoring
* ❌ Console log streaming
* ❌ MCP Apps (Token Browser, Design System Dashboard)
### Tips
* The pairing code expires after **5 minutes** — generate a new one if it times out
* If the connection drops between AI turns, ask your AI to reconnect and enter a fresh code
* The Desktop Bridge plugin must stay running in your Figma file for the relay to work
* Variables work on **any Figma plan** (Free, Pro, Organization) because the relay uses the Plugin API, not the Enterprise REST API
***
## 📡 Remote Mode (Read-Only Exploration)
**Best for:** Quickly evaluating the tool or read-only design data extraction without any plugin setup.
**What you get:** the read-only tools for viewing design data, taking screenshots, reading console logs, and design system extraction.
> **Want write access?** See [Cloud Mode](#-cloud-mode-web-ai-clients) above — same remote endpoint, plus Desktop Bridge pairing for full design creation.
Two remote endpoints are available:
| Endpoint | Transport | Auth | Best For |
| - | - | - | - |
| `/sse` | Server-Sent Events | OAuth 2.1 (automatic) | Claude Desktop, Cursor, Windsurf |
| `/mcp` | Streamable HTTP | Bearer token (your Figma PAT) | Lovable, v0, Replit, any HTTP-capable client |
### Prerequisites
* [ ] Claude Desktop installed (for `/sse`), or an MCP-compatible code generator (for `/mcp`)
* For `/mcp`: A Figma Personal Access Token
### Option A: SSE Endpoint (Claude Desktop, Cursor, Windsurf)
The `/sse` endpoint uses OAuth — authentication happens automatically when you first connect.
**UI-Based Setup (Claude Desktop):**
1. Open Claude Desktop → **Settings** → **Connectors**
2. Click **"Add Custom Connector"**
3. Enter:
* **Name:** `Figma Console (Read-Only)`
* **URL:** `https://figma-console-mcp.southleft.com/sse`
4. Click **"Add"**
5. Done! ✅
**JSON Config:**
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://figma-console-mcp.southleft.com/sse"]
}
}
}
```
### Option B: Streamable HTTP Endpoint (AI Code Generators)
The `/mcp` endpoint accepts your Figma Personal Access Token as a Bearer token — no OAuth flow needed. This is ideal for AI code generators like Lovable, v0, and Replit that support custom MCP servers with Streamable HTTP transport.
**Endpoint:** `https://figma-console-mcp.southleft.com/mcp`
**Authentication:** Pass your Figma PAT as a Bearer token in the `Authorization` header.
**How to connect** depends on the platform — look for "Add MCP Server" or "Custom Tool" in your code generator's settings, provide the URL above, and add your Figma token as the Bearer token.
### What You Can Do (Read-Only)
* ✅ View design data and file structure
* ✅ Read design tokens/variables (Enterprise plan required)
* ✅ Take screenshots
* ✅ Read console logs
* ✅ Get component metadata
* ✅ Extract full design system via `figma_get_design_system_kit`
### What You Cannot Do
* ❌ Create frames, shapes, or components
* ❌ Edit existing designs
* ❌ Create or modify variables
* ❌ Instantiate components
### Upgrading to Write Access
Want to create and modify designs? See [Cloud Mode](#-cloud-mode-web-ai-clients) above — pair the Desktop Bridge plugin and get full write access from the same `/mcp` endpoint.
***
## 🤖 GitHub Copilot (VS Code)
GitHub Copilot supports MCP servers as of VS Code 1.102+.
### Prerequisites
* VS Code 1.102 or later
* GitHub Copilot extension installed and active
* For full capabilities: Node.js 18+ and Figma Personal Access Token
### Quick Setup (CLI)
**Full capabilities (recommended):**
```bash theme={null}
# Create env file for your token
echo "FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE" > ~/.figma-console-mcp.env
# Add the server
code --add-mcp '{"name":"figma-console","command":"npx","args":["-y","figma-console-mcp@latest"],"envFile":"~/.figma-console-mcp.env"}'
```
**Read-only mode:**
```bash theme={null}
code --add-mcp '{"name":"figma-console","type":"sse","url":"https://figma-console-mcp.southleft.com/sse"}'
```
### Manual Configuration
Create `.vscode/mcp.json` in your project:
**Full capabilities:**
```json theme={null}
{
"servers": {
"figma-console": {
"command": "npx",
"args": ["-y", "figma-console-mcp@latest"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
}
}
}
}
```
> **Security Tip:** Use `envFile` instead of inline `env` to keep tokens out of version control.
### Starting the Server
1. Open Command Palette (**Cmd+Shift+P** / **Ctrl+Shift+P**)
2. Run **"MCP: List Servers"**
3. Click on **"figma-console"** to start it
4. VS Code may prompt you to **trust the server** — click Allow
***
## 🧠 OpenAI Codex
OpenAI Codex uses a graphical interface for MCP server configuration instead of JSON files. This makes setup straightforward — just fill in the fields.
### Prerequisites
* [OpenAI Codex desktop app](https://openai.com/codex/get-started/) installed
* Node.js 18+ installed
* Figma Desktop installed
* Figma Personal Access Token ([get one](#step-1-get-your-figma-token-2-min))
### Step 1: Add the MCP Server (\~2 min)
1. Open Codex and go to **Settings** (gear icon in the sidebar)
2. Click **Settings** again in the submenu
3. Select **MCP servers** from the left sidebar
4. Click **"Add MCP Server"** (or create a new server)
5. Fill in the fields:
| Field | Value |
| - | - |
| **Server name** | `Figma Console MCP` (or any name you prefer) |
| **Command to launch** | `npx` |
| **Arguments** | Add two arguments: `-y` and `figma-console-mcp@latest` |
| **Environment variables** | `FIGMA_ACCESS_TOKEN` = `figd_YOUR_TOKEN_HERE` |
| **Environment variables** | `ENABLE_MCP_APPS` = `true` |
6. Click **Save**
Here's what the completed configuration looks like:
> 💡 **Tip:** The Codex UI adds arguments one at a time. Click **"+ Add argument"** after entering `-y` to add the second argument `figma-console-mcp@latest`.
### Step 2: Connect to Figma Desktop
Same as [NPX Step 3](#step-3-connect-to-figma-desktop-2-min) above — install the Desktop Bridge Plugin in Figma.
### Step 3: Test It
Start a new thread in Codex and try:
```
Use the Figma Console connector to check Figma status
```
If the Desktop Bridge plugin isn't running yet, the server will connect but report that Figma Desktop isn't linked. Run the plugin in your Figma file (Plugins → Development → Figma Desktop Bridge) and ask Codex to check again.
### Equivalent JSON Config
For reference, the Codex GUI fields map directly to the [NPX JSON configuration](#step-2-configure-your-mcp-client-3-min) used by other MCP clients like Claude Desktop, Cursor, and Windsurf.
***
## 🛠️ Troubleshooting
### Quick Fixes
| Symptom | Likely Cause | Fix |
| - | - | - |
| "Failed to connect to Figma Desktop" | No transport available | Install Desktop Bridge Plugin and run it in your Figma file |
| "FIGMA\_ACCESS\_TOKEN not configured" | Missing or wrong token | Check token in config, must start with `figd_` |
| "Command not found: node" | Node.js not installed | Install Node.js 18+ from nodejs.org |
| Tools not appearing in MCP client | Config not loaded | Restart your MCP client completely |
| "Port 9223 already in use" | Another MCP instance or orphaned process | Server auto-falls back to 9224–9232. Orphaned processes are auto-cleaned on startup (v1.14.0+). |
| WebSocket unreachable from Docker host | Server bound to localhost | Set `FIGMA_WS_HOST=0.0.0.0` and expose port with `-p 9223:9223` |
| Plugin shows "MCP scanning" | MCP server not running yet | Start/restart your MCP client so the server starts. The plugin retries every few seconds. |
| Plugin shows "No MCP server found" | All retries exhausted | Ensure an MCP client is running. Check for stale processes: `lsof -i :9223-9232 \| grep LISTEN` |
| NPX using old version | Cached package | Use `figma-console-mcp@latest` explicitly |
| Cloud pairing code expired | Code is older than 5 minutes | Ask your AI to generate a new pairing code |
| Cloud connection drops between turns | Relay session ended | Re-pair by asking your AI to reconnect, then enter the new code in the plugin |
| Cloud Mode toggle not showing | Stale cached plugin from before Cloud Mode was added | Re-import manifest from `~/.figma-console-mcp/plugin/manifest.json` to refresh Figma's cached plugin code |
### Node.js Version Issues
**Symptom:** Cryptic errors like "parseArgs not exported from 'node:util'"
**Fix:** You need Node.js 18 or higher.
```bash theme={null}
# Check your version
node --version
# Should show v18.x.x or higher
```
If using **NVM** and having issues, try using the absolute path to Node:
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "/Users/yourname/.nvm/versions/node/v20.10.0/bin/node",
"args": ["-e", "require('figma-console-mcp')"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
}
}
}
}
```
### Claude Code OAuth Issues
> **⚠️ Known Issue:** Claude Code's native `--transport sse` has a bug where OAuth completes but the connection fails. Use `mcp-remote` instead.
**Don't use:**
```bash theme={null}
# This has a known bug
claude mcp add figma-console --transport sse https://figma-console-mcp.southleft.com/sse
```
**Use instead:**
```bash theme={null}
# This works correctly
claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse
```
Or better yet, use the NPX setup for full capabilities:
```bash theme={null}
claude mcp add figma-console -s user -- npx -y figma-console-mcp@latest
```
### Config File Syntax Errors
If Claude Desktop doesn't see your MCP server:
1. **Validate your JSON:** Use a tool like [jsonlint.com](https://jsonlint.com)
2. **Check for common mistakes:**
* Missing commas between properties
* Trailing commas (not allowed in JSON)
* Wrong quote characters (must be `"` not `'` or smart quotes)
3. **Copy the exact config** from this guide — don't retype it
### Still Having Issues?
1. Check the [GitHub Issues](https://github.com/southleft/figma-console-mcp/issues)
2. Ask in [Discussions](https://github.com/southleft/figma-console-mcp/discussions)
3. Include:
* Your setup method (NPX, Local Git, or Remote)
* The exact error message
* Output of `node --version`
* Your MCP client (Claude Desktop, Claude Code, etc.)
***
## Optional: Enable MCP Apps
MCP Apps provide interactive UI experiences like the Token Browser and Design System Dashboard. As of v1.10.0, `ENABLE_MCP_APPS=true` is included in the default configuration examples above.
If you set up before v1.10.0, add `"ENABLE_MCP_APPS": "true"` to the `env` section of your MCP config.
> **Note:** MCP Apps require a client with [ext-apps protocol](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps) support.
***
## Next Steps
1. **Try example prompts:** See [Use Cases](use-cases) for workflow examples
2. **Explore all tools:** See [Tools Reference](tools) for the complete tool list
3. **Learn about the Desktop Bridge plugin:** See [Desktop Bridge README](https://github.com/southleft/figma-console-mcp/tree/main/figma-desktop-bridge) for advanced configuration
***
## Support
* 📖 [Full Documentation](/)
* 🐛 [Report Issues](https://github.com/southleft/figma-console-mcp/issues)
* 💬 [Discussions](https://github.com/southleft/figma-console-mcp/discussions)
* 📊 [Mode Comparison](mode-comparison)
# Figma Slides Support
Source: https://docs.figma-console-mcp.southleft.com/slides
AI agents can now manage entire presentations — create slides, set transitions, reorder decks, and add content. A complete guide to the 15 Slides tools.
# AI-Powered Presentations
Figma Console MCP now extends beyond Design files and FigJam boards into **Figma Slides** — Figma's presentation tool built directly on the design canvas. Teams use it for pitch decks, design reviews, sprint demos, conference talks, and stakeholder presentations.
This is not a read-only integration. Your AI assistant can **create and manage entire presentations** — adding slides, setting transitions, reordering decks, and placing content — turning Figma Slides into a programmable stage for AI-assisted storytelling.
***
## What is Figma Slides?
Figma Slides is Figma's native presentation tool, built on the same canvas you already use for design work. Unlike standalone slide apps, your presentations live alongside your design files, share the same components and styles, and update in real time as your design system evolves. Teams use it for everything from internal sprint demos to polished client-facing pitch decks.
With Figma Console MCP, every part of your presentation is now accessible to AI agents.
***
## What's Now Possible
AI assistants connected through Figma Console MCP can now manage presentations programmatically:
Create new slides, duplicate existing ones, delete slides you no longer need, and reorder your deck — all through natural language prompts.
Retrieve the full content of any slide — text, shapes, frames, the entire node tree — so your AI assistant can analyze, summarize, or audit your presentation.
Apply any of 22 transition styles with 8 easing curves and configurable duration. Set a consistent feel across the whole deck or fine-tune individual slides.
Skip slides that are not ready, navigate between slides, and switch between grid and single-slide view — all without touching the mouse.
Place text and shapes directly onto slides. Quickly scaffold title cards, section dividers, and content placeholders.
Read the 2D slide grid layout to understand how your deck is structured, then switch to grid view for a bird's-eye overview.
***
## The 15 Slides Tools
Every tool is available in both **Local Mode** and **Cloud Mode**.
### Read Tools
| Tool | What It Does |
| - | - |
| `figma_list_slides` | List all slides in the presentation with their order, names, and skip status |
| `figma_get_slide_content` | Read the full content of a specific slide — text, shapes, frames, everything |
| `figma_get_slide_grid` | Read the 2D grid layout to understand the spatial arrangement of your deck |
| `figma_get_slide_transition` | Check what transition style, easing, and duration are set on a slide |
| `figma_get_focused_slide` | See which slide is currently selected in the editor |
### Write Tools
| Tool | What It Does |
| - | - |
| `figma_create_slide` | Add a new blank slide to the presentation |
| `figma_delete_slide` | Remove a slide from the deck |
| `figma_duplicate_slide` | Copy an existing slide, preserving all its content and formatting |
| `figma_reorder_slides` | Move slides to new positions in the deck |
| `figma_set_slide_transition` | Apply a transition style with easing and duration to a slide |
| `figma_skip_slide` | Mark a slide to be skipped during presentation mode |
| `figma_add_text_to_slide` | Add text with custom fonts, colors, alignment, wrapping, and text case |
| `figma_add_shape_to_slide` | Add a shape element to a slide for visual structure |
| `figma_set_slide_background` | Set a slide's background color (creates or updates a full-slide rectangle) |
| `figma_get_text_styles` | Get all local text styles with IDs, font info, and sizes |
### Navigation Tools
| Tool | What It Does |
| - | - |
| `figma_set_slides_view_mode` | Switch between grid view and single-slide view |
| `figma_focus_slide` | Navigate to a specific slide in the editor |
### Transition System
The transition support is comprehensive. You have full control over how each slide enters during a presentation.
**22 Transition Styles:**
| Category | Styles |
| - | - |
| Basic | `NONE`, `DISSOLVE`, `SMART_ANIMATE` |
| Slide In | `SLIDE_FROM_LEFT`, `SLIDE_FROM_RIGHT`, `SLIDE_FROM_TOP`, `SLIDE_FROM_BOTTOM` |
| Push | `PUSH_FROM_LEFT`, `PUSH_FROM_RIGHT`, `PUSH_FROM_TOP`, `PUSH_FROM_BOTTOM` |
| Move In | `MOVE_FROM_LEFT`, `MOVE_FROM_RIGHT`, `MOVE_FROM_TOP`, `MOVE_FROM_BOTTOM` |
| Slide Out | `SLIDE_OUT_TO_LEFT`, `SLIDE_OUT_TO_RIGHT`, `SLIDE_OUT_TO_TOP`, `SLIDE_OUT_TO_BOTTOM` |
| Move Out | `MOVE_OUT_TO_LEFT`, `MOVE_OUT_TO_RIGHT`, `MOVE_OUT_TO_TOP`, `MOVE_OUT_TO_BOTTOM` |
**8 Easing Curves:** `LINEAR`, `EASE_IN`, `EASE_OUT`, `EASE_IN_AND_OUT`, `GENTLE`, `QUICK`, `BOUNCY`, `SLOW`
**Duration:** Configurable from 0.01 to 10 seconds.
`DISSOLVE` with `EASE_IN_AND_OUT` at 0.5 seconds is a clean default for most presentations. `SMART_ANIMATE` works best when consecutive slides share similar elements — Figma automatically animates the differences.
***
## Use Cases
These are real-world scenarios where Slides support transforms your presentation workflow. Each example includes a prompt you can try with your AI assistant.
### Presentation Review
Get an instant overview of your deck before the big meeting.
```
List all slides in my presentation and tell me which ones
are skipped. Summarize the overall structure.
```
The AI calls `figma_list_slides` to retrieve the full deck, identifies any skipped slides, and provides a summary so you can verify everything is in order.
### Quick Additions
Need a closing slide? Add it without breaking your flow.
```
Add a new slide at the end with the title "Thank You" in
72px text, centered on the slide.
```
The AI uses `figma_create_slide` to add the slide, then `figma_add_text_to_slide` to place the title — done in seconds.
### Batch Transition Formatting
Set a consistent visual rhythm across your entire presentation in one prompt.
```
Set a DISSOLVE transition on all slides with 0.5 second
duration and EASE_IN_AND_OUT easing.
```
The AI calls `figma_list_slides` to get every slide, then applies `figma_set_slide_transition` to each one. No more clicking through slides one at a time.
### Design Iteration
Quickly create variations for stakeholder review.
```
Duplicate slide 5 and add a shape overlay for the A/B
comparison version.
```
The AI uses `figma_duplicate_slide` to create the copy and `figma_add_shape_to_slide` to place the overlay — keeping your original intact while you explore alternatives.
### Content Audit
Let your AI assistant read through the deck and flag issues.
```
Read slide 3 and tell me what text elements are on it.
Check if there are any placeholder texts that need updating.
```
The AI calls `figma_get_slide_content` to retrieve the full node tree, then analyzes every text element to surface anything that still says "Lorem ipsum" or "Replace me."
### Presentation Prep
Hide unfinished slides before a client presentation without deleting them.
```
Skip slides 8 and 9 — they're not ready for the client
presentation yet.
```
The AI uses `figma_skip_slide` on each slide. They stay in your deck but will not appear during presentation mode. Unskip them later when they are ready.
### Deck Restructuring
Reorder your narrative without dragging slides around manually.
```
Reorder my slides so the conclusion comes before the Q&A
section.
```
The AI calls `figma_list_slides` to understand the current order, identifies the relevant slides, and uses `figma_reorder_slides` to move them into position.
### Navigation and Overview
Switch views to see the big picture or zero in on a specific slide.
```
Switch to grid view so I can see the overall flow of the
presentation.
```
The AI uses `figma_set_slides_view_mode` to switch to grid view, giving you a bird's-eye look at your entire deck layout.
### Checking Animation Settings
Verify how a specific slide will transition before presenting.
```
What transitions are set on my title slide? I want to make
sure it has a clean entrance.
```
The AI calls `figma_get_slide_transition` and reports the transition style, easing curve, and duration — so you know exactly what the audience will see.
### Scaffolding a New Section
Quickly set up the structure for a new part of your presentation.
```
Create 5 new blank slides for our brainstorming section.
Add the title "Brainstorm" to the first one.
```
The AI creates the slides with `figma_create_slide` and adds the section title with `figma_add_text_to_slide`, giving you a clean scaffold to build on.
***
## How It Works
### Editor Type Detection
The Desktop Bridge plugin reports `figma.editorType` when it connects to the MCP server. When the plugin is running inside a Figma Slides presentation, the server automatically makes all 15 Slides tools available. When running in a Figma Design file or FigJam board, the Slides tools are hidden and runtime guards prevent accidental use.
This means there is no configuration toggle or mode switch. The tools appear based on context.
### Same Plugin, New Canvas
Slides support uses the **same Desktop Bridge plugin** you already have installed. There is no separate plugin for Slides. Open any Figma Slides presentation, run the Desktop Bridge plugin, and the Slides tools become available alongside the standard toolset.
### Runtime Safety
If a Slides tool is called while connected to a Figma Design file or FigJam board, it returns a clear error message explaining that Slides tools require a Slides presentation. This prevents accidental misuse and gives the AI assistant enough context to guide you back on track.
### Compatibility
| Mode | Slides Support |
| - | - |
| Local (NPX/Git) | Full support |
| Cloud Mode | Full support |
| Remote (Read-Only) | Not available (requires Desktop Bridge) |
***
## Getting Started
Open any Figma Slides presentation in Figma Desktop. You can create a new presentation from the Figma home screen or open an existing one.
Launch the Desktop Bridge plugin from **Plugins > Development > Figma Desktop Bridge**. The plugin connects to the MCP server and reports that the editor type is Slides.
Start with a simple prompt like *"List all slides in my presentation"* to verify the connection, then move on to more complex workflows like setting transitions, restructuring decks, and adding content.
If you have not set up the Desktop Bridge plugin yet, follow the [Setup Guide](/setup) first. The same plugin installation works for Figma Design files, FigJam boards, and Slides presentations.
***
## Community Contributors
Figma Slides support was inspired by community contributions and merged into the main project:
* **Toni Haidamous** — Authored the original Slides tool design (PR #11) that laid the groundwork for this integration.
Figma Console MCP is open source. If you want to contribute new tools or improvements, visit the [GitHub repository](https://github.com/southleft/figma-console-mcp).
# Tools Reference
Source: https://docs.figma-console-mcp.southleft.com/tools
Complete API reference for all 121 MCP tools, including parameters, return values, and usage examples.
# Available Tools - Detailed Documentation
This guide provides detailed documentation for each tool, including when to use them and best practices.
> **Note:** Local Mode (NPX/Git) provides **121 tools** with full read/write capabilities and real-time monitoring. Remote Mode is **read-only** until paired, and provides **96 tools** (including full write access) when paired with the Desktop Bridge plugin via Cloud Relay. Tools marked "Local" in the table below require Local Mode. Tools marked "Local / Cloud" work in both Local Mode and Cloud Mode (after pairing). Tools marked "All" are listed on every endpoint except Cloud Mode's `/mcp` endpoint, which omits the console, screenshot, navigation, status, and reload tools. Those run a headless browser session that only the `/sse` endpoint keeps open.
## Quick Reference
| Category | Tool | Purpose | Mode |
| - | - | - | - |
| **🧭 Navigation** | `figma_navigate` | Open a Figma URL and start monitoring | All |
| | `figma_get_status` | Check browser and monitoring status | All |
| | `figma_reconnect` | Reconnect to Figma Desktop | Local |
| | `figma_list_open_files` | List files connected via the Desktop Bridge and which one is active | Local |
| | `figma_diagnose` | Plain-language health check: server identity, plugin connection, file, token | Local / Cloud |
| **📋 Console** | `figma_get_console_logs` | Retrieve console logs with filters | All |
| | `figma_watch_console` | Stream logs in real-time | All |
| | `figma_clear_console` | Clear log buffer | All |
| **🔍 Debugging** | `figma_take_screenshot` | Capture UI screenshots | All |
| | `figma_reload_plugin` | Reload current page | All |
| | `figma_capture_screenshot` | Render a node from the plugin runtime (reflects unsaved changes) | Local / Cloud |
| **👁️ Real-Time Awareness** | `figma_get_selection` | Get the nodes currently selected in Figma | Local |
| | `figma_get_design_changes` | Get buffered document-change events | Local |
| **🔁 Token Sync** | `figma_export_tokens` | Export Figma variables to DTCG JSON + CSS (replaces Style Dictionary) | Local / Cloud |
| | `figma_import_tokens` | Push code-side token edits back to Figma (diff-aware merge) | Local / Cloud |
| **🧬 Design System Extraction** | `figma_ds_analyze` | Scan production codebase(s): component inventory, classification, architecture | Local |
| | `figma_ds_extract_tokens` | Mine codebase styling into DTCG tokens with provenance | Local |
| | `figma_ds_scaffold` | Generate the design-system package + token files + showcase docs | Local |
| | `figma_ds_setup_storybook` | Wire a fresh Storybook workshop to the extracted system | Local |
| | `figma_ds_extract_component` | Per-component porting manifest + CSF3 story scaffold | Local |
| | `figma_ds_verify` | Deterministic fidelity evals + Figma round-trip readiness | Local |
| | `figma_ds_status` | Read/record porting progress (persists across sessions) | Local |
| **🎨 Design System** | `figma_get_variables` | Extract design tokens/variables | All |
| | `figma_get_styles` | Get color, text, effect styles | All |
| | `figma_get_component` | Get component data | All |
| | `figma_get_component_for_development` | Component + visual reference | All |
| | `figma_get_component_image` | Just the component image | All |
| | `figma_get_file_data` | File structure with verbosity control | All |
| | `figma_get_file_for_plugin` | File data optimized for plugins | All |
| | `figma_get_design_system_kit` | **Full design system in one call** (tokens, components, styles, visual specs) | All |
| | `figma_audit_design_system_report` | **Scored six-category health audit** with per-finding remediation, chunked drill-down, live-first data | Local |
| | `figma_get_design_system_summary` | Overview of design system | Local |
| | `figma_get_token_values` | Get variable values by mode | Local |
| **✏️ Design Creation** | `figma_execute` | Run Figma Plugin API code | Local / Cloud |
| | `figma_execute_across_files` | **Run the same code in several connected files at once**, concurrently | Local |
| | `figma_create_component_set` | **Create a component set with variants in one call** — axes matrix or existing components | Local / Cloud |
| | `figma_arrange_component_set` | Organize variants with labels | Local / Cloud |
| | `figma_set_description` | Add component descriptions | Local / Cloud |
| **🧩 Slots** | `figma_create_slot` | **Add a slot to a component** (auto-linked SLOT property; variants supported) | Local / Cloud |
| | `figma_get_slots` | List slots on a component, set, or instance | Local / Cloud |
| | `figma_append_to_slot` | **Populate an instance's slot** — clone a node or create content | Local / Cloud |
| | `figma_reset_slot` | Clear a slot's content on an instance | Local / Cloud |
| | `figma_add_slot_property` | Retrofit an existing frame as a slot (manual SLOT binding) | Local / Cloud |
| **🧩 Components** | `figma_search_components` | Find components by name (local + library) | Local |
| | `figma_get_library_components` | Discover components from published libraries | Local |
| | `figma_get_library_component_by_key` | **Resolve any component key to full props + variants + visual specs** — no library URL needed | Local / Cloud |
| | `figma_get_component_details` | Get component details | Local |
| | `figma_instantiate_component` | Create component instance (local + library) | Local / Cloud |
| | `figma_set_instance_properties` | Set TEXT, BOOLEAN, INSTANCE\_SWAP, and VARIANT properties on an instance | Local / Cloud |
| **📚 Shared Library Variables** | `figma_get_library_variables` | List variables from subscribed libraries (no Enterprise plan needed) | Local / Cloud |
| | `figma_import_library_variable` | Import a library variable into the current file | Local / Cloud |
| | `figma_add_component_property` | Add component property | Local / Cloud |
| | `figma_edit_component_property` | Edit component property | Local / Cloud |
| | `figma_delete_component_property` | Remove component property | Local / Cloud |
| **🔧 Variables** | `figma_create_variable_collection` | Create collections with modes | Local / Cloud |
| | `figma_create_variable` | Create new variables | Local / Cloud |
| | `figma_update_variable` | Update variable values | Local / Cloud |
| | `figma_rename_variable` | Rename variables | Local / Cloud |
| | `figma_delete_variable` | Delete variables | Local / Cloud |
| | `figma_delete_variable_collection` | Delete collections | Local / Cloud |
| | `figma_add_mode` | Add modes to collections | Local / Cloud |
| | `figma_rename_mode` | Rename modes | Local / Cloud |
| | `figma_batch_create_variables` | Create up to 100 variables at once | Local / Cloud |
| | `figma_batch_update_variables` | Update up to 100 variables at once | Local / Cloud |
| | `figma_setup_design_tokens` | Create collection + modes + variables atomically | Local / Cloud |
| **🔍 Design-Code Parity** | `figma_check_design_parity` | Compare Figma specs vs code implementation | All |
| | `figma_generate_component_doc` | Generate component documentation from Figma + code, with optional Figma version + git history | All |
| **💬 Comments** | `figma_get_comments` | Get comments on a Figma file | All |
| | `figma_post_comment` | Post a comment, optionally pinned to a node | All |
| | `figma_delete_comment` | Delete a comment by ID | All |
| **📝 Annotations** | `figma_get_annotations` | Read annotations from nodes (with optional child traversal) | Local / Cloud |
| | `figma_set_annotations` | Write or clear annotations (plain text, markdown, pinned properties) | Local / Cloud |
| | `figma_get_annotation_categories` | List available annotation categories | Local / Cloud |
| **🔬 Deep Analysis** | `figma_get_component_for_development_deep` | Unlimited-depth component tree with resolved token names and instance refs | Local / Cloud |
| | `figma_analyze_component_set` | Variant state machine with CSS pseudo-class mappings and cross-variant diffs | Local / Cloud |
| **📐 Node Manipulation** | `figma_resize_node` | Resize a node | Local / Cloud |
| | `figma_move_node` | Move a node | Local / Cloud |
| | `figma_clone_node` | Clone a node | Local / Cloud |
| | `figma_delete_node` | Delete a node | Local / Cloud |
| | `figma_rename_node` | Rename a node | Local / Cloud |
| | `figma_set_text` | Set text content | Local / Cloud |
| | `figma_set_fills` | Set fill colors | Local / Cloud |
| | `figma_set_strokes` | Set stroke colors | Local / Cloud |
| | `figma_create_child` | Create child node | Local / Cloud |
| **🖼️ Image** | `figma_set_image_fill` | Set image fill on nodes | Local / Cloud |
| **🔍 Accessibility** | `figma_lint_design` | 14 WCAG checks with AA/best-practice level tagging | Local / Cloud |
| | `figma_audit_component_accessibility` | Deep component scorecard: states, focus, color-blind simulation | Local / Cloud |
| | `figma_scan_code_accessibility` | Scan HTML with axe-core (104 rules): ARIA, labels, landmarks, semantics | Local |
| **📌 FigJam** | `figjam_create_sticky` | Create a sticky note | Local / Cloud |
| | `figjam_create_stickies` | Batch create up to 200 stickies | Local / Cloud |
| | `figjam_create_connector` | Connect two nodes with optional label | Local / Cloud |
| | `figjam_create_shape_with_text` | Create a labeled shape (diamond, ellipse, etc.) | Local / Cloud |
| | `figjam_create_table` | Create a table with cell data | Local / Cloud |
| | `figjam_create_code_block` | Create a code block | Local / Cloud |
| | `figjam_create_section` | Create a section to group board content | Local / Cloud |
| | `figjam_auto_arrange` | Arrange nodes in grid/row/column layout | Local / Cloud |
| | `figjam_get_board_contents` | Read all content from a FigJam board | Local / Cloud |
| | `figjam_get_connections` | Read the connection graph | Local / Cloud |
| **🎞️ Slides** | `figma_list_slides` | List slides with order, names, and skip status | Local / Cloud |
| | `figma_get_slide_content` | Read a slide's content tree | Local / Cloud |
| | `figma_get_slide_grid` | Read the deck's 2D grid layout | Local / Cloud |
| | `figma_get_slide_transition` | Read a slide's transition | Local / Cloud |
| | `figma_get_focused_slide` | Get the slide focused in single-slide view | Local / Cloud |
| | `figma_create_slide` | Add a blank slide | Local / Cloud |
| | `figma_delete_slide` | Delete a slide | Local / Cloud |
| | `figma_duplicate_slide` | Duplicate a slide with its content | Local / Cloud |
| | `figma_reorder_slides` | Move slides to new positions | Local / Cloud |
| | `figma_set_slide_transition` | Set a slide's transition style, easing, and duration | Local / Cloud |
| | `figma_skip_slide` | Skip or unskip a slide in presentation mode | Local / Cloud |
| | `figma_add_text_to_slide` | Add text to a slide | Local / Cloud |
| | `figma_add_shape_to_slide` | Add a shape to a slide | Local / Cloud |
| | `figma_set_slide_background` | Set a slide's background color | Local / Cloud |
| | `figma_get_text_styles` | List local text styles with IDs and font info | Local / Cloud |
| | `figma_set_slides_view_mode` | Switch between grid and single-slide view | Local / Cloud |
| | `figma_focus_slide` | Navigate to a slide in the editor | Local / Cloud |
| **🕒 Version History** | `figma_get_file_versions` | List version history with author/label/timestamp metadata | All |
| | `figma_get_file_at_version` | Snapshot a file (or specific nodes) at a past version | All |
| | `figma_diff_versions` | Structured diff between two versions: page changes, component property/binding deltas | All |
| | `figma_get_changes_since_version` | Convenience wrapper: diff against current HEAD | All |
| | `figma_generate_changelog` | Markdown changelog with author enrichment, ready for release notes | All |
| | `figma_blame_node` | Binary-search blame walker: find when (and by whom) a property/variant was introduced | All |
| **☁️ Cloud Relay** | `figma_pair_plugin` | Generate pairing code for Desktop Bridge | Cloud |
Slides tools are documented in the [Slides guide](/slides). MCP Apps (`figma_browse_tokens`, `figma_audit_design_system`) are Local Mode tools that register only when `ENABLE_MCP_APPS=true`; see [MCP Apps](/mcp-apps).
***
## 🧭 Navigation & Status Tools
### `figma_navigate`
Switch the active Figma file target (Local Mode) or navigate the cloud headless browser to a file (Remote/Cloud Mode).
**Usage:**
```javascript theme={null}
figma_navigate({
url: 'https://www.figma.com/design/abc123/My-Design?node-id=1-2',
lock: true // optional — pin this file as the target (Local Mode)
})
```
**Local Mode:** Switches the active file among files that already have the Desktop Bridge plugin running. Does NOT launch a browser or open files — open the target file in Figma Desktop and run the Desktop Bridge plugin in it first.
**`lock` (optional, Local Mode):** Pass `lock: true` to pin the target file. Once pinned, new plugin connections, reconnects, and your own selection/page changes in *other* files will not move the command target — so an AI agent can work in one file while you work in another without writes routing to the wrong file. The pin auto-releases when the pinned file's plugin disconnects or navigates to a different file; switching to another file (or passing `lock: false`) also releases it. Use `figma_list_open_files` to check the current `targetLocked` state before a write batch.
**Remote/Cloud Mode:** Navigates the Cloudflare-hosted headless browser to the URL and starts monitoring.
**Returns:**
* Navigation status
* Current URL
* Connection or monitoring status
* `locked` — whether the target is now pinned (Local Mode)
***
### `figma_get_status`
Check connection and monitoring status. **In local mode, validates WebSocket transport connectivity and shows connection state.**
**Usage:**
```javascript theme={null}
figma_get_status()
```
**Returns:**
* **Setup validation** (local mode only):
* `setup.valid` - Whether the WebSocket transport is available
* `setup.message` - Human-readable status
* `setup.transport` - Transport status (`websocket` or `none`)
* `setup.setupInstructions` - Step-by-step setup guide (if no transport available)
* `setup.ai_instruction` - Guidance for AI assistants
* Browser connection status
* Console monitoring active/inactive
* Current URL (if navigated)
* Number of captured console logs
**Example Response (Local Mode - WebSocket Connected):**
```json theme={null}
{
"mode": "local",
"setup": {
"valid": true,
"message": "✅ Figma Desktop connected via WebSocket (Desktop Bridge Plugin)"
}
}
```
**Example Response (Local Mode - No Transport):**
```json theme={null}
{
"mode": "local",
"setup": {
"valid": false,
"message": "❌ No connection to Figma Desktop",
"setupInstructions": {
"step1": "Install Desktop Bridge Plugin: Figma → Plugins → Development → Import from manifest",
"step2": "Run the plugin in your Figma file"
}
}
}
```
**Best Practice:**
* Call this tool first when starting a session in local mode
* If `setup.valid` is false, guide user to install and run the Desktop Bridge Plugin
***
### `figma_list_open_files`
List every Figma file that currently has the Desktop Bridge plugin open, and show which one is the active target for tool calls.
**Mode:** Local
**Usage:**
```javascript theme={null}
figma_list_open_files()
```
**Returns:** `activeFileKey`, `targetLocked` (whether `figma_navigate({ lock: true })` has pinned the target), and a `files` array with each file's `fileName`, `fileKey`, `currentPage`, `isActive`, and URL. Use the file keys with `figma_execute({ fileKey })` or `figma_execute_across_files({ fileKeys })`, and `figma_navigate` to switch the active file.
***
### `figma_diagnose`
A plain-language health check. Reports which server is answering, whether the Desktop Bridge plugin is connected and to which file, and the state of the Figma token, and helps tell this server's errors apart from errors raised by another Figma-related MCP server in the same client.
**Mode:** Local / Cloud
**Usage:**
```javascript theme={null}
figma_diagnose({
verbose: false // true adds the raw structured plugin and token state
})
```
***
## 📋 Console Tools (Plugin Debugging)
### `figma_get_console_logs`
> **💡 Plugin Developers in Local Mode**: This tool works immediately - no navigation required!
> Just check logs, run your plugin in Figma Desktop, check logs again. All `[Main]`, `[Swapper]`, etc. plugin logs appear instantly.
Retrieve console logs with filters.
**Usage:**
```javascript theme={null}
figma_get_console_logs({
count: 50, // Number of logs to retrieve (default: 100)
level: 'error', // Filter by level: 'log', 'info', 'warn', 'error', 'debug', 'all'
since: 1234567890 // Unix timestamp (ms) - only logs after this time
})
```
**Parameters:**
* `count` (optional): Number of recent logs to retrieve (default: 100)
* `level` (optional): Filter by log level (default: 'all')
* `since` (optional): Unix timestamp in milliseconds - only logs after this time
**Returns:**
* Array of console log entries with:
* `timestamp`: Unix timestamp (ms)
* `level`: 'log', 'info', 'warn', 'error', 'debug'
* `message`: The log message
* `args`: Additional arguments passed to console method
* `stackTrace`: Stack trace (for errors)
**Example:**
```javascript theme={null}
// Get last 20 error logs
figma_get_console_logs({ count: 20, level: 'error' })
// Get all logs from last 30 seconds
const thirtySecondsAgo = Date.now() - (30 * 1000);
figma_get_console_logs({ since: thirtySecondsAgo })
```
***
### `figma_watch_console`
Stream console logs in real-time for a specified duration.
**Usage:**
```javascript theme={null}
figma_watch_console({
duration: 30, // Watch for 30 seconds (default: 30, max: 300)
level: 'all' // Filter by level (default: 'all')
})
```
**Parameters:**
* `duration` (optional): How long to watch in seconds (default: 30, max: 300)
* `level` (optional): Filter by log level (default: 'all')
**Returns:**
* Real-time stream of console logs captured during the watch period
* Summary of total logs captured by level
**Use case:** Perfect for monitoring console output while you test your plugin manually.
***
### `figma_clear_console`
Clear the console log buffer.
**Usage:**
```javascript theme={null}
figma_clear_console()
```
**Returns:**
* Confirmation of buffer cleared
* Number of logs that were cleared
***
## 🔍 Debugging Tools
### `figma_take_screenshot`
Capture screenshots of Figma UI.
**Usage:**
```javascript theme={null}
figma_take_screenshot({
target: 'plugin', // 'plugin', 'full-page', or 'viewport'
format: 'png', // 'png' or 'jpeg'
quality: 90, // JPEG quality 0-100 (default: 90)
filename: 'my-screenshot' // Optional filename
})
```
**Parameters:**
* `target` (optional): What to screenshot
* `'plugin'`: Just the plugin UI (default)
* `'full-page'`: Entire scrollable page
* `'viewport'`: Current visible viewport
* `format` (optional): Image format (default: 'png')
* `quality` (optional): JPEG quality 0-100 (default: 90)
* `filename` (optional): Custom filename
**Returns:**
* Screenshot image
* Metadata (dimensions, format, size)
***
### `figma_reload_plugin`
Reload the current Figma page.
**Usage:**
```javascript theme={null}
figma_reload_plugin({
clearConsole: true // Clear console logs before reload (default: true)
})
```
**Returns:**
* Reload status
* New page URL (if changed)
***
### `figma_capture_screenshot`
Render a node (or the current page) through the plugin's `exportAsync`. Unlike `figma_take_screenshot`, which uses the REST API and reflects the saved cloud state, this captures the current state in the plugin runtime, so use it to check a change immediately after making it.
**Mode:** Local / Cloud
**Usage:**
```javascript theme={null}
figma_capture_screenshot({
nodeId: '1:234', // optional; defaults to the current page
format: 'PNG', // PNG (default), JPG, or SVG
scale: 1 // 0.5–4; the longest side is capped at 1568px
})
```
***
## 👁️ Real-Time Awareness Tools
These tools read events the Desktop Bridge plugin pushes to the local server over its persistent WebSocket connection, so they are available in Local Mode only.
### `figma_get_selection`
Get the nodes currently selected in Figma: IDs, names, types, and dimensions. Use it to act on what the user is pointing at instead of asking them to describe it.
**Mode:** Local
**Usage:**
```javascript theme={null}
figma_get_selection({
verbose: false // true adds fills, strokes, and styles for each node
})
```
### `figma_get_design_changes`
Get recent document-change events buffered by the server: which nodes changed, whether styles changed, and change counts. The buffer holds up to 200 events.
**Mode:** Local
**Usage:**
```javascript theme={null}
figma_get_design_changes({
since: 1727700000000, // optional Unix ms timestamp; only newer events
count: 20, // optional; return the last N events
clear: false // true empties the buffer after reading (for polling)
})
```
***
## 🔁 Token Sync Tools
Bidirectional design token synchronization between Figma variables and your codebase — replaces Style Dictionary and Tokens Studio's export pipeline for popular styling methods.
The canonical pivot format is **DTCG JSON** (W3C Design Tokens Community Group spec), in your choice of dialect: the legacy hex-string form (default) or the DTCG 2025.10 object form. All ten output formats listed below are fully implemented. Import applies the complete diff plan back to Figma — value updates, creates, renames, alias writes, and (under `replace`) deletes.
### `figma_export_tokens`
Export Figma variables to design token files in your codebase. Pulls every variable across every collection and mode, normalizes to the internal token model, and fans out to one or more output formats.
**Usage (zero-arg with `tokens.config.json`):**
```
figma_export_tokens()
```
**Usage (explicit format):**
```javascript theme={null}
figma_export_tokens({
format: "dtcg",
outputPath: "src/styles/tokens",
splitByMode: true,
splitByCollection: true,
prefix: "ds-"
})
```
**`outputPath` — directory or file:**
| You pass | Treated as | Result |
| - | - | - |
| A directory, an extension-less path, or a path ending in `/` | Directory (created if missing) | Each generated file is written inside it (`tokens.tokens.json`, `tokens.css`, …) |
| An existing file, or a path ending in `.json` / `.css` / `.scss` / `.less` / `.ts` / `.js` | File | The export must produce **exactly one file**, which is written at that exact path (overwriting it) |
To re-export one collection straight into an existing per-topic token file:
```javascript theme={null}
figma_export_tokens({
scope: "collection",
collectionIds: ["VariableCollectionId:12:34"],
format: "dtcg",
outputPath: "src/styles/tokens/typography.tokens.json"
})
```
A file path combined with a multi-file export (several formats from `tokens.config.json`, `splitByMode`, `splitByCollection`, `tokens-studio`) is rejected with an explanatory error **before anything is written** — pass a directory instead, or narrow the export to one file. `strategy: "dry-run"` reports the resolved destination as `wouldWriteTo`.
**Output formats:**
| Format | Notes |
| - | - |
| `dtcg` | W3C Design Tokens Community Group standard JSON. Canonical pivot format. Round-trip safe via `$extensions["figma-console-mcp"]` (Figma variable IDs preserved across sync). Dialect selectable via `dtcgDialect` (see below). |
| `css-vars` | CSS custom properties. `:root { ... }` blocks with mode-aware selectors (`.dark`, `[data-theme="..."]`). Composite typography expands to primitive vars. |
| `tailwind-v4` | Tailwind v4 `@theme inline { ... }` block. Token-to-namespace mapping generates utility classes (`bg-primary`, `text-foreground`, `rounded-lg`, etc.). |
| `tailwind-v3` | `module.exports = { colors: ... }` grouped under Tailwind v3 theme keys (`colors`, `spacing`, `fontFamily`, `borderRadius`). Spread into `tailwind.config.js`'s `theme.extend`. |
| `scss` | `$var: value;` SCSS variables. Multi-mode tokens emit a primary `$var` plus a `$var--modes` SCSS map for runtime `map-get` access. |
| `ts-module` | `export const tokens = { ... } as const` with derived `type Tokens = typeof tokens`. Multi-mode tokens emit as `{ Light: ..., Dark: ... }` objects. |
| `json-flat` | Flat key-value JSON (`{"ds-color-primary": "#4085F2"}`). Non-primary modes get a `--` suffix on keys. For custom build scripts. |
| `json-nested` | Nested object JSON mirroring the token path tree. Multi-mode tokens emit as mode-keyed sub-objects. Alphabetical key ordering. |
| `style-dictionary-v3` | Style Dictionary v3 bare-key source format (`{value, type, comment}` — no `$` prefix). Back-compat for existing SD users. |
| `tokens-studio` | Tokens Studio for Figma's multi-file layout: `$themes.json` + `$metadata.json` + per-set files (e.g. `theme/light.json`, `theme/dark.json`). Preserves Figma collection/mode bindings for round-trip with the TS plugin. |
**DTCG dialect (`dtcgDialect`):**
| Value | Behavior |
| - | - |
| `"legacy"` (default) | Hex-string colors (`"#4085F2"`), bare-number dimensions. Byte-identical to prior releases — maximum compatibility with Style Dictionary v4 and Tokens Studio. |
| `"2025"` | DTCG 2025.10 object forms: colors as `{ colorSpace: "srgb", components, alpha, hex }` (built from Figma's full-precision floats, not re-derived from quantized hex) and dimensions as `{ value, unit: "px" }`. For Style Dictionary v5+ and other 2025.10-aware toolchains. |
Import accepts **both** dialects unconditionally — no flag needed on `figma_import_tokens`, and mixed-dialect token files diff correctly (object colors compare equal to their hex equivalents, `{ value: 16, unit: "px" }` equals `16`).
**Write safety:** Export *replaces* each target file's contents with the current Figma state — it does not merge token-by-token. Under the default `strategy: "merge"` the tool refuses to write, leaving the file untouched, when overwriting an existing DTCG file would delete tokens it doesn't manage: tokens you added by hand, or tokens from collections that aren't part of this export. It also refuses when a requested `collectionIds` entry isn't found in the file it read, or when the export comes back empty — both usually mean a different file is active in Figma than you intended. Variables deleted in Figma are removed from the file as normal. Use `strategy: "dry-run"` to preview, and `strategy: "replace"` to overwrite unconditionally.
**Wrong-file protection:** the Desktop Bridge reads variables from whichever file is *active* in Figma Desktop. To stop an export from the wrong file replacing your tokens, each generated file records the Figma file it came from — a `Source: Figma file ` line under the `Generated by figma-console-mcp` header in CSS / SCSS / TypeScript / Tailwind outputs, and `figmaFileKey` in a DTCG file's root `$extensions`. Under the default strategy, an export that read from a *different* Figma file than the one recorded in the target refuses to write. A multi-format run is all-or-nothing: if any file is refused, none are written.
Two limits worth knowing: protection starts once a file has been exported by v1.40.2 or later (older files carry no record, so the first export after upgrading proceeds and adds one), and the plain-JSON formats (`json-flat`, `json-nested`, `style-dictionary-v3`, `tokens-studio`) have nowhere to carry a record when exported on their own. It also depends on the Desktop Bridge plugin reporting the file key (the bundled manifest enables this): if a target records its source but the plugin can't say which file it read, the export refuses rather than guess. **For the strongest guarantee, pin `figmaFile` in `tokens.config.json`** — the export is then routed to that specific file and fails if it isn't open, regardless of which tab is focused.
**Check the source:** every response includes `source: { fileName, fileKey }` — the Figma file the variables were actually read from.
**Round-trip safety:** Every exported token carries its Figma `variableId` and `collectionId` in DTCG `$extensions["figma-console-mcp"]`. Renames on either side don't create duplicates — the ID is the primary match key. Also stamps `lastSyncedValue` (per-mode snapshot) and `lastSyncedAt` so two-sided conflicts can be detected on import, plus variable `scopes` (omitted when default) and per-platform `codeSyntax` so metadata survives the round-trip.
**Colors at an opacity:** a color variable set to another color with an opacity ("grey/900 at 50%") exports with its link to the primitive where the format can express it: `color-mix(in srgb, var(--grey-900) 50%, transparent)` in CSS and Tailwind v4, `rgba($grey-900, 0.5)` in SCSS, the primitive reference plus an `alpha` modifier in Tokens Studio. Other formats get the resolved color. In DTCG, `$value` is the resolved color and `$extensions["figma-console-mcp"].composedColor` records each mode's `{ color, opacity }` (opacity is a percent, as in Figma); `figma_import_tokens` writes that composition back. Edit `composedColor` to change the link or opacity; editing only `$value` imports a plain color instead.
**Cloud Mode:** Omit `configPath` and `outputPath`. The tool returns token content inline in the response; have your AI client write the files via its own Edit/Write tools. File I/O (autodiscovery, automatic writes) is Local Mode only.
**Cross-library aliases:** Variables that reference targets in a published library (not in this file's local variable set) get stamped with `{__library:VariableID:...}` references — the original Figma ID is preserved for round-trip. CSS formatters emit a comment for skipped tokens with the original library variable ID, so you can see exactly what's missing and decide how to handle it.
***
### `figma_import_tokens`
Push code-side token edits back to Figma. Parses any supported source format, diffs against current Figma state, and applies only the deltas via the Plugin API.
**Usage (zero-arg with `tokens.config.json`):**
```
figma_import_tokens()
```
**Usage (inline payload):**
```javascript theme={null}
figma_import_tokens({
format: "dtcg",
payload: "{ \"color\": { \"primary\": { \"$type\": \"color\", \"$value\": \"#FF00AA\" } } }",
strategy: "dry-run" // preview first
})
```
**Strategies:**
| Strategy | Behavior |
| - | - |
| `merge` | Default. Apply only changed values. Preserve Figma-only and code-only tokens unless the conflict-resolution rule says otherwise. |
| `replace` | Wipe and rewrite. Destructive — requires explicit `replace`, never the default. |
| `dry-run` | Compute the diff plan, return it, do not mutate Figma. |
**Match priority** (how a code-side token gets paired to a Figma variable):
1. **Figma variable ID** stored in `$extensions["figma-console-mcp"].variableId`. Survives renames.
2. **Token path** (e.g. `color.primary`). Used when metadata is absent (first sync, hand-authored DTCG).
3. **Value fingerprint.** Used to detect no-op writes — same hash means no API call.
**Conflict handling:** When both Figma and code changed the same token since the last sync, `onConflict: "ask"` (default) surfaces the conflict and writes nothing. Use `"figma-wins"` / `"code-wins"` to auto-resolve, or `"skip"` to leave conflicts alone and proceed with the rest.
**What the apply phase does:**
* ✅ `toUpdate` (value changes on existing variables): applied via the plugin bridge (`figma.variables.setValueForMode`). Multi-mode supported. Renames matched by round-trip variable ID apply as name changes on the existing variable — a token-path rename never becomes a create+delete pair. `scopes` and `codeSyntax` metadata changes apply too (a code-side absent field means "no opinion" and never resets Figma metadata).
* ✅ `toCreate` (new variables and collections): missing collections are created with their full mode lists; missing variables are created with inferred or round-trip-recorded types, values set across all modes in dependency order — literal values first, alias values in a second pass so their targets exist. TIMING/EASING tokens are skipped with a clear warning (the Plugin API cannot create those types).
* ✅ Alias updates (code-side `{color.primary}` references): written as real `{ type: "VARIABLE_ALIAS", id }` values. Resolver priority: just-created variable → live Figma snapshot → pending in this batch → recorded `$extensions` variable ID. Unresolvable references are skipped with a warning.
* ✅ `toDelete` (Figma-only variables): applied **only** under `strategy: "replace"`, and announced loudly in the response. The default `merge` strategy reports them without deleting.
Partial-success semantics throughout — per-variable errors don't fail the batch; results are returned in `applyResult.errors[]`.
**Cloud Mode:** Pass tokens inline via `payload` (single file) or `files` (multi-file). Omit `configPath`. The apply phase works in Cloud Mode because it routes through the paired Desktop Bridge plugin via the Cloud Plugin Relay — transport-agnostic.
***
## 🧬 Design System Extraction Tools
> **⚠️ Local Mode only**: These tools read a production codebase and write a design-system package to your local filesystem — something the cloud deployment cannot do. They are registered only in Local Mode (NPX / Local Git) and never appear in Cloud or Remote Mode tool lists.
Turn a production codebase into a design system. The tools run in order:
1. **`figma_ds_analyze`** — scan the app(s): component inventory, classification, architecture picture
2. **`figma_ds_extract_tokens`** — mine the styling into DTCG tokens
3. **`figma_ds_scaffold`** — generate the design-system package, then run `npm create storybook@latest` inside it
4. **`figma_ds_setup_storybook`** — wire the fresh workshop to the extracted system
5. Per component: **`figma_ds_extract_component`** → port it → record with **`figma_ds_status`**
6. **`figma_ds_verify`** — deterministic fidelity evals before handoff or pushing tokens to Figma
For design-led organizations, the extracted `tokens/tokens.json` imports straight into Figma variables with `figma_import_tokens` (top-level groups become collections) — a full code → design system → Figma round-trip.
All manifests persist under `/.extraction/`, so a long engagement survives session boundaries.
### `figma_ds_analyze`
Analyze one or more production app codebases as the first step of extraction. Detects framework (React/Next/Angular/Web Components), styling methods (Tailwind v3/v4, CSS Modules, SCSS, Emotion, styled-components), and vendor component layers (shadcn/ui, Radix, MUI, Chakra, etc.); builds a component inventory with per-component classification (vendored / wrapped / pure-vendor / bespoke), prop contracts, real usage counts (porting rank), observed prop values (variant inference), and duplicate detection. Iconography and typography rules are captured for the scaffold's showcase pages.
It also classifies the **architecture** — the difference between a UI kit and a design system. An app ships `FollowButton`, `ModerationMenu`, `NodeCard` (components named after usage); a design system ships `Button`, `Menu`, `Card`. The analyzer assigns atomic levels, detects specializations (`FollowButton` → `Button`), and derives `missingPrimitives`: the generic components the specializations imply but that don't exist in the codebase — your design-system build list.
**When to Use:**
* Starting a design-system engagement from an existing product codebase
* Deciding what to build: which components are worth porting, which are vendor pass-throughs, which usage-named components should collapse into generic primitives
* Finding the shared design language across several apps (pass multiple targets — inventories merge and cross-app duplicates are flagged)
**Usage:**
```javascript theme={null}
figma_ds_analyze({
targets: ["/absolute/path/to/app"], // multiple targets = cross-app extraction
outDir: "/absolute/path/to/design-system", // optional; default: /design-system
exclude: ["legacy/"], // optional substring filters
maxFiles: 5000
})
```
**Parameters:**
* `targets` (required): App root directories. **Absolute paths strongly recommended** — the MCP server's working directory is not your project.
* `outDir` (optional): Where the design-system package will be generated; manifests persist under `/.extraction/`. Default: `/design-system`.
* `include` / `exclude` (optional): Substring filters on relative paths (`node_modules`, `dist`, `.next`, etc. are always skipped).
* `maxFiles` (optional): Hard cap on files scanned per target (default 5000).
**Returns:** A compressed summary — per-target detection results, inventory counts by classification, top components by usage, duplicate groups, and the architecture summary (specializations + missing primitives) — plus the path to the full manifest at `/.extraction/analysis.json`. Read slices of the manifest for detail.
***
### `figma_ds_extract_tokens`
Extract design tokens from the analyzed codebase into canonical DTCG JSON (plus optional CSS variables / Tailwind / SCSS / TypeScript projections via the same formatter engine as `figma_export_tokens`).
Mining runs in two confidence tiers:
1. **Declared** styling intent — `:root` and `@theme` custom properties (light + dark blocks across framework conventions: `.dark`, `[data-theme=…]`, `[data-mode=…]`, `prefers-color-scheme` → multi-mode tokens), SCSS variables, `tailwind.config` theme values, shadcn HSL triples. These keep their names and always become tokens.
2. **Inferred** — recurring raw values (hex colors, spacing/radius/font sizes) promoted above a frequency threshold; everything below the threshold is listed in the report for human review instead of silently dropped. Tailwind utility classes used in markup are frequency-mined and valued from the app's **own installed theme**, so the values are version-accurate rather than from a hardcoded palette.
Every token carries provenance — source `file:line`, confidence tier, frequency — in `$extensions`. Names stay structural as mined (`color/blue/500`); do a semantic-naming review pass with the user afterwards (role names layer on as aliases).
**Usage:**
```javascript theme={null}
figma_ds_extract_tokens({
outDir: "/absolute/path/to/design-system", // same outDir as figma_ds_analyze
formats: ["dtcg", "css-vars", "tailwind-v4"], // match the app's styling method
minFrequency: 4, // promotion threshold for undeclared raw values
write: true // false = dry run, returns the DTCG document inline
})
```
**Parameters:**
* `outDir` (optional): The outDir used in `figma_ds_analyze` (reads `.extraction/analysis.json` from it). Pass explicitly when in doubt.
* `targets` (optional): Override — scan these app roots instead of the analysis manifest's targets (rarely needed).
* `formats` (optional, default `["dtcg", "css-vars"]`): Token file formats to write under `/tokens/`. `dtcg` (canonical) is always written; the full format list matches `figma_export_tokens`.
* `dtcgDialect` (optional, default `"legacy"`): `"legacy"` hex-string colors (max compatibility) or `"2025"` DTCG 2025.10 object colors/dimensions.
* `minFrequency` (optional, default 4): How often a raw value must recur to be promoted to a token.
* `write` (optional, default `true`): Write files, or return the document inline (dry run).
**Returns:** Token counts by tier and type, set/mode structure, warnings, a below-threshold sample for review, and the list of files written. The DTCG output at `tokens/tokens.json` is directly importable via `figma_import_tokens` — top-level groups become Figma variable collections.
***
### `figma_ds_scaffold`
Generate the design-system package skeleton at `outDir` from a completed analysis + token extraction: `package.json` (app framework as peer deps), `src/components` layout, token files via the shared formatter engine, framework-neutral token/typography/iconography showcase MDX docs pages (the bird's-eye view of what was mined), and a README with the workflow.
Storybook itself is **not** installed by this tool — after scaffolding, run `npm create storybook@latest` inside `outDir`. The Storybook CLI auto-detects the framework and installs the current version, so the scaffold never bakes version-pinned Storybook templates that rot.
**Usage:**
```javascript theme={null}
figma_ds_scaffold({
outDir: "/absolute/path/to/design-system",
packageName: "@acme/design-system", // default: @extracted/design-system
force: false // existing files are skipped unless true
})
```
**Parameters:**
* `outDir` (required): The outDir used in `figma_ds_analyze` / `figma_ds_extract_tokens`.
* `packageName` (optional): npm package name for the design system.
* `framework` (optional): Override the scaffold framework (default: first framework detected by the analysis). Note: Storybook has no `.astro` renderer — `astro` scaffolds a react-vite workshop whose stories mirror the component markup.
* `formats` / `dtcgDialect` (optional): Token formats to (re)generate under `tokens/`.
* `force` (optional, default `false`): Overwrite existing scaffold files (token files always refresh).
**Returns:** Files written/skipped and next steps. Additive by default — safe to re-run.
***
### `figma_ds_setup_storybook`
Wire a freshly-initialized Storybook workshop to the extracted design system — run **after** `npm create storybook@latest` inside `outDir`. A stock workshop knows nothing about the source app; each piece this generates corresponds to a real render-fidelity failure found in live extraction runs:
* **`.storybook/preview.css`** — Tailwind entry importing the extracted tokens plus the **source app's** `@theme` utility mapping, custom `@utility` definitions, `@layer base`, and `@font-face` rules mined from its stylesheets, with a dark variant covering both `.dark` and `[data-theme]` conventions
* **Font copying** — self-hosted font files copied into `staticDirs`, with runtime-var fallbacks
* **`main.js` patch** — Tailwind vite plugin + automatic JSX runtime (without it, stories throw `React is not defined`)
* **`preview.jsx` patch** — preview\.css import + a theme toolbar/decorator that sets both the class and `data-theme` conventions, using the extracted mode names
**Usage:**
```javascript theme={null}
figma_ds_setup_storybook({
outDir: "/absolute/path/to/design-system" // must contain a fresh .storybook/
})
```
**Parameters:**
* `outDir` (required): The design-system package dir (same outDir as `figma_ds_analyze`) containing the freshly-initialized `.storybook/`.
**Returns:** What was generated/patched, plus any manual steps for things it couldn't patch safely. Idempotent — safe to re-run. Restart the Storybook dev server afterwards; `@import`ed CSS changes are not always hot-reloaded.
***
### `figma_ds_extract_component`
Deep-extract **one** component from the inventory for porting into the design system: source (capped at 64KB), local import closure (relative imports to follow), prop contract, observed call-site variants, vendor classification, style touchpoints (classNames, CSS-module imports, custom properties referenced), and a ready-to-adapt CSF3 story scaffold with variant stories inferred from real usage.
The agent then ports the component into `/src/components//` and records progress with `figma_ds_status`.
**Usage:**
```javascript theme={null}
figma_ds_extract_component({
outDir: "/absolute/path/to/design-system",
component: "Button" // name from the inventory (see figma_ds_analyze topByUsage)
})
```
**Parameters:**
* `outDir` (required): The outDir used in `figma_ds_analyze`.
* `component` (required): Component name from the inventory. Near-miss names come back as suggestions.
**Returns:** The porting manifest plus a `portingChecklist` (decouple app-specific imports, replace hardcoded values with tokens, adapt the story scaffold, verify visually, record status). Pure-vendor components return guidance instead of source — theme them via tokens and document approved usage, or wrap them in the design system if customization is needed.
***
### `figma_ds_verify`
Run the deterministic fidelity evals on an extracted design-system package — the governance gate before handing off or pushing tokens to Figma. Each check encodes a failure class found in real extraction runs:
| Check | Catches |
| - | - |
| DTCG parse + alias integrity | `tokens.json` that won't import, dangling `{alias}` references |
| Quoted-CSS-expression scan | Quoted functional expressions (`"cubic-bezier(...)"`) in generated token files — they silently kill transitions |
| Workshop `var()` resolution | `var(--x)` consumed in component/preview CSS with no definition anywhere in the workshop |
| Structure | Component directories missing a stories file or index barrel |
| Porting coverage | Portable inventory components with no recorded porting status |
Also reports **Figma round-trip readiness** with the exact `figma_import_tokens` call for design-led orgs (ask the user: code-led or design-led?).
**Usage:**
```javascript theme={null}
figma_ds_verify({ outDir: "/absolute/path/to/design-system" })
```
**Parameters:**
* `outDir` (required): The design-system package dir.
**Returns:** `{ passed, checks: [{ name, status: pass|fail|warn|skip, details }], figmaRoundTrip: { ready, how } }`.
***
### `figma_ds_status`
Read or update porting progress, persisted in `/.extraction/status.json` so long engagements survive session boundaries.
**Usage:**
```javascript theme={null}
// Read progress
figma_ds_status({ outDir: "/absolute/path/to/design-system" })
// Record a component's status
figma_ds_status({
outDir: "/absolute/path/to/design-system",
update: {
component: "Button",
status: "ported", // pending | in-progress | ported | skipped
notes: "Merged FollowButton + SubscribeButton into variants",
storyFile: "src/components/Button/Button.stories.jsx"
}
})
```
**Parameters:**
* `outDir` (required): The outDir used in `figma_ds_analyze`.
* `update` (optional): `{ component, status, notes?, storyFile? }`. Omit to just read progress.
**Returns:** Status counts, the next components remaining, and the manifest path.
***
## 🎨 Design System Tools
> **⚠️ All Design System tools require `FIGMA_ACCESS_TOKEN`** configured in your MCP client.
>
> See the [Setup Guide](/setup) for setup instructions.
### `figma_get_variables`
Extract design tokens/variables from a Figma file. Supports both main files and branches.
**Usage:**
```javascript theme={null}
figma_get_variables({
fileUrl: 'https://figma.com/design/abc123',
includePublished: true, // Include published library variables
enrich: true, // Add CSS/Tailwind exports
export_formats: ['css', 'tailwind', 'sass'], // Export formats
include_usage: true, // Show where variables are used
include_dependencies: true // Show variable dependencies
})
```
**Branch Support:**
The tool automatically detects and handles Figma branch URLs in both formats:
```javascript theme={null}
// Path-based branch URL
figma_get_variables({
fileUrl: 'https://figma.com/design/abc123/branch/xyz789/My-File'
})
// Query-based branch URL
figma_get_variables({
fileUrl: 'https://figma.com/design/abc123/My-File?branch-id=xyz789'
})
```
**Auto-Detection:** If you've navigated to a file using `figma_navigate`, you can omit `fileUrl` entirely:
```javascript theme={null}
// First navigate to the branch
figma_navigate({ url: 'https://figma.com/design/abc123/branch/xyz789/My-File' })
// Then get variables from the current file
figma_get_variables({ refreshCache: true })
```
**Parameters:**
* `fileUrl` (optional): Figma file URL - supports main files and branches (uses current if navigated)
* `includePublished` (optional): Include published variables (default: true)
* `enrich` (optional): Add exports and usage analysis (default: false)
* `export_formats` (optional): Code formats to generate
* `include_usage` (optional): Include usage in styles/components
* `include_dependencies` (optional): Include dependency graph
* `refreshCache` (optional): Force fresh data fetch, bypassing cache
**Returns:**
* Variable collections
* Variables with modes and values
* Summary statistics
* Export code (if `enrich: true`)
* Usage information (if `include_usage: true`)
* Branch info (when using branch URL): `fileKey`, `branchId`, `isBranch`
**Note:** Figma Variables API requires Enterprise plan. If unavailable, the tool automatically falls back to Styles API or console-based extraction.
***
### `figma_get_styles`
Get all styles (color, text, effects) from a Figma file.
**Usage:**
```javascript theme={null}
figma_get_styles({
fileUrl: 'https://figma.com/design/abc123',
enrich: true, // Add code exports
export_formats: ['css', 'tailwind'], // Export formats
include_usage: true, // Show component usage
include_exports: true // Include code examples
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `enrich` (optional): Add exports and usage (default: false)
* `export_formats` (optional): Code formats to generate
* `include_usage` (optional): Show where styles are used
* `include_exports` (optional): Include code examples
**Returns:**
* All styles (color, text, effect, grid)
* Style metadata and properties
* Export code (if `enrich: true`)
* Usage information (if requested)
***
### `figma_get_component`
Get component data in two export formats: metadata (default) or reconstruction specification.
**Usage:**
```javascript theme={null}
// Metadata format (default) - for documentation and style guides
figma_get_component({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '123:456',
format: 'metadata', // or omit for default
enrich: true // Add token coverage analysis
})
// Reconstruction format - for programmatic component creation
figma_get_component({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '123:456',
format: 'reconstruction' // Compatible with Figma Component Reconstructor plugin
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `nodeId` (required): Component node ID (e.g., '123:456')
* `format` (optional): Export format - `'metadata'` (default) or `'reconstruction'`
* `enrich` (optional): Add quality metrics (default: false, only for metadata format)
**Export Formats:**
**Metadata Format** (default):
* Component metadata and documentation
* Properties and variants
* Bounds and layout info
* Token coverage (if `enrich: true`)
* Use for: Documentation, style guides, design system references
**Reconstruction Format**:
* Complete node tree specification
* All visual properties (fills, strokes, effects)
* Layout properties (auto-layout, padding, spacing)
* Text properties with font information
* Color values in 0-1 normalized RGB format
* Validation of spec against plugin requirements
* Use for: Programmatic component creation, version control, component migration
* Compatible with: Figma Component Reconstructor plugin
***
### `figma_get_component_for_development`
Get component data optimized for UI implementation, with visual reference.
**Usage:**
```javascript theme={null}
figma_get_component_for_development({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '695:313',
includeImage: true // Include rendered image (default: true)
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `nodeId` (required): Component node ID
* `includeImage` (optional): Include rendered image (default: true)
**Returns:**
* Component image (rendered at 2x scale)
* Filtered component data with:
* Layout properties (auto-layout, padding, spacing)
* Visual properties (fills, strokes, effects)
* Typography
* Component properties and variants
* Bounds and positioning
**Excludes:** Plugin data, document metadata (optimized for UI implementation)
***
### `figma_get_component_image`
Render a component as an image only.
**Usage:**
```javascript theme={null}
figma_get_component_image({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '695:313',
scale: 2, // Image scale (0.01-4, default: 2)
format: 'png' // 'png', 'jpg', 'svg', 'pdf'
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `nodeId` (required): Node ID to render
* `scale` (optional): Scale factor (default: 2)
* `format` (optional): Image format (default: 'png')
**Returns:**
* Image URL (expires after 30 days)
* Image metadata
***
### `figma_get_file_data`
Get file structure with verbosity control.
**Usage:**
```javascript theme={null}
figma_get_file_data({
fileUrl: 'https://figma.com/design/abc123',
depth: 2, // Levels of children (0-3, default: 1)
verbosity: 'standard', // 'summary', 'standard', 'full'
nodeIds: ['123:456'], // Specific nodes only (optional)
enrich: true // Add file statistics and health metrics
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `depth` (optional): Depth of children tree (max: 3)
* `verbosity` (optional): Data detail level
* `'summary'`: IDs, names, types only (\~90% smaller)
* `'standard'`: Essential properties (\~50% smaller)
* `'full'`: Everything
* `nodeIds` (optional): Retrieve specific nodes only
* `enrich` (optional): Add statistics and metrics
**Returns:**
* File metadata
* Document tree (filtered by verbosity)
* Component/style counts
* Statistics (if `enrich: true`)
***
### `figma_get_file_for_plugin`
Get file data optimized for plugin development.
**Usage:**
```javascript theme={null}
figma_get_file_for_plugin({
fileUrl: 'https://figma.com/design/abc123',
depth: 3, // Higher depth allowed (max: 5)
nodeIds: ['123:456'] // Specific nodes (optional)
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL
* `depth` (optional): Depth of children (max: 5, default: 2)
* `nodeIds` (optional): Specific nodes only
**Returns:**
* Filtered file data with:
* IDs, names, types
* Plugin data (pluginData, sharedPluginData)
* Component relationships
* Lightweight bounds
* Structure for navigation
**Excludes:** Visual properties (fills, strokes, effects) - optimized for plugin work
***
## Tool Comparison
### When to Use Each Tool
**For Component Development:**
* `figma_get_component_for_development` - Best for implementing UI components (includes image + layout data)
* `figma_get_component_image` - Just need a visual reference
* `figma_get_component` - Need full component metadata
**For Plugin Development:**
* `figma_get_file_for_plugin` - Optimized file structure for plugins
* `figma_get_console_logs` - Debug plugin code
* `figma_watch_console` - Monitor plugin execution
**For Design System Extraction:**
* `figma_get_variables` - Design tokens with code exports
* `figma_get_styles` - Traditional styles with code exports
* `figma_get_file_data` - Full file structure with verbosity control
**For Debugging:**
* `figma_get_console_logs` - Retrieve specific logs
* `figma_watch_console` - Live monitoring
* `figma_take_screenshot` - Visual debugging
* `figma_get_status` - Check connection health
***
***
## ✏️ Design Creation Tools
> **⚠️ Requires Desktop Bridge Plugin**: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using `figma_pair_plugin` to connect through the cloud relay.
### `figma_execute`
**The Power Tool** - Execute any Figma Plugin API code to create designs, modify elements, or perform complex operations.
**When to Use:**
* Creating UI components (buttons, cards, modals, notifications)
* Building frames with auto-layout
* Adding text with specific fonts and styles
* Creating shapes (rectangles, ellipses, vectors)
* Applying effects, fills, and strokes
* Creating pages or organizing layers
* Any operation that requires the full Figma Plugin API
**Usage:**
```javascript theme={null}
figma_execute({
code: `
// Create a button component
const button = figma.createFrame();
button.name = "Button";
button.resize(120, 40);
button.cornerRadius = 8;
button.fills = [{ type: 'SOLID', color: { r: 0.23, g: 0.51, b: 0.96 } }];
// Add auto-layout
button.layoutMode = "HORIZONTAL";
button.primaryAxisAlignItems = "CENTER";
button.counterAxisAlignItems = "CENTER";
// Add text
await figma.loadFontAsync({ family: "Inter", style: "Medium" });
const text = figma.createText();
text.characters = "Click me";
text.fontName = { family: "Inter", style: "Medium" };
text.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
button.appendChild(text);
// Position and select
button.x = figma.viewport.center.x;
button.y = figma.viewport.center.y;
figma.currentPage.selection = [button];
return { nodeId: button.id, name: button.name };
`,
timeout: 10000 // Optional: max execution time in ms (default: 5000)
})
```
**Parameters:**
* `code` (required): JavaScript code to execute. Has access to `figma` global object.
* `timeout` (optional): Execution timeout in ms (default: 5000, max: 30000)
* `fileKey` (optional, **Local Mode only**): Run against a specific connected file instead of the active one, without changing the active file or releasing target lock. Get connected fileKeys from `figma_list_open_files`. Cloud Mode pairs with a single plugin instance and rejects this parameter rather than silently running against the paired file.
**Returns:**
* Whatever the code returns (use `return` statement)
* Execution success/failure status
* `fileContext` — the file name and key **as reported by the plugin that ran the code**, so you can confirm it executed where you intended
**Best Practices:**
1. **Always use `await` for async operations** (loadFontAsync, getNodeByIdAsync)
2. **Return useful data** (node IDs, names) for follow-up operations
3. **Position elements** relative to viewport center for visibility
4. **Select created elements** so users can see them immediately
5. **Use try/catch** for error handling in complex operations
**Common Patterns:**
```javascript theme={null}
// Create a page
const page = figma.createPage();
page.name = "My New Page";
await figma.setCurrentPageAsync(page);
// Find and modify existing node
const node = await figma.getNodeByIdAsync("123:456");
node.name = "New Name";
// Create component from frame
const component = figma.createComponent();
// ... add children
// Apply auto-layout
frame.layoutMode = "VERTICAL";
frame.itemSpacing = 8;
frame.paddingTop = 16;
frame.paddingBottom = 16;
frame.paddingLeft = 16;
frame.paddingRight = 16;
```
***
### `figma_execute_across_files`
**Local Mode only.** Run the same code in several connected files at once, concurrently. Built for cross-file work on a multi-file design system — auditing every file for the same problem, or applying the same fix to a set of them — instead of switching the active file and running `figma_execute` once per file.
Each file's code runs in that file's own plugin context, so one file's failure or timeout doesn't affect the others. Results come back as a per-file map.
**When to Use:**
* Checking the same thing across a library split over multiple files ("which files still use the old text styles?")
* Applying one mechanical fix across a known set of files
* Any read that you'd otherwise repeat file by file
**Usage:**
```javascript theme={null}
// Preferred: name the files you mean.
figma_execute_across_files({
fileKeys: ["abc123", "def456"], // from figma_list_open_files
code: `
const detached = figma.currentPage.findAll(n => n.type === "INSTANCE" && !n.mainComponent);
return { detachedCount: detached.length };
`,
timeout: 10000
})
// Every connected file — opt in explicitly.
figma_execute_across_files({
allFiles: true,
code: `return { pageCount: figma.root.children.length };`
})
```
**Parameters:**
* `code` (required): JavaScript to run in each targeted file. Same `figma` global as `figma_execute`.
* `fileKeys` (optional): Which connected files to target. Get them from `figma_list_open_files`.
* `allFiles` (optional, default `false`): Target every connected file.
* `timeout` (optional): Per-file timeout in ms (default: 10000, max: 30000). Applied independently per file — one unresponsive file doesn't delay the rest.
**You must pass either `fileKeys` or `allFiles: true`.** The tool refuses to run otherwise. This is deliberate: `allFiles` executes your code in files you may be actively editing, including one pinned by target lock, so hitting everything is a decision rather than what happens when you leave a parameter out. Name the files explicitly for anything that writes.
**Returns:**
```json theme={null}
{
"results": {
"abc123": {
"fileName": "Design System — Core",
"success": true,
"result": { "detachedCount": 3 },
"fileContext": { "fileName": "Design System — Core", "fileKey": "abc123" }
},
"def456": {
"fileName": "Design System — Icons",
"success": false,
"error": "WebSocket command EXECUTE_CODE timed out after 10000ms"
}
},
"totalTargeted": 2,
"totalSucceeded": 1,
"totalFailed": 1,
"missingFileKeys": ["ghi789"]
}
```
* `fileContext` is reported by the plugin that actually ran the code — use it to confirm each result came from the file you addressed.
* `missingFileKeys` lists requested files that aren't currently connected; the rest still run.
* The response is only marked as an error if *every* targeted file failed.
**Requires** the Desktop Bridge plugin open in each target file. Cloud Mode pairs with exactly one plugin instance, so this tool isn't available there.
***
## 🔧 Variable Management Tools
> **⚠️ Requires Desktop Bridge Plugin**: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using `figma_pair_plugin` to connect through the cloud relay.
### `figma_create_variable_collection`
Create a new variable collection with optional modes.
**When to Use:**
* Setting up a new design system
* Creating themed variable sets (colors, spacing, typography)
* Organizing variables into logical groups
**Usage:**
```javascript theme={null}
figma_create_variable_collection({
name: "Brand Colors",
initialModeName: "Light", // Optional: rename default mode
additionalModes: ["Dark", "High Contrast"] // Optional: add more modes
})
```
**Parameters:**
* `name` (required): Collection name
* `initialModeName` (optional): Name for the default mode (otherwise "Mode 1")
* `additionalModes` (optional): Array of additional mode names to create
**Returns:**
* Created collection with ID, name, modes, and mode IDs
***
### `figma_create_variable`
Create a new variable in a collection.
**When to Use:**
* Adding design tokens to your system
* Creating colors, spacing values, text strings, or boolean flags
* Setting up multi-mode variable values
**Usage:**
```javascript theme={null}
figma_create_variable({
name: "colors/primary/500",
collectionId: "VariableCollectionId:123:456",
resolvedType: "COLOR",
valuesByMode: {
"1:0": "#3B82F6", // Light mode
"1:1": "#60A5FA" // Dark mode
},
description: "Primary brand color", // Optional
scopes: ["ALL_FILLS"] // Optional
})
```
**Parameters:**
* `name` (required): Variable name (use `/` for grouping)
* `collectionId` (required): Target collection ID
* `resolvedType` (required): `"COLOR"`, `"FLOAT"`, `"STRING"`, or `"BOOLEAN"`
* `valuesByMode` (optional): Object mapping mode IDs to values
* `description` (optional): Variable description
* `scopes` (optional): Where variable can be applied
**Value Formats:**
* **COLOR**: Hex string `"#FF0000"` or `"#FF0000FF"` (with alpha)
* **FLOAT**: Number `16` or `1.5`
* **STRING**: Text `"Hello World"`
* **BOOLEAN**: `true` or `false`
***
### `figma_update_variable`
Update a variable's value in a specific mode.
**When to Use:**
* Changing existing token values
* Updating theme-specific values
* Modifying design system tokens
**Usage:**
```javascript theme={null}
figma_update_variable({
variableId: "VariableID:123:456",
modeId: "1:0",
value: "#10B981" // New color value
})
```
**Parameters:**
* `variableId` (required): Variable ID to update
* `modeId` (required): Mode ID to update value in
* `value` (required): New value (format depends on variable type)
***
### `figma_rename_variable`
Rename a variable while preserving all its values.
**When to Use:**
* Reorganizing variable naming conventions
* Fixing typos in variable names
* Moving variables to different groups
**Usage:**
```javascript theme={null}
figma_rename_variable({
variableId: "VariableID:123:456",
newName: "colors/brand/primary"
})
```
**Parameters:**
* `variableId` (required): Variable ID to rename
* `newName` (required): New name (can include `/` for grouping)
***
### `figma_delete_variable`
Delete a variable.
**When to Use:**
* Removing unused tokens
* Cleaning up design system
* Removing deprecated variables
**Usage:**
```javascript theme={null}
figma_delete_variable({
variableId: "VariableID:123:456"
})
```
**⚠️ Warning:** This action cannot be undone programmatically. Use Figma's Undo if needed.
***
### `figma_delete_variable_collection`
Delete a collection and ALL its variables.
**When to Use:**
* Removing entire token sets
* Cleaning up unused collections
* Resetting design system sections
**Usage:**
```javascript theme={null}
figma_delete_variable_collection({
collectionId: "VariableCollectionId:123:456"
})
```
**⚠️ Warning:** This deletes ALL variables in the collection. Cannot be undone programmatically.
***
### `figma_add_mode`
Add a new mode to an existing collection.
**When to Use:**
* Adding theme variants (Dark mode, High Contrast)
* Adding responsive breakpoints (Mobile, Tablet, Desktop)
* Adding brand variants
**Usage:**
```javascript theme={null}
figma_add_mode({
collectionId: "VariableCollectionId:123:456",
modeName: "Dark"
})
```
**Parameters:**
* `collectionId` (required): Collection to add mode to
* `modeName` (required): Name for the new mode
**Returns:**
* Updated collection with new mode ID
**Note:** Figma has limits on the number of modes per collection (varies by plan).
***
### `figma_rename_mode`
Rename an existing mode in a collection.
**When to Use:**
* Fixing mode names
* Updating naming conventions
* Making mode names more descriptive
**Usage:**
```javascript theme={null}
figma_rename_mode({
collectionId: "VariableCollectionId:123:456",
modeId: "1:0",
newName: "Light Theme"
})
```
**Parameters:**
* `collectionId` (required): Collection containing the mode
* `modeId` (required): Mode ID to rename
* `newName` (required): New name for the mode
***
### `figma_batch_create_variables`
Create multiple variables in a single operation — up to 50x faster than calling `figma_create_variable` repeatedly.
**When to Use:**
* Creating multiple design tokens at once (e.g., a full color palette)
* Importing variables from an external source
* Any time you need to create more than 2-3 variables
**Usage:**
```javascript theme={null}
figma_batch_create_variables({
collectionId: "VariableCollectionId:123:456",
variables: [
{
name: "colors/primary/500",
resolvedType: "COLOR",
description: "Primary brand color",
valuesByMode: { "1:0": "#3B82F6", "1:1": "#60A5FA" }
},
{
name: "colors/primary/600",
resolvedType: "COLOR",
valuesByMode: { "1:0": "#2563EB", "1:1": "#3B82F6" }
},
{
name: "spacing/md",
resolvedType: "FLOAT",
valuesByMode: { "1:0": 16 }
}
]
})
```
**Parameters:**
* `collectionId` (required): Collection ID to create all variables in
* `variables` (required): Array of 1-100 variable definitions, each with:
* `name` (required): Variable name (use `/` for grouping)
* `resolvedType` (required): `"COLOR"`, `"FLOAT"`, `"STRING"`, or `"BOOLEAN"`
* `description` (optional): Variable description
* `valuesByMode` (optional): Object mapping mode IDs to values
**Returns:**
```json theme={null}
{
"success": true,
"message": "Batch created 3 variables (0 failed)",
"created": 3,
"failed": 0,
"results": [
{ "success": true, "name": "colors/primary/500", "id": "VariableID:1:1" },
{ "success": true, "name": "colors/primary/600", "id": "VariableID:1:2" },
{ "success": true, "name": "spacing/md", "id": "VariableID:1:3" }
]
}
```
**Performance:** Executes in a single Plugin API roundtrip. 10-50x faster than individual calls for bulk operations.
***
### `figma_batch_update_variables`
Update multiple variable values in a single operation — up to 50x faster than calling `figma_update_variable` repeatedly.
**When to Use:**
* Updating many token values at once (e.g., theme refresh)
* Syncing variable values from an external source
* Any time you need to update more than 2-3 variables
**Usage:**
```javascript theme={null}
figma_batch_update_variables({
updates: [
{ variableId: "VariableID:1:1", modeId: "1:0", value: "#2563EB" },
{ variableId: "VariableID:1:2", modeId: "1:0", value: "#1D4ED8" },
{ variableId: "VariableID:1:3", modeId: "1:0", value: 20 }
]
})
```
**Parameters:**
* `updates` (required): Array of 1-100 updates, each with:
* `variableId` (required): Variable ID to update
* `modeId` (required): Mode ID to update value in
* `value` (required): New value (COLOR: hex `"#FF0000"`, FLOAT: number, STRING: text, BOOLEAN: true/false)
**Returns:**
```json theme={null}
{
"success": true,
"message": "Batch updated 3 variables (0 failed)",
"updated": 3,
"failed": 0,
"results": [
{ "success": true, "variableId": "VariableID:1:1", "name": "colors/primary/500" },
{ "success": true, "variableId": "VariableID:1:2", "name": "colors/primary/600" },
{ "success": true, "variableId": "VariableID:1:3", "name": "spacing/md" }
]
}
```
**Performance:** Executes in a single Plugin API roundtrip. 10-50x faster than individual calls for bulk updates.
***
### `figma_setup_design_tokens`
Create a complete design token structure in one atomic operation: collection, modes, and all variables.
**When to Use:**
* Setting up a new design system from scratch
* Importing CSS custom properties or design tokens into Figma
* Creating themed token sets (Light/Dark) with all values at once
* Bootstrapping a new project with a full token foundation
**Usage:**
```javascript theme={null}
figma_setup_design_tokens({
collectionName: "Brand Tokens",
modes: ["Light", "Dark"],
tokens: [
{
name: "color/background",
resolvedType: "COLOR",
description: "Page background",
values: { "Light": "#FFFFFF", "Dark": "#1A1A2E" }
},
{
name: "color/text",
resolvedType: "COLOR",
values: { "Light": "#111827", "Dark": "#F9FAFB" }
},
{
name: "spacing/page",
resolvedType: "FLOAT",
values: { "Light": 24, "Dark": 24 }
},
{
name: "color/action/primary",
resolvedType: "COLOR",
// Alias values: DTCG brace references resolve to real variable aliases
values: { "Light": "{color.background}", "Dark": "{color.background}" }
}
]
})
```
**Parameters:**
* `collectionName` (required): Name for the new collection
* `modes` (required): Array of 1-4 mode names (first becomes default)
* `tokens` (required): Array of 1-100 token definitions, each with:
* `name` (required): Token name (use `/` for grouping)
* `resolvedType` (required): `"COLOR"`, `"FLOAT"`, `"STRING"`, or `"BOOLEAN"`
* `description` (optional): Token description
* `values` (required): Object mapping **mode names** (not IDs) to values. A value can be a literal **or a DTCG brace reference** (`"{color.blue.600}"`, set-qualified forms like `"{primitives.color.blue.600}"` too) — resolved via `createVariableAlias` against both variables created in the same call and variables that already exist in the file.
**Alias resolution:** creation runs in two passes — all variables are created first, then values are applied — so **forward references within one call resolve** (a semantic token can reference a primitive defined later in the same `tokens` array). Unresolvable references warn per-item without failing the batch. Semantic collections no longer require raw `figma_execute` scripting.
**Returns:**
```json theme={null}
{
"success": true,
"message": "Created collection 'Brand Tokens' with 2 modes and 3 tokens (0 failed)",
"collectionId": "VariableCollectionId:1:1",
"collectionName": "Brand Tokens",
"modes": { "Light": "1:0", "Dark": "1:1" },
"created": 3,
"failed": 0,
"results": [
{ "success": true, "name": "color/background", "id": "VariableID:1:1" },
{ "success": true, "name": "color/text", "id": "VariableID:1:2" },
{ "success": true, "name": "spacing/page", "id": "VariableID:1:3" }
]
}
```
**Key Difference from Other Tools:** Values are keyed by **mode name** (e.g., `"Light"`, `"Dark"`) instead of mode ID — the tool resolves names to IDs internally.
**Performance:** Creates everything in a single Plugin API roundtrip. Ideal for bootstrapping entire token systems.
***
## 🧩 Component Tools
> **⚠️ Requires Desktop Bridge Plugin**: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using `figma_pair_plugin` to connect through the cloud relay.
### `figma_search_components`
Search for components by name or description. Supports both local file search and cross-file published library search.
**Mode:** Local (not available in Cloud Mode)
**When to Use:**
* Finding existing components to instantiate
* Discovering available UI building blocks
* Searching a published design system library from another file
* Checking if a component already exists before creating
**Usage:**
```javascript theme={null}
// Search local file (existing behavior)
figma_search_components({
query: "Button"
})
// Search a published library by file key
figma_search_components({
query: "Button",
libraryFileKey: "abc123XYZ"
})
// Search a published library by URL
figma_search_components({
query: "Card",
libraryFileUrl: "https://www.figma.com/design/abc123/My-Design-System"
})
```
**Parameters:**
* `query` (optional): Search term to match against component names or descriptions
* `category` (optional): Filter by category
* `libraryFileKey` (optional): File key of a published library for cross-file search
* `libraryFileUrl` (optional): URL of a published library file (alternative to libraryFileKey)
* `limit` (optional): Max results (default: 10, max: 25)
* `offset` (optional): Pagination offset
**Returns:**
* Array of matching components with keys, names, variant info, and `source` ("local" or "library")
**Note:** Library search requires `FIGMA_ACCESS_TOKEN` environment variable.
***
### `figma_get_library_components`
Discover published components from a shared/team library file. This is the primary tool for cross-file design system workflows.
**When to Use:**
* Browsing all components in a published design system
* Getting component keys for instantiation from another file
* Auditing a library's component inventory with variant detail
**Usage:**
```javascript theme={null}
// By file key
figma_get_library_components({
libraryFileKey: "abc123XYZ",
query: "Button"
})
// By URL with full variant detail
figma_get_library_components({
libraryFileUrl: "https://www.figma.com/design/abc123/My-Design-System",
includeVariants: true,
limit: 50
})
```
**Parameters:**
* `libraryFileUrl` (optional): URL of the library file
* `libraryFileKey` (optional): File key of the library file
* `query` (optional): Filter by component name or description
* `limit` (optional): Max results (default: 25, max: 100)
* `offset` (optional): Pagination offset
* `includeVariants` (optional): Include individual variant components (default: false)
**Returns:**
* Component sets with variant counts and keys, standalone components, summary stats, and instantiation examples
**Workflow:**
1. Call `figma_get_library_components` with your design system file
2. Find the component you want and note its `key`
3. Call `figma_instantiate_component` with that `componentKey` — the component is imported from the published library automatically
**Note:** Requires `FIGMA_ACCESS_TOKEN` environment variable. Local mode only.
***
### `figma_get_library_component_by_key`
Resolve a single library component to its full property definitions, variants, and visual specs — using **only the component key**, with no need to first find the source library file's URL.
This is the missing link between "I see a component key in search results" (from `figma_search_components`, `figma_get_library_components`, or the official Figma MCP's `search_design_system`) and "I'm ready to instantiate a specific variant."
**When to Use:**
* You have a component key (40-char hex) from any search tool and want to inspect what properties / variants it exposes before instantiating
* You need each variant's published key so `figma_instantiate_component` can target a specific one
* You want per-variant visual specs (fills, strokes, padding, typography) for code-generation fidelity
**How It Works:**
1. Tries Figma REST `/v1/component_sets/{key}` first (most common case — buttons, inputs, anything with variants)
2. On 404, falls back to `/v1/components/{key}` (standalone components)
3. Extracts `file_key` + `node_id` from the response
4. Fetches the node at `depth=2` to read `componentPropertyDefinitions` and the variant subtree
5. For COMPONENT\_SETs, also fetches the source file's `/components` list **in parallel** so each variant child node can be mapped to its published variant key
**Usage:**
```javascript theme={null}
// Resolve a component set by key
figma_get_library_component_by_key({
componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197"
})
// Summary mode — properties and variant names only (no visual specs)
figma_get_library_component_by_key({
componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197",
format: "summary"
})
// Skip visual specs entirely (faster, smaller response)
figma_get_library_component_by_key({
componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197",
includeVisualSpecs: false
})
```
**Parameters:**
* `componentKey` (required): The 40-char hex component key from search results. Works for both COMPONENT\_SET and standalone COMPONENT keys.
* `includeVisualSpecs` (optional, default `true`): Include per-variant fills/strokes/padding/typography. Auto-stripped if the response would exceed 500KB.
* `format` (optional, `"full"` | `"summary"`, default `"full"`): `summary` omits per-variant visual specs. Auto-downgrades on large responses.
**Returns:**
* `resolvedAs`: `"COMPONENT_SET"` or `"COMPONENT"`
* `fileKey` + `nodeId`: source file + node id
* `name`, `description`, `thumbnail_url`, `containing_frame`, `user`, `created_at`, `updated_at`
* `properties`: `componentPropertyDefinitions` (VARIANT / BOOLEAN / TEXT / INSTANCE\_SWAP)
* `variants[]`: each with `name`, `nodeId`, `key` (the value to pass to `figma_instantiate_component`), and optional `visualSpec`
* `visualSpec`: root-level fills/strokes/effects/padding/typography, plus `sizing` (fixed/hug/fill and min/max width and height)
* `bounds`: width × height of the component set
* `compression` (only when stripped): `{ originalSizeKB, finalSizeKB, strippedVisualSpecs: true }`
* `warnings[]`: non-fatal issues (e.g. variant-key resolution skipped)
**Plan requirements:** Works on **all Figma plans**. Requires `FIGMA_ACCESS_TOKEN` with `library_assets:read` + `files:read` scopes.
***
### `figma_get_library_variables`
List every variable from team libraries the current file has subscribed. Uses the **Plugin API path** (`figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync()` + `getVariablesInLibraryCollectionAsync()`), which works on every Figma plan — unlike the REST `/v1/files/{key}/variables/local` endpoint which is Enterprise-only.
**When to Use:**
* Inventory what design tokens (colors, spacing, typography sizes) are available from your subscribed libraries
* Find the `key` of a specific library variable so you can import it
* Build a design system overview that includes shared tokens (not just file-local ones)
**Usage:**
```javascript theme={null}
// Everything subscribed
figma_get_library_variables()
// Filter by library name (case-insensitive substring)
figma_get_library_variables({ libraryName: "Northright" })
// Filter to only color tokens from a specific collection
figma_get_library_variables({
libraryName: "Altitude",
collectionName: "Colors",
resolvedType: "COLOR"
})
```
**Parameters:**
* `libraryName` (optional): Case-insensitive substring filter on the source library's name
* `collectionName` (optional): Case-insensitive substring filter on the collection name within a library
* `resolvedType` (optional, `"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"`): Filter to a single token type. Auto-prunes empty collections after filtering.
**Returns:**
* `summary`: `{ totalCollections, totalVariables }`
* `filters`: echoed back so you can verify
* `collections[]`: `[{ libraryName, collectionKey, collectionName, variableCount, variables: [{ key, name, resolvedType }] }]`
**Plan requirements:** Works on **all Figma plans**. Requires the Desktop Bridge plugin to be running. Only libraries the user has explicitly enabled in the current file appear (subscribing libraries is UI-only — the Plugin API cannot subscribe libraries for you).
***
### `figma_import_library_variable`
Import a single variable from a subscribed library into the current file. After import, the variable becomes locally addressable by its returned `id` and can be passed to any tool that binds variables to nodes (`figma_set_fills`, `figma_update_variable`, etc.). Idempotent — calling twice returns the same local id.
**When to Use:**
* After `figma_get_library_variables`, you've picked a token and want to use it in the current file
* You're building a composition that mixes file-local variables with library tokens
**Usage:**
```javascript theme={null}
// Step 1: find the variable
const list = await figma_get_library_variables({
libraryName: "Northright",
resolvedType: "COLOR"
});
// Step 2: import it
const result = await figma_import_library_variable({
variableKey: list.collections[0].variables[0].key
});
// Step 3: use the returned id to bind it to a node
await figma_set_fills({
nodeId: "...",
fills: [{ type: "SOLID", boundVariables: { color: { type: "VARIABLE_ALIAS", id: result.imported.id } } }]
});
```
**Parameters:**
* `variableKey` (required): The variable's library key from `figma_get_library_variables` (the `collections[].variables[].key` field — distinct from the local `id` you'll get back).
**Returns:**
* `imported`: `{ id, key, name, resolvedType, description, variableCollectionId, remote }`
* `usage.bind`: a hint string showing how to use the returned `id` with binding tools
**Errors:**
* If the source library isn't subscribed by the current file, returns a specific hint pointing to **Figma > Assets panel > Libraries**. The Plugin API rejects with a generic message; this tool detects the pattern and explains it.
**Plan requirements:** Works on **all Figma plans**. Requires the Desktop Bridge plugin.
***
### `figma_get_component_details`
Get detailed information about a specific component.
**Mode:** Local (not available in Cloud Mode)
**Usage:**
```javascript theme={null}
figma_get_component_details({
componentKey: "abc123def456" // Component key from search results
})
```
**Parameters:**
* `componentKey` (required): The component's key identifier
**Returns:**
* Full component details including properties, variants, and metadata
***
### `figma_instantiate_component`
Create an instance of a component on the canvas.
**When to Use:**
* Adding existing components to your design
* Building compositions from component library
* Creating layouts using design system components
**Usage:**
```javascript theme={null}
figma_instantiate_component({
componentKey: "abc123def456",
x: 100, // X position
y: 200, // Y position
overrides: { // Property overrides
"Button Label": "Click Me",
"Show Icon": true
}
})
```
**Parameters:**
* `componentKey` (required): Component key to instantiate
* `x` (optional): X position on canvas
* `y` (optional): Y position on canvas
* `overrides` (optional): Property overrides for the instance
**Returns:**
* Created instance with node ID
***
### `figma_set_instance_properties`
Set component properties on an instance. Use this instead of editing an instance's text layers directly: components expose TEXT, BOOLEAN, INSTANCE\_SWAP, and VARIANT properties that control their content.
**Mode:** Local / Cloud
**Usage:**
```javascript theme={null}
figma_set_instance_properties({
nodeId: '1:234', // must be an INSTANCE node
properties: {
'Label': 'Save', // TEXT or VARIANT: string
'Show Icon': false // BOOLEAN: boolean
}
})
```
The tool adds the `#nodeId` suffix Figma uses for TEXT, BOOLEAN, and INSTANCE\_SWAP property names. Slot content can't be set this way; use `figma_append_to_slot`.
***
### `figma_create_component_set`
Create a component set with variants in one declarative call — replaces hand-written `figma_execute` + `figma.combineAsVariants()` scripts.
**When to Use:**
* Building a component's full variant matrix (states × sizes × …) from a single base component
* Combining existing loose components into a proper component set
* Any time you'd otherwise script `combineAsVariants` by hand
**Two modes:**
1. **Generate from a base component** — pass `baseComponentId` + `properties` (the variant axes matrix). The base is cloned for every combination of the axes, each variant named `Prop=Value` comma-joined (e.g. `State=hover, Size=sm`), then combined into a set. The base component itself becomes the **first variant** (same node ID), so existing instances of the base survive as instances of that variant.
2. **Combine existing components** — pass `componentIds`, optionally with `variantProperties` (aligned 1:1 by index) to rename each component to `Prop=Value` form before combining. Property names and values must not contain `=` or `,`. On any pre-combine failure, a unified rollback restores the components' original names.
**Usage (axes matrix):**
```javascript theme={null}
figma_create_component_set({
baseComponentId: "123:456",
properties: {
State: ["default", "hover", "disabled"],
Size: ["sm", "lg"]
}, // → 6 variants: State=default, Size=sm … State=disabled, Size=lg
name: "Button",
autoArrange: true // labeled grid inside a white container
})
```
**Usage (combine existing components):**
```javascript theme={null}
figma_create_component_set({
componentIds: ["123:1", "123:2", "123:3"],
variantProperties: [
{ State: "default" },
{ State: "hover" },
{ State: "disabled" }
],
name: "Button"
})
```
**Parameters:**
* `baseComponentId` (optional): Node ID of an existing COMPONENT to use as the base. Mutually exclusive with `componentIds`.
* `properties` (required with `baseComponentId`): Variant property axes — `{ State: ["default", "hover"], Size: ["sm", "lg"] }`. Max 100 combinations.
* `componentIds` (optional): Node IDs of existing COMPONENT nodes to combine. Components already inside a component set are rejected.
* `variantProperties` (optional, only with `componentIds`): One property map per component, aligned by index. Without it, existing names are kept (names lacking `=` become `Property 1=`).
* `name` (optional): Name for the component set (defaults to Figma's derived name)
* `parentId` (optional): Container frame/section to create the set in (defaults to current page)
* `position` (optional): `{ x, y }` position within the parent
* `autoArrange` (optional, default `false`): Lay the new set out as a labeled grid (columns = last property, rows = other properties) inside a white container — same in-place layout as `figma_arrange_component_set`
* `arrangeOptions` (optional): `gap`, `cellPadding`, `columnProperty` — used when `autoArrange` is true
**Naming convention:** Figma derives the variant property definitions from the `Prop=Value` names; they live on the **SET** (`componentPropertyDefinitions`), not on individual variants.
**Size guidance:** hard cap **100 variants**. The timeout auto-scales with variant count (\~1.2s/variant, 30s floor / 2min cap) at every hop, but above **\~40 variants** the single-pass clone+combine gets slow and the response carries a warning — prefer splitting large matrices into multiple sets (e.g. one set per Size).
**Returns:**
* The component set's `id`, `name`, and key
* Each variant's `name`, `nodeId`, and **`key`** — instantiate with a *variant's* key via `figma_instantiate_component`, not the set's key
***
### `figma_arrange_component_set`
Organize component variants into a professional component set with labels and proper structure.
**When to Use:**
* After creating multiple component variants
* Organizing messy component sets
* Adding row/column labels to variant grids
* Getting the purple dashed border Figma styling
**Usage:**
```javascript theme={null}
figma_arrange_component_set({
componentSetId: "123:456", // Component set to arrange
options: {
gap: 24, // Gap between cells
cellPadding: 20, // Padding inside cells
columnProperty: "State" // Property to use for columns
}
})
```
**Parameters:**
* `componentSetId` (optional): ID of component set to arrange (uses selection if not provided)
* `componentSetName` (optional): Find component set by name
* `options` (optional): Layout options
* `gap`: Gap between grid cells (default: 24)
* `cellPadding`: Padding inside each cell (default: 20)
* `columnProperty`: Property to use for columns (default: auto-detect, usually "State")
**Returns:**
* Arranged component set with:
* White container frame with title
* Row labels (vertically centered)
* Column headers (horizontally centered)
* Purple dashed border (Figma's native styling)
**Example Result:**
```
┌─────────────────────────────────────────┐
│ Button │
│ Default Hover Pressed Disabled
│ ┌─────────────────────────────────────┐
│ │ Primary/Small [btn] [btn] [btn] [btn]
│ │ Primary/Medium [btn] [btn] [btn] [btn]
│ │ Primary/Large [btn] [btn] [btn] [btn]
│ │ Secondary/... [btn] [btn] [btn] [btn]
│ └─────────────────────────────────────┘
└─────────────────────────────────────────┘
```
***
### `figma_create_slot`
Add a Figma Slot to a component via the GA `createSlot()` API. The linked SLOT component property is created automatically and named after the slot — renaming the slot later renames the property.
**Mode:** Local / Cloud (requires Desktop Bridge)
```javascript theme={null}
figma_create_slot({
nodeId: "123:456", // COMPONENT node (standalone OR a variant inside a set)
name: "Content", // optional slot layer name
width: 320, height: 140, // optional initial size (each independent)
layoutMode: "VERTICAL" // optional: NONE | HORIZONTAL | VERTICAL (GRID rejected by Figma)
})
// → { success, slot: { id, name, propertyKey, width, height, layoutMode } }
```
For a COMPONENT\_SET, call once per variant component — each variant gets its own SlotNode pointing at a shared property.
### `figma_get_slots`
List slots on a COMPONENT, COMPONENT\_SET (aggregated across variants, each tagged with `variantId`/`variantName`), or INSTANCE. Returns ids, names, property keys, dimensions, layout mode, and current children. Use on an instance before `figma_append_to_slot` to discover slot names.
**Mode:** Local / Cloud (requires Desktop Bridge)
### `figma_append_to_slot`
Populate a slot on a component instance. Slot content **cannot** be set through `figma_set_instance_properties` — Figma rejects slot values there by design; this tool is the population path.
**Mode:** Local / Cloud (requires Desktop Bridge)
```javascript theme={null}
// Clone an existing node into the slot
figma_append_to_slot({
instanceId: "123:789", slotName: "Content", // or slotId directly
sourceNodeId: "123:111", // node to clone (clone: false moves it)
clearExisting: true // optional: replace current content
})
// Or create new content in place
figma_append_to_slot({
instanceId: "123:789", slotName: "Content",
nodeType: "TEXT", // FRAME | RECTANGLE | ELLIPSE | TEXT | LINE | POLYGON | STAR | VECTOR
properties: { text: "Hello", name: "Label", width: 200, height: 24 }
})
```
Notes: main components can't be appended (clone an instance instead); in NONE-layout slots, clones snap to the slot origin so they stay visible; `clearExisting` only clears after the new content validates.
### `figma_reset_slot`
Clear all content from a slot on an instance. Takes `slotId` or `instanceId` + `slotName`.
**Mode:** Local / Cloud (requires Desktop Bridge)
### `figma_add_slot_property`
Retrofit an existing frame as a slot: adds a SLOT component property and binds the frame to it via `componentPropertyReferences.slotContentId`. Prefer `figma_create_slot` for new slots. Supports `description` and `preferredValues` (the components the slot should accept). Works on standalone components and on component sets (bind a frame inside any variant). Existing property references on the frame are preserved.
**Mode:** Local / Cloud (requires Desktop Bridge)
***
### `figma_set_description`
Add or update a description on a component, component set, or style.
**When to Use:**
* Documenting components for developers
* Adding usage guidelines
* Writing design system documentation
**Usage:**
```javascript theme={null}
figma_set_description({
nodeId: "123:456",
description: "Primary action button. Use for main CTAs.\n\n**Variants:**\n- Size: Small, Medium, Large\n- State: Default, Hover, Pressed, Disabled"
})
```
**Parameters:**
* `nodeId` (required): Node ID of component/style to document
* `description` (required): Description text (supports markdown)
**Returns:**
* Confirmation with updated node info
**Note:** Descriptions appear in Figma's Dev Mode for developers.
***
## 🔧 Node Manipulation Tools
### `figma_resize_node`
Resize a node to specific dimensions.
**Usage:**
```javascript theme={null}
figma_resize_node({
nodeId: "123:456",
width: 200,
height: 100
})
```
***
### `figma_move_node`
Move a node to a specific position.
**Usage:**
```javascript theme={null}
figma_move_node({
nodeId: "123:456",
x: 100,
y: 200
})
```
***
### `figma_clone_node`
Create a copy of a node.
**Usage:**
```javascript theme={null}
figma_clone_node({
nodeId: "123:456"
})
```
**Returns:**
* New node ID of the clone
***
### `figma_delete_node`
Delete a node from the canvas.
**Usage:**
```javascript theme={null}
figma_delete_node({
nodeId: "123:456"
})
```
**⚠️ Warning:** This cannot be undone programmatically.
***
### `figma_rename_node`
Rename a node.
**Usage:**
```javascript theme={null}
figma_rename_node({
nodeId: "123:456",
newName: "Header Section"
})
```
***
### `figma_set_text`
Set the text content of a text node.
**Usage:**
```javascript theme={null}
figma_set_text({
nodeId: "123:456",
characters: "Hello World"
})
```
***
### `figma_set_fills`
Set the fill colors of a node.
**Usage:**
```javascript theme={null}
figma_set_fills({
nodeId: "123:456",
fills: [{ type: "SOLID", color: "#FF0000" }]
})
```
***
### `figma_set_strokes`
Set the stroke colors of a node.
**Usage:**
```javascript theme={null}
figma_set_strokes({
nodeId: "123:456",
strokes: [{ type: "SOLID", color: "#000000" }],
strokeWeight: 2
})
```
***
### `figma_create_child`
Create a child node inside a parent.
**Usage:**
```javascript theme={null}
figma_create_child({
parentId: "123:456",
type: "FRAME",
name: "New Frame"
})
```
***
## 🏷️ Component Property Tools
### `figma_add_component_property`
Add a new property to a component.
**Usage:**
```javascript theme={null}
figma_add_component_property({
nodeId: "123:456",
propertyName: "Show Icon",
propertyType: "BOOLEAN",
defaultValue: true
})
```
**Parameters:**
* `nodeId` (required): Component node ID
* `propertyName` (required): Name for the new property
* `propertyType` (required): `"BOOLEAN"`, `"TEXT"`, `"INSTANCE_SWAP"`, or `"VARIANT"`
* `defaultValue` (required): Default value for the property
***
### `figma_edit_component_property`
Edit an existing component property.
**Usage:**
```javascript theme={null}
figma_edit_component_property({
nodeId: "123:456",
propertyName: "Label",
newValue: {
name: "Button Text",
defaultValue: "Click me"
}
})
```
***
### `figma_delete_component_property`
Remove a property from a component.
**Usage:**
```javascript theme={null}
figma_delete_component_property({
nodeId: "123:456",
propertyName: "Deprecated Prop"
})
```
***
## 📦 Design System Kit
### `figma_get_design_system_kit`
Extract your entire design system — tokens, components, and styles — in a single call. This is the **preferred tool** for design system extraction, replacing separate calls to `figma_get_variables`, `figma_get_component`, and `figma_get_styles`.
Returns component visual specs (exact colors, padding, typography, layout), rendered screenshots, token values per mode (light/dark), and resolved style values. Ideal for AI code generation — the `visualSpec` data provides pixel-accurate reproduction data.
**Available in both Local and Remote modes.**
### `figma_audit_design_system_report`
Run a deterministic, Lighthouse-style health audit of the current design system and get the scored report back as data — no UI, no MCP Apps support, no `ENABLE_MCP_APPS` flag required. Same scoring engine as the Design System Dashboard app: **Naming & Semantics, Token Architecture, Component Metadata, Accessibility, Consistency, Coverage** — each 0–100, weighted into an overall score.
```javascript theme={null}
// Bounded readable summary (default)
figma_audit_design_system_report({})
// Chunked drill-down: full findings for ONE category
figma_audit_design_system_report({ category: "accessibility" })
// Complete scored JSON (examples/locations clamped)
figma_audit_design_system_report({ format: "full" })
// Re-crawl after editing the file (results cache for ~5 minutes)
figma_audit_design_system_report({ forceRefresh: true })
```
**Built for heavy files and small context windows:**
* Component data is fetched **live-first** through the Desktop Bridge — one page per plugin roundtrip (30s cap each, failures isolated per page) — with the REST published-library endpoints as fallback. The chosen source is disclosed in the report (`bridge-live` / `rest-published` / `none`) because a published snapshot can be stale: scores from different sources are not comparable.
* The bridge crawl is **fileKey-verified**: if the plugin is connected to a different file than requested, the audit refuses the data and falls back to REST rather than silently scoring the wrong file.
* Raw audit data caches for 5 minutes, so a summary call plus per-category drill-downs cost **one crawl**.
* The default summary output stays bounded regardless of file size; use `category` for detail instead of `format: "full"` when working interactively.
**Every finding ends with a remediation verdict** — whether this MCP can fix it (`design`: auto-fixable via write tools like `figma_rename_variable` / `figma_set_description` / `figma_rename_mode`), can fix it after a design decision (`design-assisted`: e.g. contrast hues, alias tiering), or the work needs a human (`manual`: e.g. missing core components). Reports name the exact tools, so the natural next step is asking your agent to apply the fixes.
**Local Mode only** (requires the Desktop Bridge for live data; REST fallback works with a Figma token).
**Usage:**
```javascript theme={null}
// Full design system extraction
figma_get_design_system_kit({
fileKey: "abc123def"
})
// Only tokens and components, with images
figma_get_design_system_kit({
fileKey: "abc123def",
include: ["tokens", "components"],
includeImages: true
})
// Specific components only
figma_get_design_system_kit({
fileKey: "abc123def",
include: ["components"],
componentIds: ["1:234", "5:678"]
})
// Compact format for large design systems
figma_get_design_system_kit({
fileKey: "abc123def",
format: "compact"
})
```
**Parameters:**
| Parameter | Type | Default | Description |
| - | - | - | - |
| `fileKey` | string | *(current file)* | Figma file key. If omitted, extracted from the current browser URL. |
| `include` | array | `["tokens", "components", "styles"]` | Which sections to include. |
| `componentIds` | array | *(all)* | Specific component node IDs to include. If omitted, all published components are returned. |
| `includeImages` | boolean | `false` | Include image URLs for components (adds latency). |
| `format` | `"full"` \| `"summary"` \| `"compact"` | `"full"` | Response detail level. |
**Format options:**
* **`full`** — Complete data with visual specs and resolved style values. Best for implementing specific components.
* **`summary`** — Strips variant-level visual specs (medium payload). Good for overview + a few deep-dives.
* **`compact`** — Only names, types, and property definitions. Best for large design systems or getting an inventory.
**Adaptive compression:** Regardless of format setting, responses are automatically compressed if they exceed safe size limits for the AI context window.
**Returns:**
* `tokens` — Variables grouped by collection, with full mode support (light/dark/etc.)
* `components` — Published components with property definitions, variant specs, and visual specs (fills, strokes, effects, corner radius, layout, typography)
* `styles` — Color, text, and effect styles with resolved values
* `ai_instruction` — Guidance for the AI on how to use the extracted data
* `errors` — Any sections that failed to extract (partial results are still returned)
**Example response structure:**
```json theme={null}
{
"fileKey": "abc123",
"fileName": "My Design System",
"generatedAt": "2025-01-15T10:30:00Z",
"format": "full",
"tokens": {
"collections": [{
"name": "Colors",
"modes": [{ "name": "Light" }, { "name": "Dark" }],
"variables": [{
"name": "primary",
"type": "COLOR",
"valuesByMode": {
"Light": { "r": 0.26, "g": 0.46, "b": 1 },
"Dark": { "r": 0.37, "g": 0.64, "b": 0.98 }
}
}]
}],
"summary": { "totalCollections": 3, "totalVariables": 45 }
},
"components": {
"items": [{
"name": "Button",
"properties": { "variant": { "type": "VARIANT", "values": ["primary", "secondary"] } },
"variants": [{ "name": "variant=primary", "id": "1:234" }],
"visualSpec": {
"fills": [{ "type": "SOLID", "color": "#4375FF" }],
"cornerRadius": 8,
"layout": { "mode": "HORIZONTAL", "paddingTop": 12, "paddingLeft": 24 },
"sizing": { "horizontal": "HUG", "vertical": "HUG", "minWidth": 320, "maxWidth": 640 }
}
}],
"summary": { "totalComponents": 12, "totalComponentSets": 5 }
},
"styles": {
"items": [{ "name": "Primary/Default", "styleType": "FILL", "resolvedValue": { "fills": [{ "color": "#4375FF" }] } }],
"summary": { "totalStyles": 28 }
}
}
```
***
## 📊 Design System Summary Tools
### `figma_get_design_system_summary`
Get a high-level overview of the design system in the current file.
**Mode:** Local (not available in Cloud Mode)
**Usage:**
```javascript theme={null}
figma_get_design_system_summary()
```
**Returns:**
* Component count and categories
* Variable collections and counts
* Style summary (colors, text, effects)
* Page structure overview
***
### `figma_get_token_values`
Get all variable values organized by collection and mode.
**Mode:** Local (not available in Cloud Mode)
**Usage:**
```javascript theme={null}
figma_get_token_values({
collectionName: "Brand Colors" // Optional: filter by collection
})
```
**Returns:**
* Variables organized by collection
* Values for each mode
* Variable metadata
***
## AI Decision Guide: Which Tool to Use?
### For Design System Extraction
| Task | Tool |
| - | - |
| **Get everything at once** (tokens + components + styles) | `figma_get_design_system_kit` |
| Get only tokens/variables | `figma_get_design_system_kit` with `include: ["tokens"]` |
| Get only components with visual specs | `figma_get_design_system_kit` with `include: ["components"]` |
| Get variables with multi-format export (CSS, Tailwind, Sass) | `figma_get_variables` |
| Get a quick overview (counts, categories) | `figma_get_design_system_summary` |
| Feed a design system to an AI code generator | `figma_get_design_system_kit` |
> **Tip:** Prefer `figma_get_design_system_kit` over calling `figma_get_variables`, `figma_get_component`, and `figma_get_styles` separately. It returns all three in a single optimized call with visual specs and resolved values.
### For Design Creation
| Task | Tool | Example |
| - | - | - |
| Create UI components | `figma_execute` | Buttons, cards, modals |
| Create frames/layouts | `figma_execute` | Auto-layout containers |
| Add text | `figma_execute` | Labels, headings, paragraphs |
| Create shapes | `figma_execute` | Icons, decorations |
| Modify existing elements | `figma_execute` | Change colors, resize |
| Create pages | `figma_execute` | Organize file structure |
### For Variable Management
| Task | Tool |
| - | - |
| Create new token collection | `figma_create_variable_collection` |
| Add a single design token | `figma_create_variable` |
| Add multiple design tokens (3+) | `figma_batch_create_variables` |
| Change a single token value | `figma_update_variable` |
| Change multiple token values (3+) | `figma_batch_update_variables` |
| Set up a full token system from scratch | `figma_setup_design_tokens` |
| Reorganize token names | `figma_rename_variable` |
| Remove tokens | `figma_delete_variable` |
| Add themes (Light/Dark) | `figma_add_mode` |
| Rename themes | `figma_rename_mode` |
### For Design-Code Parity
| Task | Tool |
| - | - |
| Compare Figma specs against code | `figma_check_design_parity` |
| Generate component documentation | `figma_generate_component_doc` |
| Audit component before sign-off | `figma_check_design_parity` |
| Create design system reference docs | `figma_generate_component_doc` |
| Notify designers of parity drift | `figma_post_comment` |
| Review existing feedback threads | `figma_get_comments` |
| Clean up resolved feedback | `figma_delete_comment` |
### Prerequisites Checklist
Before using write tools, ensure one of the following:
**Local Mode:**
1. ✅ Running in **Local Mode** (NPX/Git)
2. ✅ **Desktop Bridge plugin** is running in your Figma file
3. ✅ `figma_get_status` returns `setup.valid: true`
**Cloud Mode:**
1. ✅ **Desktop Bridge plugin** is running in your Figma file with Cloud Mode enabled
2. ✅ Paired via `figma_pair_plugin` (or natural language: "connect to my Figma plugin")
***
## 🔍 Design-Code Parity Tools
### `figma_check_design_parity`
Compare a Figma component's design specs against your code implementation. Produces a scored parity report with actionable fix items.
**When to Use:**
* Before sign-off on a component implementation
* During design system audits to catch drift between design and code
* To verify that code accurately reflects the design spec
**Usage:**
```javascript theme={null}
figma_check_design_parity({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '695:313',
codeSpec: {
visual: {
backgroundColor: '#FFFFFF',
borderColor: '#E4E4E7',
borderRadius: 12,
opacity: 1
},
spacing: {
paddingTop: 24,
paddingRight: 24,
paddingBottom: 24,
paddingLeft: 24,
gap: 24
},
componentAPI: {
props: [
{ name: 'className', type: 'string', required: false },
{ name: 'children', type: 'ReactNode', required: false }
]
},
metadata: {
name: 'Card',
filePath: 'src/components/card/card.tsx'
}
},
canonicalSource: 'design',
enrich: true
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL (uses current URL if omitted)
* `nodeId` (required): Component node ID
* `codeSpec` (required): Structured code-side data with sections:
* `visual`: backgroundColor, borderColor, borderRadius, opacity, shadow, etc.
* `spacing`: paddingTop/Right/Bottom/Left, gap, width, height, minWidth, maxWidth
* `typography`: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color
* `tokens`: usedTokens array, hardcodedValues array, tokenCoverage percentage
* `componentAPI`: props array (name, type, required, defaultValue, description)
* `accessibility`: role, ariaLabel, keyboardInteraction, focusManagement, contrastRatio
* `metadata`: name, filePath, version, status, tags, description
* `canonicalSource` (optional): Which source is truth — `"design"` (default) or `"code"`
* `enrich` (optional): Enable token/enrichment analysis (default: true)
**Returns:**
* `summary`: Total discrepancies, parity score (0-100), counts by severity (critical/major/minor/info), categories breakdown
* `discrepancies`: Array of property mismatches with category, severity, design value, code value, and suggestion
* `actionItems`: Structured fix instructions specifying which side to fix, which Figma tool or code change to apply
* `designData`: Raw Figma data extracted from the component (fills, strokes, spacing, properties)
* `codeData`: The codeSpec as provided
* `ai_instruction`: Structured presentation guide for consistent report formatting
**Parity Score:**
`score = max(0, 100 - (critical×15 + major×8 + minor×3 + info×1))`
**COMPONENT\_SET Handling:**
When given a COMPONENT\_SET node, the tool automatically resolves to the default variant (first child) for visual comparisons (fills, strokes, spacing, typography). Component property definitions and naming are read from the COMPONENT\_SET itself.
***
### `figma_generate_component_doc`
Generate platform-agnostic markdown documentation for a component by merging Figma design data with code-side info. Output is compatible with Docusaurus, Mintlify, ZeroHeight, Knapsack, Supernova, and any markdown-based docs platform.
**When to Use:**
* Generating design system component documentation
* Creating developer handoff documentation
* Building a component reference library
**Usage:**
```javascript theme={null}
figma_generate_component_doc({
fileUrl: 'https://figma.com/design/abc123',
nodeId: '695:313',
codeInfo: {
importStatement: "import { Button } from '@mylib/ui'",
props: [
{ name: 'variant', type: "'primary' | 'secondary' | 'ghost'", required: false, defaultValue: "'primary'", description: 'Visual style variant' },
{ name: 'size', type: "'sm' | 'md' | 'lg'", required: false, defaultValue: "'md'", description: 'Button size' }
],
events: [
{ name: 'onClick', payload: 'React.MouseEvent', description: 'Fires when clicked' }
],
usageExamples: [
{ title: 'Basic', code: '' },
{ title: 'Destructive', code: '' }
]
},
systemName: 'MyDesignSystem',
includeFrontmatter: true,
enrich: true
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL (uses current URL if omitted)
* `nodeId` (required): Component node ID
* `codeInfo` (optional): Code-side documentation info. Read the component source code first, then fill in relevant sections:
* `importStatement`: Import path
* `filePath`: Component file path
* `packageName`: Package name
* `props`: Array of prop definitions (name, type, required, defaultValue, description)
* `events`: Array of event definitions (name, payload, description)
* `slots`: Array of slot/sub-component definitions (name, description)
* `usageExamples`: Array of code examples (title, code, language)
* `changelog`: Version history entries (version, date, changes)
* `variantDefinition`: CVA or variant definition code block (rendered in Implementation section)
* `subComponents`: Array of composable sub-parts (name, description, element, dataSlot, props)
* `sourceFiles`: Array of related files (path, role, variants, description) — used for Source Files table and Storybook link detection
* `baseComponent`: Base component attribution (name, url, description) — e.g., "Built on shadcn/ui Alert"
* `sections` (optional): Toggle individual sections on/off (overview, statesAndVariants, visualSpecs, implementation, accessibility, changelog)
* `outputPath` (optional): Suggested file path for saving
* `systemName` (optional): Design system name for documentation headers
* `enrich` (optional): Enable enrichment analysis (default: true)
* `includeFrontmatter` (optional): Include YAML frontmatter metadata (default: true)
* `history` (optional): Pull an ongoing changelog instead of relying on hand-written `codeInfo.changelog` entries. Both sources are **off by default**, so existing callers are unaffected.
* `figma` (default `false`): Walk Figma version history and diff each consecutive pair **scoped to this component**, producing one row per version that actually changed it
* `git` (default `false`): Run `git log` for the component's source files. **Local mode only** — the Cloudflare Worker runtime has no filesystem or git binary
* `versions` (default `5`, max `20`): How many Figma versions to walk back
* `includeAutosaves` (default `false`): Include unlabeled Figma auto-saves. Prefers labeled versions, but **auto-falls back to auto-saves when a file has none** (see below), so you rarely need to set this
* `mode` (`summary` | `standard` | `detailed`, default `standard`): `detailed` names individual component properties and variable bindings instead of counting them
* `gitLimit` (default `10`, max `50`): How many commits to list
* `gitPaths` (optional): Explicit paths to log. Defaults to `codeInfo.filePath` plus every `codeInfo.sourceFiles[].path`
* `repoPath` (optional): Repo directory to run git in. Defaults to the server's working directory
**Returns:**
* `componentName`: Resolved component name
* `markdown`: Complete markdown documentation with frontmatter, overview, states & variants, visual specs, implementation, accessibility sections
* `includedSections`: Which sections were generated
* `dataSourceSummary`: What data sources were available (Figma enriched, code info, variables, styles)
* `historySummary`: Present only when `history` was requested — per-source row counts, API calls made, resolved git paths, and any degradation notes
* `suggestedOutputPath`: Where to save the file
* `ai_instruction`: Guidance for the AI on next steps (saving file, asking user for path)
**COMPONENT\_SET Handling:**
Documents the **whole set**, not one variant: colors are listed per variant; spacing, typography and layer structure are compared across every variant (a shared value prints once, differences are attributed to the variant property that drives them — `varies by **Size**`, an *Applies to* column, one anatomy tree per distinct structure). Property definitions are read from the COMPONENT\_SET. Hidden layers are included and labeled; gradients, shadows, blurs and opacity are reported; and if the component's tree is deeper than the extraction reaches (8 levels), the document says so rather than presenting itself as complete.
***
#### Component History (`history`)
When either history source is enabled, the generated doc gains a `## History` section in place of the pass-through `## Changelog`:
```javascript theme={null}
figma_generate_component_doc({
nodeId: '695:313',
codeInfo: { filePath: 'src/components/Button/Button.tsx' },
history: { figma: true, git: true, versions: 10, mode: 'detailed' }
})
```
```markdown theme={null}
## History
### Design history
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| v1.2 icon slot | 2026-03-01 | carol | Added 1 layer: `Icon` Property `Disabled` added (BOOLEAN) |
### Code history
| Commit | Date | Author | Message |
|--------|------|--------|---------|
| `a1b2c3d` | 2026-03-02 | TJ | feat(button): add icon slot |
### Release notes
| Version | Date | Changes |
|---------|------|---------|
| 2.1.0 | 2026-03-05 | Icon slot support |
```
Any `codeInfo.changelog` entries you pass are still rendered, folded in as **Release notes**. Frontmatter also gains `figmaVersion` / `figmaVersionDate` provenance — kept separate from the code-side `version` semver.
**Cost:** design history costs roughly one API call per version walked (N rows needs N+1 scoped node snapshots). Past-version snapshots are immutable and cached per process, so repeat runs on the same component are nearly free.
**Scoping:** history tracks the **COMPONENT\_SET** when the node belongs to one. Variant node IDs churn as variants are added and removed, so the set is the stable identity across versions.
**Labeled versions vs auto-saves:** labeled versions make the best changelog rows, but many real design-system files have none at all — a mature file was verified live with 72 auto-saves and 0 labeled versions. Rather than emit an empty section there, history falls back to auto-saves automatically and says so in a note (`historySummary.design.usedAutosaveFallback`). Auto-save noise is largely absorbed downstream: a version only becomes a row if it actually changed the scoped component — on a real 24-variant Button, 20 version-pairs produced 4 rows. Auto-save rows render as `_(auto-save)_` with the date rather than the raw 19-digit version ID; that ID stays available as `historySummary.design.latestVersionId`.
**Coverage limits** — the generated doc states these inline so an empty table is never misread as "nothing changed":
* Figma's REST version snapshots **omit description and Dev Mode annotation edits**, raw layout/visual properties, and variable *value* changes. Structure (child layers), component property definitions, variable *bindings*, and renames are tracked, at depth 2
* Version-history retention is plan-dependent, so lower tiers expose a shorter window
* Reading version history requires the `file_versions:read` OAuth scope, or the **Versions** Read permission on a Personal Access Token. Without it the section degrades to an explanatory note rather than failing the doc
* `git` history uses `--follow` (renames traced) only when exactly one path is resolved — git supports it for a single pathspec only
***
## 💬 Comment Tools
### `figma_get_comments`
Get comments on a Figma file. Returns comment threads with author, message, timestamps, and pinned node locations.
**When to Use:**
* Reviewing feedback threads on a design file
* Checking for open comments before a release
* Retrieving comment IDs to reply to or delete
**Usage:**
```javascript theme={null}
figma_get_comments({
fileUrl: 'https://figma.com/design/abc123',
include_resolved: false,
as_md: true
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL (uses current URL if omitted)
* `as_md` (optional): Return comment message bodies as markdown (default: false)
* `include_resolved` (optional): Include resolved comment threads (default: false)
**Returns:**
* `comments`: Array of comment objects with `id`, `message`, `user`, `created_at`, `resolved_at`, `client_meta` (pinned location)
* `summary`: Total, active, resolved, and returned counts
***
### `figma_post_comment`
Post a comment on a Figma file, optionally pinned to a specific design node. Supports replies to existing threads.
**When to Use:**
* After `figma_check_design_parity` to notify designers of drift
* Leaving feedback on specific components or elements
* Replying to an existing comment thread
**Usage:**
```javascript theme={null}
// Pin a comment to a specific node
figma_post_comment({
fileUrl: 'https://figma.com/design/abc123',
message: 'Border-radius in code uses 8px but Figma shows 6px. Please update.',
node_id: '695:313'
})
// Reply to an existing comment thread
figma_post_comment({
fileUrl: 'https://figma.com/design/abc123',
message: 'Fixed in the latest push.',
reply_to_comment_id: '1627922741'
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL (uses current URL if omitted)
* `message` (required): The comment message text
* `node_id` (optional): Node ID to pin the comment to (e.g., `'695:313'`)
* `x` (optional): X offset for comment placement relative to the node
* `y` (optional): Y offset for comment placement relative to the node
* `reply_to_comment_id` (optional): ID of an existing comment to reply to
**Returns:**
* `comment`: Created comment object with `id`, `message`, `created_at`, `user`, `client_meta`
**@mentions are not supported via the API.** Including `@name` in the message renders as plain text, not a clickable Figma mention tag. Clickable @mentions with notifications are a Figma UI-only feature. To notify specific people, share the comment link or use Figma's built-in notification system.
***
### `figma_delete_comment`
Delete a comment from a Figma file by its comment ID.
**When to Use:**
* Cleaning up test or outdated comments
* Removing resolved feedback after fixes are confirmed
* Managing comment threads programmatically
**Usage:**
```javascript theme={null}
figma_delete_comment({
fileUrl: 'https://figma.com/design/abc123',
comment_id: '1627922741'
})
```
**Parameters:**
* `fileUrl` (optional): Figma file URL (uses current URL if omitted)
* `comment_id` (required): The ID of the comment to delete (get IDs from `figma_get_comments`)
**Returns:**
* `success`: Boolean indicating deletion success
* `deleted_comment_id`: The ID that was deleted
***
## 📝 Annotation Tools
Annotation tools require the Desktop Bridge plugin to be running in Figma. Annotations are distinct from comments: they are node-level design specs that can pin specific properties (fills, width, typography, etc.) and support markdown-formatted labels. Designers use them to communicate animation timings, accessibility requirements, interaction specs, and other implementation details.
### `figma_get_annotations`
Read annotations from a Figma node. Annotations are designer-authored specs attached to nodes — they can include notes (plain text or markdown), pinned design properties (fills, width, fontSize, etc.), and category labels.
**Mode:** Local / Cloud
**When to Use:**
* Discovering designer specs on a component before implementation
* Reading animation timings, interaction behaviors, or accessibility requirements
* Getting all annotations across a component tree for documentation
**Usage:**
```javascript theme={null}
// Read annotations from a component
figma_get_annotations({ nodeId: '695:313' })
// Read annotations from a component and all its children
figma_get_annotations({ nodeId: '695:313', include_children: true, depth: 3 })
```
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | Node ID to read annotations from (e.g., '695:313') |
| `include_children` | boolean | No | Also read annotations from child nodes (default: false) |
| `depth` | number | No | How many levels deep to traverse when include\_children is true (default: 1, max recommended: 5) |
**Returns:**
* `nodeId`, `nodeName`, `nodeType`: The target node info
* `annotations`: Array of annotations with `label`, `labelMarkdown`, `properties` (pinned design properties), `categoryId`, `categoryName`
* `annotationCount`: Number of annotations on this node
* `children`: (when include\_children=true) Array of child nodes with their annotations
* `childAnnotationCount`: Total annotations across children
* `availableCategories`: List of annotation categories in the file
### `figma_set_annotations`
Write or clear annotations on a Figma node. Supports plain text labels, rich markdown labels, pinned design properties, and annotation categories. This operation is undoable in Figma (Cmd+Z).
**Mode:** Local / Cloud
**When to Use:**
* Documenting animation timings and easing curves on components
* Adding accessibility requirements to design nodes
* Communicating implementation notes from design reviews
* Clearing outdated annotations after implementation is complete
**Usage:**
```javascript theme={null}
// Write annotations with markdown and pinned properties
figma_set_annotations({
nodeId: '695:313',
annotations: [
{ label: 'Supports keyboard navigation via Tab and Enter' },
{
labelMarkdown: '**Animation:** Press uses `ease-out` with `150ms`',
properties: [{ type: 'fills' }, { type: 'padding' }],
categoryId: '1026:1'
}
]
})
// Append to existing annotations
figma_set_annotations({
nodeId: '695:313',
annotations: [{ label: 'Min touch target: 44x44px' }],
mode: 'append'
})
// Clear all annotations
figma_set_annotations({ nodeId: '695:313', annotations: [] })
```
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | Node ID to write annotations to (e.g., '695:313') |
| `annotations` | array | Yes | Array of annotation objects (see below). Pass `[]` to clear all annotations. |
| `mode` | string | No | `replace` (default) overwrites all existing annotations. `append` adds to existing. |
**Annotation object fields:**
| Field | Type | Required | Description |
| - | - | - | - |
| `label` | string | No | Plain text annotation label |
| `labelMarkdown` | string | No | Rich text with markdown (bold, italic, links, lists, code, headers) |
| `properties` | array | No | Array of `{ type: string }` for pinned properties (e.g., `fills`, `width`, `fontSize`) |
| `categoryId` | string | No | Annotation category ID (use `figma_get_annotation_categories` to list) |
**Returns:**
* `success`: Boolean indicating write success
* `nodeId`: The target node ID
* `nodeName`: The node name
* `annotationCount`: Number of annotations after the operation
* `mode`: The write mode used
> **Note:** Pinned properties must be valid for the node type. For example, `cornerRadius` works on COMPONENT nodes but not on COMPONENT\_SET nodes. Use `figma_get_annotation_categories` to discover valid category IDs.
### `figma_get_annotation_categories`
List available annotation categories in the current Figma file. Categories group annotations by purpose (e.g., interactions, accessibility, development notes).
**Mode:** Local / Cloud
**When to Use:**
* Discovering available categories before creating annotations
* Listing category IDs for use with `figma_set_annotations`
**Usage:**
```javascript theme={null}
figma_get_annotation_categories()
// Returns: { categories: [{ id: '1026:0' }, { id: '1026:1' }, ...] }
```
**Parameters:** None
**Returns:**
* `categories`: Array of `{ id, name }` category objects
### Annotations Workflow
| Use Case | Tool |
| - | - |
| Discover designer specs on a component | `figma_get_annotations` |
| Get all annotations across a component tree | `figma_get_annotations` (with `include_children: true`) |
| Document animation timings and interaction behaviors | `figma_set_annotations` |
| Add accessibility requirements to components | `figma_set_annotations` |
| Clear outdated annotations after implementation | `figma_set_annotations` (with `annotations: []`) |
| List annotation categories for organizing notes | `figma_get_annotation_categories` |
| Generate component docs including annotations | `figma_generate_component_doc` |
***
## 🖼️ Image Tools
### `figma_set_image_fill`
Set an image fill on one or more Figma nodes. Accepts base64-encoded image data or (in Local Mode) an absolute file path.
**Mode:** Local / Cloud
**When to Use:**
* Applying photos, illustrations, or textures to frames and shapes
* Setting hero images, avatars, or background images
* Replacing placeholder images with real assets
**Usage:**
```javascript theme={null}
// Base64 image data
figma_set_image_fill({
nodeIds: ["123:456", "789:012"],
imageData: "iVBORw0KGgo...", // base64-encoded PNG or JPEG
scaleMode: "FILL"
})
// File path (Local Mode only)
figma_set_image_fill({
nodeIds: ["123:456"],
imageData: "/tmp/hero-image.jpg",
scaleMode: "FIT"
})
```
**Parameters:**
* `nodeIds` (required): Array of node IDs to apply the image fill to
* `imageData` (required): Base64-encoded image data (JPEG/PNG), or an absolute file path starting with `/` (Local Mode only)
* `scaleMode` (optional): How the image fills the node — `"FILL"` (default), `"FIT"`, `"CROP"`, or `"TILE"`
**Returns:**
* `imageHash`: Figma's internal hash for the created image
* `updatedCount`: Number of nodes successfully updated
* `nodes`: Array of updated node IDs and names
***
## 🔍 Accessibility Tools
Three tools provide full-spectrum accessibility coverage across design and code — without maintaining a rule database. Design-side checks are bounded by Figma's API; code-side checks delegate to axe-core (Deque).
### `figma_lint_design`
Run comprehensive WCAG 2.2 accessibility and design quality checks on the current page or a specific node tree. Returns categorized findings with severity levels.
**Mode:** Local / Cloud
**When to Use:**
* Checking designs for WCAG accessibility compliance (14 checks)
* Finding hardcoded colors that should use design tokens
* Detecting detached components, missing focus variants, color-only states
* Auditing heading hierarchy, reading order, reflow readiness
* Pre-handoff quality checks
**Usage:**
```javascript theme={null}
// Lint the current page for all issues
figma_lint_design()
// Only WCAG accessibility checks (14 rules)
figma_lint_design({
rules: ["wcag"]
})
// Only design system hygiene
figma_lint_design({
rules: ["design-system"]
})
// Specific rules only
figma_lint_design({
rules: ["wcag-contrast", "wcag-focus-indicator", "wcag-image-alt"],
maxFindings: 50
})
// Lint a specific node tree
figma_lint_design({
nodeId: "123:456",
maxDepth: 5
})
```
**Parameters:**
* `nodeId` (optional): Node ID to lint (defaults to current page)
* `rules` (optional): Rule filter — `["all"]` (default), `["wcag"]` (14 rules), `["design-system"]`, `["layout"]`, or specific rule IDs
* `maxDepth` (optional): Maximum tree depth to traverse (default: 10)
* `maxFindings` (optional): Maximum findings before stopping (default: 100)
**Rule Groups:**
| Group | Rules | What It Checks |
| - | - | - |
| `wcag` | 14 rules (see below) | WCAG accessibility compliance |
| `design-system` | `hardcoded-color`, `no-text-style`, `default-name`, `detached-component`, `token-misuse` | Design system hygiene |
| `layout` | `no-autolayout`, `empty-container` | Layout quality |
Each finding includes a `wcagLevel` field (`a`, `aa`, or `best-practice`) so teams can filter by their target conformance level.
**Individual Rules:**
| Rule | Severity | Level | Description |
| - | - | - | - |
| `wcag-contrast` | critical | AA | Text contrast below 4.5:1 (3:1 for large text ≥24px or ≥18.5px bold) |
| `wcag-non-text-contrast` | critical | AA | UI component/graphical object below 3:1 against background |
| `wcag-color-only` | critical | A | Information conveyed only through color (no icon/border indicator) |
| `wcag-target-size` | critical | AA | Interactive elements smaller than 24x24px |
| `wcag-focus-indicator` | critical | AA | Interactive component missing focus variant or visible indicator — blocker for keyboard users |
| `wcag-disabled-no-context` | warning | AA | Disabled variant has no tooltip/helper text explaining why disabled. Recommends aria-disabled over HTML disabled to keep element focusable for screen readers. |
| `wcag-text-size` | warning | best-practice | Text below 12px (readability best practice — WCAG 1.4.4 is about zoom support, not minimum size) |
| `wcag-letter-spacing` | warning | best-practice | Negative letter spacing harms readability |
| `wcag-image-alt` | warning | A | Image fills without description annotation |
| `wcag-heading-hierarchy` | warning | A | Heading levels skip (e.g., H1 → H3) |
| `wcag-reflow` | warning | AA | Fixed-position frames; content must support 320px min width (400% zoom on 1280px) |
| `wcag-reading-order` | warning | A | Layer order doesn't match visual reading order |
| `wcag-line-height` | info | best-practice | Line height below 1.5x (WCAG 1.4.12 requires supporting user overrides, not specific defaults) |
| `wcag-paragraph-spacing` | info | best-practice | Paragraph spacing below 2x font size (same — about user override support) |
| `token-misuse` | warning | — | Variable name prefix doesn't match usage (e.g., bg/\* token as text fill) |
| `hardcoded-color` | warning | — | Solid fills not bound to a variable or style |
| `no-text-style` | warning | — | Text nodes without an applied text style |
| `default-name` | warning | — | Nodes with generic Figma names |
| `detached-component` | warning | — | Frames with component naming but not a component |
| `no-autolayout` | warning | — | Frames with 2+ children without auto-layout |
| `empty-container` | info | — | Frames with zero children |
**Returns:**
```json theme={null}
{
"rootNodeId": "0:1",
"rootNodeName": "My Page",
"nodesScanned": 142,
"categories": [
{
"rule": "wcag-contrast",
"severity": "critical",
"count": 3,
"description": "Text does not meet WCAG AA contrast ratio",
"nodes": [
{ "id": "1:2", "name": "Label", "ratio": "2.3:1", "required": "4.5:1", "fg": "#AAAAAA", "bg": "#FFFFFF" }
]
}
],
"summary": {
"critical": 3,
"warning": 8,
"info": 1,
"total": 12
}
}
```
**Natural language triggers:**
* "Check my design for accessibility issues"
* "Lint this page"
* "Find hardcoded colors"
* "Are there any detached components?"
* "Run a WCAG contrast check"
* "Audit the design quality"
### `figma_audit_component_accessibility`
Deep accessibility audit for a specific component or component set. Produces a scorecard covering state coverage, focus indicator quality, non-color differentiation, target size consistency, annotation completeness, and color-blind simulation.
**Mode:** Local / Cloud
**When to Use:**
* Validating a component's accessibility before design handoff
* Checking if all interactive states (focus, disabled, error) are present
* Verifying color-blind safety with protanopia/deuteranopia/tritanopia simulation
* Auditing whether components have accessibility documentation
**Usage:**
```javascript theme={null}
// Audit a component set
figma_audit_component_accessibility({
nodeId: "438:1401"
})
// Audit with iOS touch target minimum (44px)
figma_audit_component_accessibility({
nodeId: "438:1401",
targetSize: 44
})
// Audit current selection (no nodeId needed)
figma_audit_component_accessibility()
```
**Parameters:**
* `nodeId` (optional): Node ID of a COMPONENT\_SET, COMPONENT, or INSTANCE. Falls back to current selection.
* `targetSize` (optional): Minimum touch target size in px (default: 24 per WCAG 2.5.8). Use 44 for iOS, 48 for Android.
**Scoring (0-100):**
| Category (weight) | What It Checks |
| - | - |
| State Coverage (20%) | Presence of default, hover, focus, disabled, error, active, loading variants |
| Focus Indicator (20%) | Focus variant exists + has visible stroke or shadow |
| Color Differentiation (15%) | Status states use more than just color |
| Target Size (15%) | All variants meet minimum touch target |
| Annotations (10%) | Component description + accessibility notes |
| Color-Blind Safety (20%) | Contrast preserved under protanopia, deuteranopia, tritanopia |
### `figma_scan_code_accessibility`
Scan HTML code for accessibility violations using axe-core (Deque). Runs structural/semantic checks via JSDOM — no browser needed. Visual rules (color contrast) are disabled since they're handled by `figma_lint_design`.
**Mode:** Local (standalone — no Figma connection required). Not available in Cloud Mode: its HTML parser (JSDOM) does not run in Cloudflare Workers.
**When to Use:**
* Scanning component HTML for ARIA, label, and semantic issues
* Checking code accessibility before merging
* Generating a CodeSpec for design-to-code parity comparison
* Validating that implemented code matches design accessibility intent
**Usage:**
```javascript theme={null}
// Scan component HTML
figma_scan_code_accessibility({
html: ''
})
// Filter to WCAG 2.0 AA rules only
figma_scan_code_accessibility({
html: '',
tags: ["wcag2aa"]
})
// Auto-generate CodeSpec for parity checking
figma_scan_code_accessibility({
html: '',
mapToCodeSpec: true
})
```
**Parameters:**
* `html` (required): HTML string to scan (fragment or full document)
* `tags` (optional): WCAG tag filter — `["wcag2a"]`, `["wcag2aa"]`, `["wcag22aa"]`, `["best-practice"]`
* `context` (optional): CSS selector to scope the scan
* `mapToCodeSpec` (optional): If true, auto-generates `codeSpecAccessibility` for use with `figma_check_design_parity`
* `includePassingRules` (optional): Include pass/incomplete counts
**End-to-end workflow:**
```
1. figma_lint_design → visual a11y on design side
2. figma_audit_component_a11y → component scorecard
3. figma_scan_code_a11y → structural a11y on code side
└─ mapToCodeSpec: true → auto-generate CodeSpec
4. figma_check_design_parity → compare design intent vs code
```
***
## 📌 FigJam Tools
FigJam tools only work when the Desktop Bridge plugin is running in a FigJam board (`editorType === 'figjam'`). They return clear errors when used in Figma Design files.
### `figjam_create_sticky`
Create a sticky note on a FigJam board.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | Text content (max 5,000 chars) |
| `color` | string | No | YELLOW, BLUE, GREEN, PINK, ORANGE, PURPLE, RED, LIGHT\_GRAY, GRAY |
| `x` | number | No | X position on canvas |
| `y` | number | No | Y position on canvas |
### `figjam_create_stickies`
Batch create multiple sticky notes (max 200). Font is loaded once for the entire batch.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `stickies` | array | Yes | Array of `{text, color?, x?, y?}` objects (max 200) |
### `figjam_create_connector`
Connect two nodes with a connector line. Use node IDs from creation results.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `startNodeId` | string | Yes | Node ID of the start element |
| `endNodeId` | string | Yes | Node ID of the end element |
| `label` | string | No | Text label on the connector |
### `figjam_create_shape_with_text`
Create a labeled shape for flowcharts and diagrams.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | No | Text label |
| `shapeType` | string | No | ROUNDED\_RECTANGLE (default), DIAMOND, ELLIPSE, TRIANGLE\_UP, TRIANGLE\_DOWN, PARALLELOGRAM\_RIGHT, PARALLELOGRAM\_LEFT, ENG\_DATABASE, ENG\_QUEUE, ENG\_FILE, ENG\_FOLDER |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_table`
Create a table with optional cell data.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `rows` | number | Yes | Number of rows (1-100) |
| `columns` | number | Yes | Number of columns (1-50) |
| `data` | string\[]\[] | No | 2D array of cell text (row-major order) |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_code_block`
Create a code block for sharing snippets and technical documentation.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Code content (max 50,000 chars) |
| `language` | string | No | JAVASCRIPT, PYTHON, TYPESCRIPT, JSON, HTML, CSS, etc. |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_section`
Create a section to group related content on a board.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Section title |
| `x` | number | No | X position |
| `y` | number | No | Y position |
| `width` | number | No | Width in pixels (default 1000) |
| `height` | number | No | Height in pixels (default 800) |
| `fillColor` | string | No | Hex fill color, e.g. `#F5F5F5` |
### `figjam_auto_arrange`
Arrange nodes in a grid, horizontal row, or vertical column layout.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeIds` | string\[] | Yes | Array of node IDs to arrange (max 500) |
| `layout` | string | No | `grid` (default), `horizontal`, or `vertical` |
| `spacing` | number | No | Spacing between nodes in pixels (default: 40) |
| `columns` | number | No | Grid columns (defaults to sqrt of node count) |
### `figjam_get_board_contents`
Read all content from a FigJam board. Returns stickies, shapes, connectors, tables, code blocks, and sections with their text content, positions, and type-specific properties (colors, shape types, cell data, connector endpoints).
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeTypes` | string\[] | No | Filter by type: STICKY, SHAPE\_WITH\_TEXT, CONNECTOR, TABLE, CODE\_BLOCK, SECTION, FRAME, TEXT. Omit for all. |
| `maxNodes` | number | No | Maximum nodes to return (1-1000, default: 500) |
**Returns:**
* `nodes` — Array of node objects with id, type, name, position, dimensions, and type-specific data
* `totalFound` — Number of nodes returned
* `truncated` — Whether results were capped at maxNodes
* `page` — Current page name
### `figjam_get_connections`
Read the connection graph from a FigJam board. Returns all connectors as edges with their start/end node references and labels, plus a lookup of connected nodes.
**Mode:** Local / Cloud
**Parameters:** None
**Returns:**
* `edges` — Array of `{connectorId, startNodeId, endNodeId, label}`
* `connectedNodes` — Map of node ID → `{id, type, name, text}`
* `totalConnectors` — Number of connectors found
* `totalConnectedNodes` — Number of unique connected nodes
***
## ☁️ Cloud Relay
### `figma_pair_plugin`
Generate a pairing code to connect the Figma Desktop Bridge plugin to the cloud relay. This enables write operations from web-based AI clients.
**Mode:** Cloud only (available on both the `/mcp` and `/sse` endpoints)
**Parameters:** None
**Returns:**
* `code` — 6-character alphanumeric pairing code (uppercase, no ambiguous characters)
* `expiresIn` — Expiry time (5 minutes)
* Instructions for the user
**Natural language triggers:**
* "Connect to my Figma plugin"
* "Pair with my design file"
* "Set up the cloud connection"
* "Link Figma to this chat"
**How it works:**
1. Generates a unique 6-character code stored in KV with 5-minute TTL
2. User enters code in the Desktop Bridge plugin's Cloud Mode section
3. Plugin connects via WebSocket to the cloud relay Durable Object
4. All subsequent write tool calls route through the relay to the plugin
**Important:** The pairing code expires after 5 minutes. If it expires before the plugin connects, generate a new one.
***
## 🕒 Version History Tools
Six tools that turn a Figma file from a static snapshot into a queryable history. They compose: list versions → diff → generate changelog → blame specific changes back to the version that introduced them. All cache aware (past versions are immutable, so repeat queries on the same range cost zero new API calls).
**Required scope:** `file_versions:read` (OAuth) or **Versions** (Read) on a Personal Access Token, in addition to the standard `file_content:read`.
### `figma_get_file_versions`
List a file's version history with author, label, description, and timestamp metadata. Auto-paginates up to `max_versions`. Defaults to **labeled-only** (skips auto-saves) — pass `include_autosaves: true` to see every saved state.
**Usage:**
```javascript theme={null}
figma_get_file_versions({
fileUrl: 'https://www.figma.com/design/abc123/My-File', // optional
include_autosaves: false, // default
max_versions: 50, // default 50, max 200
cursor: 'vSomeId' // optional, for pagination
})
```
Returns `{ versions: [...], pagination: { has_more, next_cursor, returned, filtered_out_autosaves } }`. Each version entry includes `id`, `label`, `description`, `created_at`, `user.handle`, and `is_labeled`.
### `figma_get_file_at_version`
Snapshot a file (or selected nodes) as it existed at a past `version_id`. Thin wrapper over `figma_get_file_data` with the version param plumbed through.
**Usage:**
```javascript theme={null}
figma_get_file_at_version({
version_id: '2332825592044334783',
node_ids: ['4271:9562'], // optional — scope to specific nodes
depth: 2 // optional — limit recursion
})
```
### `figma_diff_versions`
Structured diff between two versions. Always returns a cheap page-structure diff (\~2 API calls, parallel). When `component_ids` are passed, additionally produces per-node diffs at depth=2: added/removed children (variants), name/description changes, `componentPropertyDefinitions` changes, and `boundVariables` deltas.
**Usage:**
```javascript theme={null}
figma_diff_versions({
from_version: '2285226350723738406',
to_version: '2332825592044334783', // or 'current' for HEAD
component_ids: ['4271:9562'], // optional — falls back to current Figma selection
mode: 'detailed' // 'summary' | 'standard' (default) | 'detailed'
})
```
**Note:** Variable VALUE history is not retrievable from Figma REST API. Variable definition value changes between versions are not represented; only binding-reference changes on scoped nodes are detected. This limitation is surfaced in the response's `notes[]`.
### `figma_get_changes_since_version`
Convenience wrapper for `figma_diff_versions` with `to_version="current"` (HEAD). Useful for "what's changed since the last code-sync" workflows.
```javascript theme={null}
figma_get_changes_since_version({
since_version: '2332825592044334783',
component_ids: ['4271:9562'] // optional, falls back to selection
})
```
### `figma_generate_changelog`
Markdown changelog generator. Wraps `figma_diff_versions` with author enrichment (one extra cheap API call to look up labels and authors for the from/to versions). Returns BOTH a `markdown` string ready for release notes / PRs / Storybook MDX, and the structured diff payload.
```javascript theme={null}
figma_generate_changelog({
from_version: 'vEarlier',
to_version: 'current',
component_ids: ['4271:9562'], // optional, falls back to selection
mode: 'standard' // 'summary' | 'standard' (default) | 'detailed'
})
```
Mode controls verbosity: `summary` produces a one-line release note; `standard` includes sectioned page + per-component change counts; `detailed` includes per-property and per-binding bullets.
### `figma_blame_node`
Find the version that introduced a specific change to a node — answers "who/when added this." Walks history backward via **binary search** (\~log₂(N) probes instead of N), so a 200-version lookback typically costs \~8 API calls instead of 200.
```javascript theme={null}
figma_blame_node({
node_id: '4271:9562', // optional, falls back to selection
target_component_property: 'Disabled#1:2', // OR target_child_node_id
start_version: 'current', // walk backward from here
max_versions_to_walk: 200, // default 200, max 500
include_autosaves: true // default true — better attribution
})
```
Returns `{ introduced_at: { version_id, label, created_at, user_handle, is_labeled }, attribution_certainty, summary, notes }`.
`attribution_certainty` is one of:
* `"exact"` — the introduction point is fully localized and authored by a real user
* `"system_attributed"` — the introducing version was a system-triggered autosave (`user="Figma"`); set `include_autosaves: false` and re-run to find the labeled shipping author
* `"exists_at_lookback_horizon"` — the actual introduction is older than `max_versions_to_walk`; raise the cap and retry
* `"metadata_unavailable"` — introduction was at `start_version` itself but author lookup couldn't reach it within the version-list lookback
**Honest about limits:** binary search assumes the target's existence is monotonic (added once, never removed). If the target was added, removed, then re-added, the tool may report a different introduction point than the original. This is called out in `notes[]` on every response.
***
## Error Handling
All tools return structured error responses:
```json theme={null}
{
"error": "Error message",
"message": "Human-readable description",
"hint": "Suggestion for resolution"
}
```
Common errors:
* `"FIGMA_ACCESS_TOKEN not configured"` - Set up your token (see installation guide)
* `"Failed to connect to browser"` - Browser initializing or connection issue
* `"Invalid Figma URL"` - Check URL format
* `"Node not found"` - Verify node ID is correct
* `"Desktop Bridge plugin not found"` - Ensure plugin is running in Figma
* `"Invalid hex color"` - Check hex format (use #RGB, #RGBA, #RRGGBB, or #RRGGBBAA)
See [Troubleshooting Guide](TROUBLESHOOTING.md) for detailed solutions.
# Troubleshooting
Source: https://docs.figma-console-mcp.southleft.com/troubleshooting
Solutions to common issues including browser connection, console logs, screenshots, and configuration problems.
# Troubleshooting Guide
## Connection Drops or "Not Connected"? Start Here
> **This is the most common issue, and as of v1.31.0 it is fixed at the source.** If the bridge keeps dropping and only comes back when you close the plugin, restart your MCP client, or kill ports by hand, you were hitting **zombie MCP server processes** squatting the WebSocket port range (9223–9232) after a bad shutdown. Each fresh server got bumped to a port with no plugin attached, so status read "not connected." v1.31.0 makes those zombies impossible to create and reaps any that already exist — and the plugin now reconnects itself.
### Step 1 — Update and re-import the plugin (required, one time)
The fix lives in **both** the server and the redesigned Desktop Bridge plugin, so you need both halves:
1. **Update the package** so your MCP client launches v1.31.0+ (NPX users get it automatically on next launch; pinned versions should bump to `figma-console-mcp@1.31.0` or later).
2. **Re-import the plugin** — Figma caches plugin files at the application level, so restarting your MCP client alone will *not* pick up the new plugin UI:
* Figma Desktop → **Plugins → Development → Import plugin from manifest…**
* Select `~/.figma-console-mcp/plugin/manifest.json` (the stable path the server maintains automatically)
3. Run the Desktop Bridge plugin in your file. It auto-connects.
> **You only have to do this once per plugin change.** After you're on v1.31.0+, updates don't need a re-import unless a release explicitly says so. The plugin files last changed in v1.39.0, so if your imported plugin is older than that, re-import it once. The plugin shows an update banner when the server bundles a newer plugin than the one running.
### Step 2 — Let it reconnect itself (no more restart ritual)
Once you're on v1.31.0+, you should rarely touch the connection again. Three things now keep it alive automatically:
* **Server-side self-healing.** Stale/zombie MCP servers are force-killed (`SIGTERM` → `SIGKILL`) on startup *and* swept every 5 minutes, so the port range stays clean. A hung shutdown can no longer leave an orphan behind.
* **Auto-reconnect watchdog.** If the plugin ever shows disconnected, it re-probes every \~12 seconds and reattaches the instant a server is available — **no restart needed**, even if you opened the plugin before your MCP client started.
* **One-click Reconnect.** The plugin's main button becomes **Reconnect** when a connection drops unexpectedly (and **Pause/Resume** when connected). Click it for an instant retry instead of reopening the plugin.
To confirm state at any time, ask your AI to run `figma_get_status` (or `figma_diagnose`). The plugin's log header also shows a live **`N server(s)`** badge — if that number is higher than the number of MCP clients you're running, you have stale processes (and the reaper will clear them).
### Last resort — manually clear leftover zombies (rarely needed)
You should only need this **once, right after upgrading**, to clear pre-v1.31.0 zombies that were already running before the new reaper existed (it cleans up on the *next* server start, but old processes from before the upgrade may still be holding ports). After that, the automatic reaper handles it.
```bash theme={null}
# Kill any stale Figma Console MCP servers, then clear their port-advertisement files
pkill -f figma-console-mcp
rm -f "${TMPDIR:-/tmp}"/figma-console-mcp-*.json /tmp/figma-console-mcp-*.json
```
Then reload the Desktop Bridge plugin in Figma — the watchdog reconnects to the clean server. (Port files live in the OS temp dir, which on macOS is `$TMPDIR` → `/var/folders/…`, not `/tmp`, so both paths are listed.) To inspect what's holding the range without killing anything: `lsof -i :9223-9232 | grep LISTEN`.
***
## Common Issues and Solutions
### Issue: Claude Code OAuth Completes But Connection Fails
**Symptoms:**
* Using Claude Code with `claude mcp add --transport sse`
* OAuth opens in browser and you authorize successfully
* Connection never establishes after OAuth
* Server shows "figma-console: not connected" in `/mcp`
**Cause:**
This is a [known bug in Claude Code's HTTP/SSE transport](https://github.com/anthropics/claude-code/issues/2466). The native SSE transport doesn't properly reconnect after completing the OAuth flow.
**Solution:**
Use the `mcp-remote` package instead of Claude Code's native SSE transport:
```bash theme={null}
claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse
```
Or add to `~/.claude.json` manually:
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://figma-console-mcp.southleft.com/sse"]
}
}
}
```
Restart Claude Code (`/mcp` to reconnect) — mcp-remote will open a browser for OAuth, and the connection will work correctly.
**Alternative:** If you're using Claude Code, consider using [Local Mode](/setup#-npx-setup-recommended) instead. It provides the full feature set including the Desktop Bridge plugin, and doesn't require OAuth (uses a Personal Access Token).
***
### Plugin Debugging: Simple Workflow ✅
**For Plugin Developers in Local Mode:**
> **FIRST-TIME SETUP:**
>
> 1. Open Figma Desktop normally (no special flags needed)
> 2. Go to **Plugins → Development → Import plugin from manifest...**
> 3. Select `~/.figma-console-mcp/plugin/manifest.json` (stable path created automatically by the MCP server)
> 4. Run the plugin in your Figma file — it auto-connects via WebSocket
>
> ✅ Re-importing the manifest after a package update is **optional**. Most upgrades stay wire-compatible with the previous plugin — you'll still get all functional changes. Re-import only when release notes specifically call for it (typical for plugin-side method additions), or when you want the latest cosmetic touches (status-pill copy, `pluginVersion` reporting).
### How to Verify Setup is Working
Before trying to get console logs, verify your setup:
```
"Check Figma status"
```
You should see something like:
```json theme={null}
{
"setup": {
"valid": true,
"message": "✅ Figma Desktop connected via WebSocket (Desktop Bridge Plugin)"
}
}
```
If you see `"valid": false`, the AI will provide step-by-step setup instructions.
***
### WebSocket Bridge Troubleshooting
#### Plugin Shows "Disconnected"
**Cause:** MCP server is not running (it hosts the WebSocket server on ports 9223–9232).
**Fix:** Start or restart your MCP client (Claude Code, Cursor, etc.) so the MCP server process starts.
#### Plugin Not Appearing in Development Plugins
**Cause:** Plugin manifest not imported.
**Fix:** Go to Figma → Plugins → Development → Import plugin from manifest... → select `figma-desktop-bridge/manifest.json`.
#### Port 9223 Already in Use
**Cause:** Another MCP server instance or orphaned process is running on port 9223.
**Fix:** The server automatically cleans up orphaned MCP processes on startup and falls back to the next available port in the range 9223–9232. The plugin scans the whole range on launch and picks up whichever port the server bound to.
#### Plugin Shows "MCP scanning" or "Retry"
**Cause:** The MCP server is not running yet, or all ports 9223–9232 are occupied.
**Fix:** Start your MCP client (Claude Code, Cursor, etc.) so the MCP server process starts. On v1.31.0+ the plugin's watchdog keeps probing and connects on its own the moment a server appears — you don't need to restart anything. If ports are jammed by stale processes from *before* you upgraded, see [Start Here → Last resort](#last-resort--manually-clear-leftover-zombies-rarely-needed); going forward the server's reaper clears orphans on startup and every 5 minutes automatically.
#### Plugin Shows "No MCP server found"
**Cause:** The plugin scanned every port in 9223–9232 and got no response.
**Fix:** Make sure an MCP client is running with figma-console-mcp configured. Check `figma_get_status` from your AI client.
#### Orphaned MCP Processes Filling Port Range
**Cause:** MCP clients can leave orphaned MCP server processes running after tabs/windows close (a known Claude Desktop issue, and the original root cause of the recurring "not connected until restart" reports).
**Fix (v1.31.0+):** The server now force-kills orphans it finds — escalating `SIGTERM` → `SIGKILL` so even a hung process that ignores a graceful shutdown is cleared — on startup *and* on a 5-minute background sweep. A shutdown backstop also prevents a server from zombifying in the first place. In normal use you should never need to intervene. To inspect (not kill) what's holding ports: `lsof -i :9223-9232 | grep LISTEN`. To force-clear leftovers from before you upgraded, see [Start Here → Last resort](#last-resort--manually-clear-leftover-zombies-rarely-needed).
> **Stable plugin path:** The MCP server automatically copies plugin files to `~/.figma-console-mcp/plugin/` on startup. Import from this path instead of the volatile npx cache path. Re-importing after a package update is optional — only required when the release notes call for it.
#### Running in Docker
**Cause:** The WebSocket server binds to `localhost` by default, which is unreachable from the Docker host.
**Fix:** Set `FIGMA_WS_HOST=0.0.0.0` in your container environment and expose the port with `-p 9223:9223`.
#### Plugin Connected but Commands Timeout
**Cause:** Plugin may be running in a different Figma file than expected.
**Fix:** The MCP server routes commands to the active file. Make sure the Desktop Bridge Plugin is running in the file you want to work with. Use `figma_get_status` to see which file is connected.
***
### The Simplest Workflow - No Navigation Needed!
Once setup is complete, just ask your AI to check console logs:
```
"Check the last 20 console logs"
```
Then run your plugin in Figma Desktop, and ask again:
```
"Check the last 20 console logs"
```
You'll see all your `[Main]`, `[Swapper]`, `[Serializer]`, etc. plugin logs immediately:
```json theme={null}
{
"logs": [
{
"timestamp": 1759747593482,
"level": "log",
"message": "[Main] ✓ Instance Swapping: 0 swapped, 20 unmatched",
"source": "figma"
},
{
"timestamp": 1759747593880,
"level": "log",
"message": "[Serializer] Collected 280 variables, 144 paint styles",
"source": "figma"
}
]
}
```
**That's it!** No navigation, no browser setup, no complex configuration.
***
### Issue: No Console Logs Captured
**Symptoms:**
* `figma_get_console_logs()` returns empty array
* Log count is 0
**Possible Causes:**
1. The Desktop Bridge plugin isn't running in the file you expect
2. The plugin hasn't produced output yet
3. Logs are being filtered out by level
**Solutions:**
#### Verify the plugin is connected
```
figma_get_status()
```
`bridge.connected` should be `true`, and `bridge.file.name` should match the file you're working in.
#### Re-run the plugin in Figma
The Desktop Bridge plugin captures `console.log/warn/error/info/debug` from its own QuickJS sandbox. Open the file, run **Plugins → Development → Figma Desktop Bridge**, then trigger your work.
#### Check log levels
```
figma_get_console_logs({ level: 'all' }) // Everything
figma_get_console_logs({ level: 'error' }) // Only errors
figma_get_console_logs({ level: 'log' }) // Only console.log
figma_get_console_logs({ level: 'warn' }) // Only warnings
```
> **Cloud Mode note:** In Local Mode `figma_get_console_logs` reads from the Desktop Bridge plugin's QuickJS sandbox. In Cloud Mode the Cloudflare-hosted server launches a headless browser via the Browser Rendering API and captures logs from there. Plugin-sandbox logs from a paired Desktop Bridge plugin are **not** currently captured in Cloud Mode — use Local Mode for that.
***
### Issue: Screenshot Returns Empty Data
**Symptoms:**
* `figma_take_screenshot` succeeds but image is blank
* Base64 data is present but doesn't render
**Possible Causes:**
1. The target node ID is stale (node IDs are session-specific)
2. The node is off-canvas or hidden
3. The Desktop Bridge plugin isn't connected to the right file
**Solutions:**
Re-search for the node before screenshotting:
```javascript theme={null}
figma_search_components({ query: 'YourComponent' })
figma_take_screenshot({ nodeId: '' })
```
Verify the connected file with `figma_get_status` and make sure the node belongs to it.
***
### Issue: Claude Desktop Not Seeing Tools
**Symptoms:**
* MCP server connected but no tools visible
* Tools list is empty
**Solutions:**
#### Check Configuration
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": [
"mcp-remote",
"https://figma-console-mcp.southleft.com/sse"
]
}
}
}
```
**Important:** URL must be exactly `https://figma-console-mcp.southleft.com/sse` (note the `/sse` endpoint).
#### Restart Claude Desktop
After changing configuration:
1. Quit Claude Desktop completely
2. Restart it
3. Check the tools menu
#### Verify mcp-remote
Make sure `mcp-remote` is installed:
```bash theme={null}
npm list -g mcp-remote
```
If not installed:
```bash theme={null}
npm install -g mcp-remote
```
***
## Workflow Best Practices
### Recommended Workflow
```
# 1. Verify the Desktop Bridge plugin is connected
figma_get_status()
# 2. Pull the latest plugin console output
figma_get_console_logs({ level: 'error' })
# 3. Screenshot a specific node (re-search node IDs each session)
figma_search_components({ query: 'YourComponent' })
figma_take_screenshot({ nodeId: '' })
# 4. After plugin code changes, reload the plugin UI
figma_reload_plugin({ clearConsole: true })
# 5. Clear the server-side buffer between tests
figma_clear_console()
```
### Tips
**1. Always Verify the Bridge First**
* `figma_get_status` shows whether the Desktop Bridge plugin is connected and to which file
* If `bridge.connected` is `false`, open the plugin in Figma Desktop
**2. Re-search Node IDs Per Session**
* Node IDs are session-specific and become stale across conversations
* Run `figma_search_components` before screenshotting or instantiating
**3. Clear Console Between Tests**
* Prevents old logs from mixing with new ones
* `figma_clear_console()` or `figma_reload_plugin({ clearConsole: true })`
**4. Re-import the Manifest Only When Needed**
* Figma Desktop caches plugin files at the application level
* Re-importing is **optional for most updates** (wire-compatible upgrades) and only required when the release notes specifically say so (e.g. when the plugin adds new methods)
* When required: re-import `~/.figma-console-mcp/plugin/manifest.json` (Plugins → Manage plugins → re-import)
**5. Check Error Messages**
* Errors are prefixed `[figma-console-mcp]` so you can tell them apart from other MCPs
* Most include the next step to try
***
## Getting Help
If you're still experiencing issues:
1. **Check Error Message Details**
* Error messages include specific troubleshooting steps
* Follow the hints provided
2. **Run `figma_diagnose`**
* Returns a structured report of mode, bridge state, OAuth status, and likely causes for common failures
3. **Verify Cloud Deployment**
```bash theme={null}
curl https://figma-console-mcp.southleft.com/health
```
4. **Report Issues**
* GitHub Issues: [https://github.com/southleft/figma-console-mcp/issues](https://github.com/southleft/figma-console-mcp/issues)
* Include error messages
* Include `figma_get_status` and `figma_diagnose` output
***
## Technical Details
### Console Log Buffer
* **Size:** 1000 logs (circular buffer)
* **Capture:** Real-time via WebSocket from the Desktop Bridge plugin's QuickJS sandbox
* **Source Detection:** Plugin `console.log/warn/error/info/debug` calls are tagged with source: `figma`
### Screenshot Format
* **Formats:** PNG (lossless), JPEG (with quality control)
* **Encoding:** Base64 for easy transmission
* **Targets:** Specific node IDs via the Plugin API (`figma.getNodeByIdAsync`)
***
## Environment Variables
For local development or custom deployments:
```bash theme={null}
# Log level (trace, debug, info, warn, error, fatal)
LOG_LEVEL=info
# WebSocket bridge port range (defaults to 9223)
FIGMA_WS_PORT=9223
# WebSocket bind host (set to 0.0.0.0 when running in Docker)
FIGMA_WS_HOST=localhost
# Personal Access Token for the Figma REST API (local mode only)
FIGMA_ACCESS_TOKEN=figd_xxx
# Node environment
NODE_ENV=production
```
# Use Cases
Source: https://docs.figma-console-mcp.southleft.com/use-cases
Real-world scenarios for design system extraction, component implementation, accessibility scanning, and AI-assisted design creation.
# Use Cases & Scenarios
This guide shows real-world scenarios for using Figma Console MCP in your workflow.
## 🎨 Design System Extraction
### Scenario 4b: Extract Full Design System for AI Code Generation
**Your situation:** You want to feed your design system to an AI code generator (Lovable, v0, Replit, Cursor) so it builds with your actual tokens, components, and styles instead of generic defaults.
**What to say:**
```
"Use figma_get_design_system_kit to extract my full design system from file key abc123, then use those tokens and component specs to build a signup page"
```
**What happens:**
1. AI calls `figma_get_design_system_kit` — gets tokens, components, and styles in one call
2. Receives visual specs (exact colors, padding, typography, layout) for each component
3. Uses actual token values (light/dark modes) instead of hardcoded values
4. Builds the page using your real design system variables
**Variations:**
* "Extract only my tokens and styles" → `include: ["tokens", "styles"]`
* "Get my Button and Card components with images" → `componentIds: ["1:234", "5:678"]` + `includeImages: true`
* "Just get an inventory of what's in my design system" → `format: "compact"`
**Why use this instead of individual tools:** One call replaces `figma_get_variables` + `figma_get_component` + `figma_get_styles`, keeps the AI context window clean, and includes visual specs that individual tools don't provide.
***
### Scenario 5: Extract Design Tokens
**Your situation:** You need to extract all design variables from your Figma design system.
**What to say:**
```
"Get all design variables from https://figma.com/design/abc123 and export them as CSS custom properties"
```
**What happens:**
1. AI extracts all variables using Figma API
2. Formats them as CSS custom properties
3. Provides organized, ready-to-use CSS code
**Example output:**
```css theme={null}
:root {
/* Colors */
--color-primary-default: #4375FF;
--color-primary-hover: #2563EB;
/* Spacing */
--spacing-xs: 4px;
--spacing-sm: 8px;
/* Typography */
--font-size-body: 16px;
--line-height-body: 24px;
}
```
***
### Scenario 6: Generate Tailwind Config
**Your situation:** You want to sync your Figma variables to Tailwind CSS.
**What to say:**
```
"Get variables from https://figma.com/design/abc123 and export as Tailwind config"
```
**What happens:**
1. AI extracts variables
2. Converts to Tailwind format
3. Provides `tailwind.config.js` code
***
### Scenario 7: Audit Design System Usage
**Your situation:** You want to see which components are using specific design tokens.
**What to say:**
```
"Get all variables from my design system and show me where each one is used"
```
**What happens:**
1. AI extracts variables with enrichment enabled
2. Shows usage analysis
3. Lists which styles/components use each variable
***
## 🔧 Component Implementation
### Scenario 8: Implement Component from Figma
**Your situation:** You need to implement a Tooltip component from your design file.
**What to say:**
```
"Get the Tooltip component from https://figma.com/design/abc123?node-id=695-313 and help me implement it in React"
```
**What happens:**
1. AI fetches component data with visual reference image
2. Extracts layout, styling, and property information
3. Helps you implement with accurate spacing, colors, and behavior
**AI will provide:**
* Component image for visual reference
* Layout properties (padding, spacing, auto-layout)
* Color and typography specs
* Implementation guidance
***
### Scenario 9: Get Component Specifications
**Your situation:** You just need the specs for a component, not implementation help.
**What to say:**
```
"Get visual reference and layout specs for the Button component at node-id=123:456"
```
**What happens:**
1. AI renders component as high-res image
2. Extracts layout measurements
3. Lists color values and typography
4. You implement it yourself with accurate specs
***
### Scenario 10: Compare Multiple Component Variants
**Your situation:** You have a Button component with Primary, Secondary, and Tertiary variants.
**What to say:**
```
"Get component data for these three button variants: node-id=1:2, node-id=1:3, node-id=1:4. Show me the differences"
```
**What happens:**
1. AI fetches all three variants
2. Compares their properties
3. Highlights what changes between variants (colors, borders, padding, etc.)
***
## ✏️ Design Creation (Local Mode & Cloud Mode)
These scenarios require the Desktop Bridge plugin. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, say "connect to my Figma plugin" first to pair via the cloud relay — then all the same prompts work from web-based AI clients like Claude.ai, v0, Replit, and Lovable.
### Scenario 11: Create Component Variants with Variables
**Your situation:** You want to create a complete button component set with multiple variants, sizes, and states—all bound to design system variables.
**Prerequisites:**
* Local mode with Desktop Bridge plugin running
* Design system variables defined (colors, spacing, radius)
**What to say:**
```
"Create a button component with:
- 4 types: primary, secondary, outline, ghost
- 3 sizes: small, medium, large
- 5 states: default, hover, active, focus, disabled
Bind the colors to my design system variables (piccolo for primary, beerus for secondary, etc.) and use the spacing/radius variables for padding and border-radius."
```
**What happens:**
1. AI loads required fonts
2. Creates individual component variants (60 total: 4×3×5)
3. Applies variable bindings for colors, padding, and border-radius
4. Combines into a component set
5. Calls `figma_arrange_component_set` to organize with labels and proper layout
6. Takes a screenshot to verify the result
**Follow-up prompts:**
* "Add descriptions to each variant"
* "Adjust the hover states to use darker colors"
* "Create a similar set for icon buttons"
***
### Scenario 12: Build a Design System from Scratch
**Your situation:** You're starting a new project and need to set up design system foundations.
**What to say:**
```
"Create a design system with:
1. A color variable collection with:
- Primary colors (piccolo, beerus, goten)
- Neutral colors (bulma, trunks, goku)
- Semantic colors (success, warning, error)
2. A spacing variable collection with xs (4px) through 2xl (48px)
3. A radius variable collection with none, sm, md, lg, full
Then create a basic button component using these variables."
```
**What happens:**
1. AI creates variable collections
2. Adds variables with appropriate values
3. Creates a button component bound to the variables
4. Provides a screenshot of the result
***
### Scenario 13: Organize Existing Component Set
**Your situation:** You have a messy component set that needs proper organization with labels.
**What to say:**
```
"Find my 'Button' component set on the current page and arrange it with:
- Proper variant labels
- Purple dashed border container
- Full-width frame"
```
**What happens:**
1. AI finds the component set by name
2. Calls `figma_arrange_component_set` with your specifications
3. Variants are organized in a grid with row/column labels
4. Everything is wrapped in a properly styled container
***
### Scenario 14: Create Component with Auto-Layout
**Your situation:** You need a card component with proper auto-layout settings.
**What to say:**
```
"Create a card component with:
- Vertical auto-layout, 16px gap
- 24px padding all around
- Rounded corners (12px)
- Contains: image placeholder, title text, description text, action button
- Bind padding to my spacing variables"
```
**What happens:**
1. AI executes Plugin API code to create the frame
2. Sets up auto-layout with specified settings
3. Creates child elements (image, text, button)
4. Binds padding to design system variables
5. Converts to component
***
### Scenario 15: Add Documentation to Components
**Your situation:** You want to add descriptions to your components for design system documentation.
**What to say:**
```
"Add a description to my Button component explaining:
- When to use each variant
- Accessibility requirements
- Usage guidelines
Use markdown formatting."
```
**What happens:**
1. AI finds the Button component
2. Calls `figma_set_description` with markdown-formatted documentation
3. Description appears in Figma's component panel
***
### Scenario 16: Clone and Modify Existing Design
**Your situation:** You want to create variations of an existing component.
**What to say:**
```
"Clone my 'Card/Default' component 3 times and modify each:
1. 'Card/Compact' - reduce padding to 12px
2. 'Card/Featured' - add a colored top border
3. 'Card/Minimal' - remove the image placeholder"
```
**What happens:**
1. AI clones the component using `figma_clone_node`
2. Modifies each clone using node manipulation tools
3. Renames using `figma_rename_node`
4. Takes a screenshot to show all variations
***
### Scenario 17: Variable Mode Management (Local Mode & Cloud Mode)
**Your situation:** You need to add a dark mode to your design system variables. This works in both Local Mode and Cloud Mode (after pairing).
**What to say:**
```
"Add a 'Dark' mode to my colors collection and set up the dark mode values:
- piccolo: #60A5FA (lighter blue)
- beerus: #A78BFA (lighter purple)
- background: #1F2937 (dark gray)
- text: #F9FAFB (light gray)"
```
**What happens:**
1. AI finds the colors collection
2. Adds a new mode using `figma_add_mode`
3. Updates each variable with dark mode values using `figma_update_variable`
4. Confirms the changes
**Follow-up prompts:**
* "Show me all variables with their light and dark values"
* "Create a preview frame showing both modes"
***
### Scenario 18: Batch Component Creation
**Your situation:** You need to create a set of icon buttons with consistent styling.
**What to say:**
```
"Create icon button components for these actions:
- Edit (pencil icon)
- Delete (trash icon)
- Copy (duplicate icon)
- Share (share icon)
Each should have 3 sizes (24px, 32px, 40px) and use the same variable bindings as my regular buttons."
```
**What happens:**
1. AI creates each icon button variant
2. Applies consistent styling and variable bindings
3. Combines into a component set
4. Organizes with `figma_arrange_component_set`
5. Takes a final screenshot
***
### Scenario 19: Interactive Iteration Workflow
**Your situation:** You're creating a component and want to refine it based on visual feedback.
**What to say:**
```
"Create a navigation bar component with a logo, menu items, and a CTA button. After each step, show me a screenshot so I can give feedback."
```
**What happens:**
1. AI creates initial navigation structure → takes screenshot
2. You provide feedback ("make the menu items larger")
3. AI modifies → takes screenshot
4. Continue iterating until you're satisfied
This workflow leverages the screenshot feedback loop for precise design control.
***
## ☁️ Cloud Mode Workflows
These scenarios are for web-based AI clients (Claude.ai, v0, Replit, Lovable) that connect to Figma through the cloud relay. No local installation required — just the Desktop Bridge plugin running in Figma.
### Scenario: Connect Cloud AI to Figma (First Time)
**Your situation:** You're using Claude.ai (or v0, Replit, Lovable) and want to create or modify designs in Figma.
**What to say:**
```
"Connect to my Figma plugin so we can start designing"
```
or
```
"Pair with my Figma file"
```
**What happens:**
1. AI generates a 6-character pairing code (valid for 5 minutes)
2. You enter the code in the Desktop Bridge plugin's Cloud Mode section
3. The plugin connects to the cloud relay — you're paired
4. All Cloud Mode tools — including write/create tools — are now available through the cloud relay
**Follow-up prompts:**
* "Create a card component with an image, title, and description"
* "Update my primary color variable to #006699"
* "Show me what components are in this file"
***
### Scenario: Design System Extraction for AI Code Generators (Cloud)
**Your situation:** You're using v0, Replit, or Lovable and want your actual design tokens — not REST API snapshots that require an Enterprise plan.
**What to say:**
```
"Connect to my Figma file and extract my design system variables"
```
**What happens:**
1. AI generates a pairing code, you enter it in the plugin
2. Plugin API extracts ALL variables on any Figma plan (Pro, Org, or Enterprise)
3. AI receives full token data: colors, spacing, typography, with all mode values (Light/Dark/etc.)
4. You can now generate code using your real design system
**Why this matters:** The Figma REST API requires an Enterprise plan to access variables. Cloud Relay bypasses this limitation because the Desktop Bridge plugin uses the Plugin API, which works on all plans.
***
### Scenario: Update Design Tokens from Web Chat
**Your situation:** You're in a meeting, using Claude.ai on a laptop, and want to update a brand color across your design system.
**What to say:**
```
"Connect to Figma and change the primary brand color to #006699 across all modes"
```
**What happens:**
1. AI generates pairing code, you enter it in the Desktop Bridge plugin
2. AI reads your current variables to find the primary color
3. Updates the value across Light, Dark, and any other modes
4. Confirms the changes with the new values
***
### Scenario: Create Components from Web AI Client
**Your situation:** You're using Claude.ai to prototype a new component and want it created directly in Figma.
**What to say:**
```
"Connect to my Figma and create a notification toast with an icon, title text, and a dismiss button"
```
**What happens:**
1. AI generates pairing code, you enter it in the plugin
2. AI uses the plugin API to create a frame with auto-layout
3. Adds child elements (icon placeholder, title text, dismiss button)
4. Takes a screenshot to verify the result and show you what was created
***
## 🔍 Visual Debugging Workflows
### Scenario 20: Document Plugin State
**Your situation:** You want to show someone what your plugin looks like at a specific point.
**What to say:**
```
"Navigate to my plugin, take a full-page screenshot, and save it as 'plugin-error-state'"
```
**What happens:**
1. AI takes full-page screenshot
2. Saves with your custom filename
3. You can share the visual state with your team
***
### Scenario 21: Monitor Visual Changes
**Your situation:** Testing if plugin UI updates correctly.
**What to say:**
```
"Take a screenshot, then I'll make a change, then take another screenshot"
```
**What happens:**
1. AI takes "before" screenshot
2. You make your changes
3. AI takes "after" screenshot
4. You can compare the two states
***
## 🚀 Advanced Workflows
### Scenario 22: Full Design System Export
**Your situation:** Migrating from Figma to code.
**What to say:**
```
"Extract everything from my design system:
1. Get all variables and export as CSS
2. Get all text styles and export as Tailwind
3. Get all color styles as Sass variables
4. List all components"
```
**What happens:**
1. AI systematically extracts all design system data
2. Provides multiple export formats
3. Organizes everything for your codebase
***
### Scenario 23: Plugin Development Sprint
**Your situation:** Rapid plugin development with continuous debugging.
**Workflow:**
```
1. "Watch console for 5 minutes while I develop"
→ AI monitors in background
2. "Show me any errors from the last 2 minutes"
→ AI filters recent error logs
3. "Take a screenshot of current state"
→ Visual checkpoint
4. "Reload the plugin and clear console"
→ Fresh start
5. Repeat...
```
***
### Scenario 24: Design Token Migration
**Your situation:** Moving from Figma Styles to Variables.
**What to say:**
```
"Compare my old styles with new variables. Show me what changed and generate migration scripts"
```
**What happens:**
1. AI gets both styles and variables
2. Maps old → new
3. Identifies breaking changes
4. Suggests migration approach
***
## 💡 Tips for Effective Prompts
### ✅ Good Prompts
* **Be specific:** "Get the primary button component from [https://figma.com/design/abc123?node-id=1:2](https://figma.com/design/abc123?node-id=1:2)"
* **Include URL:** Always provide your Figma file URL
* **State intent:** "...and help me implement it in React" (tells AI what you'll do with the data)
* **Request format:** "export as CSS" vs "export as Tailwind"
### ❌ Avoid Vague Prompts
* ❌ "Get my design system" (which file?)
* ❌ "Help with my plugin" (what specifically?)
* ❌ "Show me components" (which ones? what data?)
### 🎯 Pro Tips
1. **Chain operations:** "Navigate to X, watch console for 30s, then screenshot"
2. **Use filters:** "Show me only error logs from the last minute"
3. **Be specific about formats:** "Export as Tailwind v4 syntax"
4. **Request enrichment explicitly:** "Get variables with CSS exports and usage information"
5. **Cloud Mode — connect first:** Start by saying "pair with my Figma plugin" or "connect to Figma" before asking for design changes
6. **Use natural language:** You don't need to know tool names. Say "create a blue square" not "call figma\_execute"
***
## 🔄 Integration with Other Tools
### With Figma's Official MCP Server
Figma's official MCP server provides design context for code generation and Code Connect mappings. Console MCP can check the result against the design and the token set.
**Workflow:**
1. Generate component code with the official server's `get_design_context` (and Code Connect, if your team uses it)
2. Ask Console MCP for the component's token names and values (`figma_get_component_for_development_deep` or `figma_get_variables`)
3. Replace any hardcoded values with tokens
4. Run `figma_check_design_parity` to confirm the implementation matches the Figma component
**Example:**
```
// Generated code contains a raw value
// Console MCP returns the bound token
--color-primary: #4375FF
// You refactor to the token
```
***
## 📚 More Examples
See also:
* [Tool Documentation](tools) - Complete API reference for all 121 tools
* [Architecture Overview](architecture) - Understanding deployment modes
* [Example Prompts](https://github.com/southleft/figma-console-mcp#-example-prompts) - Quick prompt examples on GitHub
* [Troubleshooting](troubleshooting) - Solutions to common issues
***
## 🐛 Plugin Development & Debugging
**Limited availability.** Console monitoring currently captures logs from the Desktop Bridge plugin sandbox only. Monitoring a separate plugin's console is not supported — Figma allows only one plugin to run at a time, and each plugin has an isolated console. This was possible in earlier versions using Chrome DevTools Protocol (CDP) but is not compatible with the current WebSocket bridge architecture. We're exploring workarounds and will update this section when a solution is available.
### Scenario: Simple Plugin Debugging
**Your situation:** You're developing a Figma plugin and want to see console output from the Desktop Bridge plugin itself.
**What to say to your AI assistant:**
```
"Check the last 20 console logs"
```
**What happens:**
1. AI retrieves console logs from the Desktop Bridge plugin sandbox
2. Shows errors, warnings, and log statements with timestamps
**Follow-up prompts:**
* "Show me just the error logs"
* "What does this stack trace mean?"
* "Help me fix this error"
**Note:** These console tools capture output from the Desktop Bridge plugin (code.js), not from other plugins running in Figma. To debug a separate plugin, you would need to use Figma's built-in DevTools (Help → Debugging → Open DevTools) alongside the MCP tools.
'
})
// Filter to WCAG 2.0 AA rules only
figma_scan_code_accessibility({
html: '',
tags: ["wcag2aa"]
})
// Auto-generate CodeSpec for parity checking
figma_scan_code_accessibility({
html: '',
mapToCodeSpec: true
})
```
**Parameters:**
* `html` (required): HTML string to scan (fragment or full document)
* `tags` (optional): WCAG tag filter — `["wcag2a"]`, `["wcag2aa"]`, `["wcag22aa"]`, `["best-practice"]`
* `context` (optional): CSS selector to scope the scan
* `mapToCodeSpec` (optional): If true, auto-generates `codeSpecAccessibility` for use with `figma_check_design_parity`
* `includePassingRules` (optional): Include pass/incomplete counts
**End-to-end workflow:**
```
1. figma_lint_design → visual a11y on design side
2. figma_audit_component_a11y → component scorecard
3. figma_scan_code_a11y → structural a11y on code side
└─ mapToCodeSpec: true → auto-generate CodeSpec
4. figma_check_design_parity → compare design intent vs code
```
***
## 📌 FigJam Tools
FigJam tools only work when the Desktop Bridge plugin is running in a FigJam board (`editorType === 'figjam'`). They return clear errors when used in Figma Design files.
### `figjam_create_sticky`
Create a sticky note on a FigJam board.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | Text content (max 5,000 chars) |
| `color` | string | No | YELLOW, BLUE, GREEN, PINK, ORANGE, PURPLE, RED, LIGHT\_GRAY, GRAY |
| `x` | number | No | X position on canvas |
| `y` | number | No | Y position on canvas |
### `figjam_create_stickies`
Batch create multiple sticky notes (max 200). Font is loaded once for the entire batch.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `stickies` | array | Yes | Array of `{text, color?, x?, y?}` objects (max 200) |
### `figjam_create_connector`
Connect two nodes with a connector line. Use node IDs from creation results.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `startNodeId` | string | Yes | Node ID of the start element |
| `endNodeId` | string | Yes | Node ID of the end element |
| `label` | string | No | Text label on the connector |
### `figjam_create_shape_with_text`
Create a labeled shape for flowcharts and diagrams.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | No | Text label |
| `shapeType` | string | No | ROUNDED\_RECTANGLE (default), DIAMOND, ELLIPSE, TRIANGLE\_UP, TRIANGLE\_DOWN, PARALLELOGRAM\_RIGHT, PARALLELOGRAM\_LEFT, ENG\_DATABASE, ENG\_QUEUE, ENG\_FILE, ENG\_FOLDER |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_table`
Create a table with optional cell data.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `rows` | number | Yes | Number of rows (1-100) |
| `columns` | number | Yes | Number of columns (1-50) |
| `data` | string\[]\[] | No | 2D array of cell text (row-major order) |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_code_block`
Create a code block for sharing snippets and technical documentation.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Code content (max 50,000 chars) |
| `language` | string | No | JAVASCRIPT, PYTHON, TYPESCRIPT, JSON, HTML, CSS, etc. |
| `x` | number | No | X position |
| `y` | number | No | Y position |
### `figjam_create_section`
Create a section to group related content on a board.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Section title |
| `x` | number | No | X position |
| `y` | number | No | Y position |
| `width` | number | No | Width in pixels (default 1000) |
| `height` | number | No | Height in pixels (default 800) |
| `fillColor` | string | No | Hex fill color, e.g. `#F5F5F5` |
### `figjam_auto_arrange`
Arrange nodes in a grid, horizontal row, or vertical column layout.
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeIds` | string\[] | Yes | Array of node IDs to arrange (max 500) |
| `layout` | string | No | `grid` (default), `horizontal`, or `vertical` |
| `spacing` | number | No | Spacing between nodes in pixels (default: 40) |
| `columns` | number | No | Grid columns (defaults to sqrt of node count) |
### `figjam_get_board_contents`
Read all content from a FigJam board. Returns stickies, shapes, connectors, tables, code blocks, and sections with their text content, positions, and type-specific properties (colors, shape types, cell data, connector endpoints).
**Mode:** Local / Cloud
**Parameters:**
| Parameter | Type | Required | Description |
| - | - | - | - |
| `nodeTypes` | string\[] | No | Filter by type: STICKY, SHAPE\_WITH\_TEXT, CONNECTOR, TABLE, CODE\_BLOCK, SECTION, FRAME, TEXT. Omit for all. |
| `maxNodes` | number | No | Maximum nodes to return (1-1000, default: 500) |
**Returns:**
* `nodes` — Array of node objects with id, type, name, position, dimensions, and type-specific data
* `totalFound` — Number of nodes returned
* `truncated` — Whether results were capped at maxNodes
* `page` — Current page name
### `figjam_get_connections`
Read the connection graph from a FigJam board. Returns all connectors as edges with their start/end node references and labels, plus a lookup of connected nodes.
**Mode:** Local / Cloud
**Parameters:** None
**Returns:**
* `edges` — Array of `{connectorId, startNodeId, endNodeId, label}`
* `connectedNodes` — Map of node ID → `{id, type, name, text}`
* `totalConnectors` — Number of connectors found
* `totalConnectedNodes` — Number of unique connected nodes
***
## ☁️ Cloud Relay
### `figma_pair_plugin`
Generate a pairing code to connect the Figma Desktop Bridge plugin to the cloud relay. This enables write operations from web-based AI clients.
**Mode:** Cloud only (available on both the `/mcp` and `/sse` endpoints)
**Parameters:** None
**Returns:**
* `code` — 6-character alphanumeric pairing code (uppercase, no ambiguous characters)
* `expiresIn` — Expiry time (5 minutes)
* Instructions for the user
**Natural language triggers:**
* "Connect to my Figma plugin"
* "Pair with my design file"
* "Set up the cloud connection"
* "Link Figma to this chat"
**How it works:**
1. Generates a unique 6-character code stored in KV with 5-minute TTL
2. User enters code in the Desktop Bridge plugin's Cloud Mode section
3. Plugin connects via WebSocket to the cloud relay Durable Object
4. All subsequent write tool calls route through the relay to the plugin
**Important:** The pairing code expires after 5 minutes. If it expires before the plugin connects, generate a new one.
***
## 🕒 Version History Tools
Six tools that turn a Figma file from a static snapshot into a queryable history. They compose: list versions → diff → generate changelog → blame specific changes back to the version that introduced them. All cache aware (past versions are immutable, so repeat queries on the same range cost zero new API calls).
**Required scope:** `file_versions:read` (OAuth) or **Versions** (Read) on a Personal Access Token, in addition to the standard `file_content:read`.
### `figma_get_file_versions`
List a file's version history with author, label, description, and timestamp metadata. Auto-paginates up to `max_versions`. Defaults to **labeled-only** (skips auto-saves) — pass `include_autosaves: true` to see every saved state.
**Usage:**
```javascript theme={null}
figma_get_file_versions({
fileUrl: 'https://www.figma.com/design/abc123/My-File', // optional
include_autosaves: false, // default
max_versions: 50, // default 50, max 200
cursor: 'vSomeId' // optional, for pagination
})
```
Returns `{ versions: [...], pagination: { has_more, next_cursor, returned, filtered_out_autosaves } }`. Each version entry includes `id`, `label`, `description`, `created_at`, `user.handle`, and `is_labeled`.
### `figma_get_file_at_version`
Snapshot a file (or selected nodes) as it existed at a past `version_id`. Thin wrapper over `figma_get_file_data` with the version param plumbed through.
**Usage:**
```javascript theme={null}
figma_get_file_at_version({
version_id: '2332825592044334783',
node_ids: ['4271:9562'], // optional — scope to specific nodes
depth: 2 // optional — limit recursion
})
```
### `figma_diff_versions`
Structured diff between two versions. Always returns a cheap page-structure diff (\~2 API calls, parallel). When `component_ids` are passed, additionally produces per-node diffs at depth=2: added/removed children (variants), name/description changes, `componentPropertyDefinitions` changes, and `boundVariables` deltas.
**Usage:**
```javascript theme={null}
figma_diff_versions({
from_version: '2285226350723738406',
to_version: '2332825592044334783', // or 'current' for HEAD
component_ids: ['4271:9562'], // optional — falls back to current Figma selection
mode: 'detailed' // 'summary' | 'standard' (default) | 'detailed'
})
```
**Note:** Variable VALUE history is not retrievable from Figma REST API. Variable definition value changes between versions are not represented; only binding-reference changes on scoped nodes are detected. This limitation is surfaced in the response's `notes[]`.
### `figma_get_changes_since_version`
Convenience wrapper for `figma_diff_versions` with `to_version="current"` (HEAD). Useful for "what's changed since the last code-sync" workflows.
```javascript theme={null}
figma_get_changes_since_version({
since_version: '2332825592044334783',
component_ids: ['4271:9562'] // optional, falls back to selection
})
```
### `figma_generate_changelog`
Markdown changelog generator. Wraps `figma_diff_versions` with author enrichment (one extra cheap API call to look up labels and authors for the from/to versions). Returns BOTH a `markdown` string ready for release notes / PRs / Storybook MDX, and the structured diff payload.
```javascript theme={null}
figma_generate_changelog({
from_version: 'vEarlier',
to_version: 'current',
component_ids: ['4271:9562'], // optional, falls back to selection
mode: 'standard' // 'summary' | 'standard' (default) | 'detailed'
})
```
Mode controls verbosity: `summary` produces a one-line release note; `standard` includes sectioned page + per-component change counts; `detailed` includes per-property and per-binding bullets.
### `figma_blame_node`
Find the version that introduced a specific change to a node — answers "who/when added this." Walks history backward via **binary search** (\~log₂(N) probes instead of N), so a 200-version lookback typically costs \~8 API calls instead of 200.
```javascript theme={null}
figma_blame_node({
node_id: '4271:9562', // optional, falls back to selection
target_component_property: 'Disabled#1:2', // OR target_child_node_id
start_version: 'current', // walk backward from here
max_versions_to_walk: 200, // default 200, max 500
include_autosaves: true // default true — better attribution
})
```
Returns `{ introduced_at: { version_id, label, created_at, user_handle, is_labeled }, attribution_certainty, summary, notes }`.
`attribution_certainty` is one of:
* `"exact"` — the introduction point is fully localized and authored by a real user
* `"system_attributed"` — the introducing version was a system-triggered autosave (`user="Figma"`); set `include_autosaves: false` and re-run to find the labeled shipping author
* `"exists_at_lookback_horizon"` — the actual introduction is older than `max_versions_to_walk`; raise the cap and retry
* `"metadata_unavailable"` — introduction was at `start_version` itself but author lookup couldn't reach it within the version-list lookback
**Honest about limits:** binary search assumes the target's existence is monotonic (added once, never removed). If the target was added, removed, then re-added, the tool may report a different introduction point than the original. This is called out in `notes[]` on every response.
***
## Error Handling
All tools return structured error responses:
```json theme={null}
{
"error": "Error message",
"message": "Human-readable description",
"hint": "Suggestion for resolution"
}
```
Common errors:
* `"FIGMA_ACCESS_TOKEN not configured"` - Set up your token (see installation guide)
* `"Failed to connect to browser"` - Browser initializing or connection issue
* `"Invalid Figma URL"` - Check URL format
* `"Node not found"` - Verify node ID is correct
* `"Desktop Bridge plugin not found"` - Ensure plugin is running in Figma
* `"Invalid hex color"` - Check hex format (use #RGB, #RGBA, #RRGGBB, or #RRGGBBAA)
See [Troubleshooting Guide](TROUBLESHOOTING.md) for detailed solutions.
# Troubleshooting
Source: https://docs.figma-console-mcp.southleft.com/troubleshooting
Solutions to common issues including browser connection, console logs, screenshots, and configuration problems.
# Troubleshooting Guide
## Connection Drops or "Not Connected"? Start Here
> **This is the most common issue, and as of v1.31.0 it is fixed at the source.** If the bridge keeps dropping and only comes back when you close the plugin, restart your MCP client, or kill ports by hand, you were hitting **zombie MCP server processes** squatting the WebSocket port range (9223–9232) after a bad shutdown. Each fresh server got bumped to a port with no plugin attached, so status read "not connected." v1.31.0 makes those zombies impossible to create and reaps any that already exist — and the plugin now reconnects itself.
### Step 1 — Update and re-import the plugin (required, one time)
The fix lives in **both** the server and the redesigned Desktop Bridge plugin, so you need both halves:
1. **Update the package** so your MCP client launches v1.31.0+ (NPX users get it automatically on next launch; pinned versions should bump to `figma-console-mcp@1.31.0` or later).
2. **Re-import the plugin** — Figma caches plugin files at the application level, so restarting your MCP client alone will *not* pick up the new plugin UI:
* Figma Desktop → **Plugins → Development → Import plugin from manifest…**
* Select `~/.figma-console-mcp/plugin/manifest.json` (the stable path the server maintains automatically)
3. Run the Desktop Bridge plugin in your file. It auto-connects.
> **You only have to do this once per plugin change.** After you're on v1.31.0+, updates don't need a re-import unless a release explicitly says so. The plugin files last changed in v1.39.0, so if your imported plugin is older than that, re-import it once. The plugin shows an update banner when the server bundles a newer plugin than the one running.
### Step 2 — Let it reconnect itself (no more restart ritual)
Once you're on v1.31.0+, you should rarely touch the connection again. Three things now keep it alive automatically:
* **Server-side self-healing.** Stale/zombie MCP servers are force-killed (`SIGTERM` → `SIGKILL`) on startup *and* swept every 5 minutes, so the port range stays clean. A hung shutdown can no longer leave an orphan behind.
* **Auto-reconnect watchdog.** If the plugin ever shows disconnected, it re-probes every \~12 seconds and reattaches the instant a server is available — **no restart needed**, even if you opened the plugin before your MCP client started.
* **One-click Reconnect.** The plugin's main button becomes **Reconnect** when a connection drops unexpectedly (and **Pause/Resume** when connected). Click it for an instant retry instead of reopening the plugin.
To confirm state at any time, ask your AI to run `figma_get_status` (or `figma_diagnose`). The plugin's log header also shows a live **`N server(s)`** badge — if that number is higher than the number of MCP clients you're running, you have stale processes (and the reaper will clear them).
### Last resort — manually clear leftover zombies (rarely needed)
You should only need this **once, right after upgrading**, to clear pre-v1.31.0 zombies that were already running before the new reaper existed (it cleans up on the *next* server start, but old processes from before the upgrade may still be holding ports). After that, the automatic reaper handles it.
```bash theme={null}
# Kill any stale Figma Console MCP servers, then clear their port-advertisement files
pkill -f figma-console-mcp
rm -f "${TMPDIR:-/tmp}"/figma-console-mcp-*.json /tmp/figma-console-mcp-*.json
```
Then reload the Desktop Bridge plugin in Figma — the watchdog reconnects to the clean server. (Port files live in the OS temp dir, which on macOS is `$TMPDIR` → `/var/folders/…`, not `/tmp`, so both paths are listed.) To inspect what's holding the range without killing anything: `lsof -i :9223-9232 | grep LISTEN`.
***
## Common Issues and Solutions
### Issue: Claude Code OAuth Completes But Connection Fails
**Symptoms:**
* Using Claude Code with `claude mcp add --transport sse`
* OAuth opens in browser and you authorize successfully
* Connection never establishes after OAuth
* Server shows "figma-console: not connected" in `/mcp`
**Cause:**
This is a [known bug in Claude Code's HTTP/SSE transport](https://github.com/anthropics/claude-code/issues/2466). The native SSE transport doesn't properly reconnect after completing the OAuth flow.
**Solution:**
Use the `mcp-remote` package instead of Claude Code's native SSE transport:
```bash theme={null}
claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse
```
Or add to `~/.claude.json` manually:
```json theme={null}
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://figma-console-mcp.southleft.com/sse"]
}
}
}
```
Restart Claude Code (`/mcp` to reconnect) — mcp-remote will open a browser for OAuth, and the connection will work correctly.
**Alternative:** If you're using Claude Code, consider using [Local Mode](/setup#-npx-setup-recommended) instead. It provides the full feature set including the Desktop Bridge plugin, and doesn't require OAuth (uses a Personal Access Token).
***
### Plugin Debugging: Simple Workflow ✅
**For Plugin Developers in Local Mode:**
> **FIRST-TIME SETUP:**
>
> 1. Open Figma Desktop normally (no special flags needed)
> 2. Go to **Plugins → Development → Import plugin from manifest...**
> 3. Select `~/.figma-console-mcp/plugin/manifest.json` (stable path created automatically by the MCP server)
> 4. Run the plugin in your Figma file — it auto-connects via WebSocket
>
> ✅ Re-importing the manifest after a package update is **optional**. Most upgrades stay wire-compatible with the previous plugin — you'll still get all functional changes. Re-import only when release notes specifically call for it (typical for plugin-side method additions), or when you want the latest cosmetic touches (status-pill copy, `pluginVersion` reporting).
### How to Verify Setup is Working
Before trying to get console logs, verify your setup:
```
"Check Figma status"
```
You should see something like:
```json theme={null}
{
"setup": {
"valid": true,
"message": "✅ Figma Desktop connected via WebSocket (Desktop Bridge Plugin)"
}
}
```
If you see `"valid": false`, the AI will provide step-by-step setup instructions.
***
### WebSocket Bridge Troubleshooting
#### Plugin Shows "Disconnected"
**Cause:** MCP server is not running (it hosts the WebSocket server on ports 9223–9232).
**Fix:** Start or restart your MCP client (Claude Code, Cursor, etc.) so the MCP server process starts.
#### Plugin Not Appearing in Development Plugins
**Cause:** Plugin manifest not imported.
**Fix:** Go to Figma → Plugins → Development → Import plugin from manifest... → select `figma-desktop-bridge/manifest.json`.
#### Port 9223 Already in Use
**Cause:** Another MCP server instance or orphaned process is running on port 9223.
**Fix:** The server automatically cleans up orphaned MCP processes on startup and falls back to the next available port in the range 9223–9232. The plugin scans the whole range on launch and picks up whichever port the server bound to.
#### Plugin Shows "MCP scanning" or "Retry"
**Cause:** The MCP server is not running yet, or all ports 9223–9232 are occupied.
**Fix:** Start your MCP client (Claude Code, Cursor, etc.) so the MCP server process starts. On v1.31.0+ the plugin's watchdog keeps probing and connects on its own the moment a server appears — you don't need to restart anything. If ports are jammed by stale processes from *before* you upgraded, see [Start Here → Last resort](#last-resort--manually-clear-leftover-zombies-rarely-needed); going forward the server's reaper clears orphans on startup and every 5 minutes automatically.
#### Plugin Shows "No MCP server found"
**Cause:** The plugin scanned every port in 9223–9232 and got no response.
**Fix:** Make sure an MCP client is running with figma-console-mcp configured. Check `figma_get_status` from your AI client.
#### Orphaned MCP Processes Filling Port Range
**Cause:** MCP clients can leave orphaned MCP server processes running after tabs/windows close (a known Claude Desktop issue, and the original root cause of the recurring "not connected until restart" reports).
**Fix (v1.31.0+):** The server now force-kills orphans it finds — escalating `SIGTERM` → `SIGKILL` so even a hung process that ignores a graceful shutdown is cleared — on startup *and* on a 5-minute background sweep. A shutdown backstop also prevents a server from zombifying in the first place. In normal use you should never need to intervene. To inspect (not kill) what's holding ports: `lsof -i :9223-9232 | grep LISTEN`. To force-clear leftovers from before you upgraded, see [Start Here → Last resort](#last-resort--manually-clear-leftover-zombies-rarely-needed).
> **Stable plugin path:** The MCP server automatically copies plugin files to `~/.figma-console-mcp/plugin/` on startup. Import from this path instead of the volatile npx cache path. Re-importing after a package update is optional — only required when the release notes call for it.
#### Running in Docker
**Cause:** The WebSocket server binds to `localhost` by default, which is unreachable from the Docker host.
**Fix:** Set `FIGMA_WS_HOST=0.0.0.0` in your container environment and expose the port with `-p 9223:9223`.
#### Plugin Connected but Commands Timeout
**Cause:** Plugin may be running in a different Figma file than expected.
**Fix:** The MCP server routes commands to the active file. Make sure the Desktop Bridge Plugin is running in the file you want to work with. Use `figma_get_status` to see which file is connected.
***
### The Simplest Workflow - No Navigation Needed!
Once setup is complete, just ask your AI to check console logs:
```
"Check the last 20 console logs"
```
Then run your plugin in Figma Desktop, and ask again:
```
"Check the last 20 console logs"
```
You'll see all your `[Main]`, `[Swapper]`, `[Serializer]`, etc. plugin logs immediately:
```json theme={null}
{
"logs": [
{
"timestamp": 1759747593482,
"level": "log",
"message": "[Main] ✓ Instance Swapping: 0 swapped, 20 unmatched",
"source": "figma"
},
{
"timestamp": 1759747593880,
"level": "log",
"message": "[Serializer] Collected 280 variables, 144 paint styles",
"source": "figma"
}
]
}
```
**That's it!** No navigation, no browser setup, no complex configuration.
***
### Issue: No Console Logs Captured
**Symptoms:**
* `figma_get_console_logs()` returns empty array
* Log count is 0
**Possible Causes:**
1. The Desktop Bridge plugin isn't running in the file you expect
2. The plugin hasn't produced output yet
3. Logs are being filtered out by level
**Solutions:**
#### Verify the plugin is connected
```
figma_get_status()
```
`bridge.connected` should be `true`, and `bridge.file.name` should match the file you're working in.
#### Re-run the plugin in Figma
The Desktop Bridge plugin captures `console.log/warn/error/info/debug` from its own QuickJS sandbox. Open the file, run **Plugins → Development → Figma Desktop Bridge**, then trigger your work.
#### Check log levels
```
figma_get_console_logs({ level: 'all' }) // Everything
figma_get_console_logs({ level: 'error' }) // Only errors
figma_get_console_logs({ level: 'log' }) // Only console.log
figma_get_console_logs({ level: 'warn' }) // Only warnings
```
> **Cloud Mode note:** In Local Mode `figma_get_console_logs` reads from the Desktop Bridge plugin's QuickJS sandbox. In Cloud Mode the Cloudflare-hosted server launches a headless browser via the Browser Rendering API and captures logs from there. Plugin-sandbox logs from a paired Desktop Bridge plugin are **not** currently captured in Cloud Mode — use Local Mode for that.
***
### Issue: Screenshot Returns Empty Data
**Symptoms:**
* `figma_take_screenshot` succeeds but image is blank
* Base64 data is present but doesn't render
**Possible Causes:**
1. The target node ID is stale (node IDs are session-specific)
2. The node is off-canvas or hidden
3. The Desktop Bridge plugin isn't connected to the right file
**Solutions:**
Re-search for the node before screenshotting:
```javascript theme={null}
figma_search_components({ query: 'YourComponent' })
figma_take_screenshot({ nodeId: '