southleft/figma-console-mcp

Figma Console MCP Server

Your design system as an API. A design-system-focused Model Context Protocol server for Figma. It works in both directions (Figma ⇄ code), writes to Figma, and runs deterministic checks for design-code parity, accessibility, and design-system health. It hands the AI exact tokens, variants, bindings, and states as structured data rather than prescribing a framework or house style, so generated code follows your team's own stack and conventions.

🆕 Shaders, grid and auto layout, OKLCH and P3 color, text wrap and variable fonts (latest v1.46.0): apply shaders and set their properties by name (figma_apply_shader, figma_list_shaders), set auto layout or grid layout in one call with CSS-style grid tracks (figma_set_layout), use OKLCH, Display P3 and other CSS colors on fills and strokes, and set text wrap (balance, pretty) and variable-font axes with figma_set_text (v1.46.0). v1.45 added Motion: animate layers with presets, custom animation styles or keyframes bound to Timing and Easing tokens, export video, and find code layers. See what's new →

What is this?

Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:

• 🎨 Design system extraction - Pull variables, components, and styles
• 🧬 Codebase → design system extraction - Scan a production codebase, mine its de-facto styling into DTCG tokens with per-token provenance, scaffold a design-system package with a wired Storybook workshop, and gate it with deterministic fidelity evals — then round-trip the tokens into Figma variables (Local Mode)
• 🔁 Bidirectional token sync - Export Figma variables to DTCG JSON (legacy or 2025.10 dialect) + 9 more formats; push code-side edits back to Figma with full apply — creates, renames, alias re-targeting, and replace-gated deletes. Replaces Style Dictionary and Tokens Studio's export pipeline.
• 📸 Visual debugging - Take screenshots for context
• ✏️ Design creation - Create UI components, frames, and layouts directly in Figma — including one-call component-set creation from a variant axes matrix
• 🔧 Variable management - Create, update, rename, and delete design tokens
• 🕰 Version history & time-series awareness - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame, and fold per-component design + git history into generated component docs
• ⚡ Real-time monitoring - Watch console logs from the Desktop Bridge plugin
• 📌 FigJam boards - Create stickies, flowcharts, tables, and code blocks on collaborative boards
• 🎞️ Slides presentations - Build and manage Figma Slides decks programmatically
• ♿ Accessibility scanning - 14 WCAG design checks with conformance level tagging, component scorecards, axe-core code scanning, design-to-code parity
• 🔍 Design-code parity & component docs - Deterministic comparison of a Figma component with its code (visual, spacing, typography, tokens, component API, accessibility), and generated component documentation with per-variant tokens and an optional design + git changelog
• 📋 Design-system health audits - Lighthouse-style scored audit across naming, tokens, component metadata, accessibility, consistency, and coverage — available as a plain tool for any MCP client (with per-finding auto-fix guidance) and as a visual dashboard app
• 🛡 Cross-MCP identity - Every tool response carries _mcp: "figma-console-mcp" and errors are prefixed [figma-console-mcp] so attribution stays unambiguous in agents running multiple Figma MCPs
• ☁️ Cloud Write Relay - Web AI clients (Claude.ai, v0, Replit) can design in Figma via cloud pairing
• 🔄 Four ways to connect - Remote SSE, Cloud Mode, NPX, or Local Git

---

⚡ Quick Start

Choose Your Setup

First, decide what you want to do:

| I want to... | Setup Method | Time | |--------------|--------------|------| | Create and modify designs with AI | NPX Setup (Recommended) | ~10 min | | Design from the web (Claude.ai, v0, Replit, Lovable) | Cloud Mode | ~5 min | | Contribute to the project | Local Git Setup | ~15 min | | Just explore my design data (read-only) | Remote SSE | ~2 min |

⚠️ Important: Capability Differences

| Capability | NPX / Local Git | Cloud Mode | Remote SSE | |------------|-----------------|------------|------------| | Read design data | ✅ | ✅ | ✅ | | Create components & frames | ✅ | ✅ | ❌ | | Edit existing designs | ✅ | ✅ | ❌ | | Manage design tokens/variables | ✅ | ✅ | ❌ | | FigJam boards (stickies, flowcharts) | ✅ | ✅ | ❌ | | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ | | Codebase → design system extraction (figma_ds_*) | ✅ | ❌ | ❌ | | Desktop Bridge plugin | ✅ | ✅ | ❌ | | Requires Node.js | Yes | No | No | | Total tools available | 130 | 105 after pairing | Read-only subset |

Bottom line: Remote SSE is read-only until you pair the plugin. Cloud Mode unlocks write access (105 tools) from web AI clients without Node.js. NPX/Local Git gives the full 130 tools with real-time monitoring.

---

🚀 NPX Setup (Recommended)

Best for: Designers who want full AI-assisted design capabilities.

What you get: All 130 tools including design creation, variable management, and component instantiation.

Prerequisites

• [ ] Node.js 18+ — Check with node --version (Download)
• [ ] Figma Desktop installed (not just the web app)
• [ ] An MCP client (Claude Code, Cursor, Windsurf, Claude Desktop, etc.)

Step 1: Get Your Figma Token

1. Go to 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 scopes (all Read unless noted): File content, File versions, Library content, Library assets, Comments (Read and write), Current user, and Variables (Enterprise only, optional). See why each is needed 5. Copy the token — you won't see it again! (starts with figd_)

Step 2: Configure Your MCP Client

Claude Code (CLI):

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

OpenAI Codex (CLI):

codex mcp add figma-console --env FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE --env ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest

Then set startup_timeout_sec = 60 and tool_timeout_sec = 300 for it in ~/.codex/config.toml (Codex's 10 s / 60 s defaults are too short). The Codex app and IDE extension share this config. Full Codex setup →

Gemini CLI:

gemini mcp add -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true figma-console npx -y figma-console-mcp@latest

Google Antigravity (IDE, CLI, app): add the JSON below to ~/.gemini/config/mcp_config.json, plus "timeoutSeconds": 300 in the server entry. Full Antigravity setup →

Cursor / Windsurf / Claude Desktop:

Add to your MCP config file (see Where to find your config file below):

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}

📂 Where to Find Your Config File

If you're not sure where to put the JSON configuration above, here's where each app stores its MCP config:

| App | macOS | Windows | |-----|-------|---------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | %APPDATA%\Claude\claude_desktop_config.json | | Claude Code (CLI) | ~/.claude.json | %USERPROFILE%\.claude.json | | Cursor | ~/.cursor/mcp.json | %USERPROFILE%\.cursor\mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | %USERPROFILE%\.codeium\windsurf\mcp_config.json | | OpenAI Codex (app, CLI, IDE) | ~/.codex/config.toml (TOML, see format) | %USERPROFILE%\.codex\config.toml | | Gemini CLI | ~/.gemini/settings.json | %USERPROFILE%\.gemini\settings.json | | Google Antigravity (IDE, CLI, app) | ~/.gemini/config/mcp_config.json | %USERPROFILE%\.gemini\config\mcp_config.json |

Tip for designers: The ~ symbol means your home folder. On macOS, that's /Users/YourName/. On Windows, it's C:\Users\YourName\. You can open these files in any text editor — even TextEdit or Notepad.

> Can't find the file? If it doesn't exist yet, create it. The app will pick it up on its next restart. Make sure the entire file is valid JSON (watch for missing commas or brackets).

> Claude Code users: You can skip manual editing entirely. Just run the claude mcp add command above and it handles everything for you.

Step 3: Connect to Figma Desktop

Desktop Bridge Plugin: 1. Open Figma Desktop normally (no special flags needed) and open a file 2. Go to Plugins → Development → Import plugin from manifest... 3. Select ~/.figma-console-mcp/plugin/manifest.json (stable path, auto-created by the MCP server). Run npx figma-console-mcp --print-path to print the exact path for your machine. 4. Run the plugin in your Figma file — it scans ports 9223–9232 and connects automatically to your running MCP server

Can't see the folder in the import dialog? .figma-console-mcp starts with a dot, so macOS hides it. In the dialog, press ⌘⇧G and paste the path (or press ⌘⇧. to show hidden files). On Windows the folder is visible as normal.

Heads-up on plugin updates. Figma caches plugin files (code.js and ui.html) at the application level. The MCP server refreshes the files at ~/.figma-console-mcp/plugin/ on every startup, but Figma keeps using its cached copy until you re-import the manifest.

> Re-importing is _required_ only when a release notes entry says so — typically when the plugin adds a new method the server needs (e.g. v1.22.4, v1.10.0). The plugin files last changed in v1.41.5; 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 most upgrades the new server stays wire-compatible with the previous plugin, and re-importing is optional: you'll still get every functional change, just not the cosmetic plugin-side touches (status-pill copy, pluginVersion reporting).

> When you do re-import: Plugins → Manage plugins → re-import ~/.figma-console-mcp/plugin/manifest.json. The stable path never changes, so it's a one-click step.

Step 4: Restart Your MCP Client

Restart your MCP client to load the new configuration.

Step 5: Test It!

Check Figma status

→ Should show connection status with active WebSocket transport

Create a simple frame with a blue background

→ Should create a frame in Figma (confirms write access!)

📖 Complete Setup Guide

---

For Contributors: Local Git Mode

Best for: Developers who want to modify source code or contribute to the project.

What you get: Same 130 tools as NPX, plus full source code access.

Quick Setup

# Clone and build
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run build:local

Configure Your MCP Client

Add to your config file (see Where to find your config file):

{
  "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"
      }
    }
  }
}

Then follow NPX Steps 3-5 above.

📖 Complete Setup Guide

---

📡 Remote SSE (Read-Only Exploration)

Best for: Quickly evaluating the tool or read-only design data extraction.

What you get: the read-only tools — view file data, components, styles, comments and version history, take screenshots, read logs, check design-code parity. Cannot create or modify designs.

Claude Desktop (UI Method)

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" — Done! ✅

OAuth authentication happens automatically when you first use design system tools.

Claude Code

⚠️ Known Issue: Claude Code's native --transport sse has a bug. Use mcp-remote instead:

claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse

💡 Tip: For full capabilities, use NPX Setup instead of Remote SSE.

Other Clients (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://figma-console-mcp.southleft.com/sse"]
    }
  }
}

Upgrading to Full Capabilities

Ready for design creation? Follow the NPX Setup guide above, or try Cloud Mode if you don't want to install Node.js.

📖 Complete Setup Guide

---

☁️ Cloud Mode (Web AI Clients)

Best for: Using Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no Node.js required.

What you get: 105 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.

Prerequisites

• [ ] Figma Personal Access Token — Create one here (starts with figd_)
• [ ] Figma Desktop with the Desktop Bridge plugin installed (see Desktop Bridge setup)
• [ ] A web AI client that supports MCP (Claude.ai, Lovable, v0, Replit, etc.)

Step 1: Add the MCP Connector

Add this endpoint to your AI platform's MCP settings:

URL: https://figma-console-mcp.southleft.com/mcp Auth: Your Figma PAT as Bearer token

In Claude.ai: Settings → Connectors → Add Custom Connector → paste the URL above. In Lovable/v0/Replit: Look for "Add MCP Server" or "Integrations" in settings → paste the URL and add your token.

Step 2: Pair the Plugin

1. Open the Desktop Bridge plugin in Figma Desktop (Plugins → Development → Figma Desktop Bridge) 2. Tell your AI assistant:

   Connect to my Figma plugin
   

3. The AI gives you a 6-character pairing code (expires in 5 minutes) 4. In the plugin: Toggle "Cloud Mode" → enter the code → click Connect 5. You're paired! Full write access is now available

What You Can Do

Once paired, use natural language to design:

Create a card component with a header image, title, description, and action button
Set up a color token collection with Light and Dark modes
Add a "High Contrast" mode to my existing token collection

How It Works

Your AI client sends write commands through the cloud MCP server, which relays them via WebSocket to the Desktop Bridge plugin running in your Figma Desktop. The plugin executes the commands using the Figma Plugin API and returns results back through the same path.

AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugin → Figma

Variables on any plan: Cloud Mode uses the Plugin API (not the Enterprise REST API), so variable management works on Free, Pro, and Organization plans.

📖 Complete Setup Guide

---

📊 Installation Method Comparison

| Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE | |---------|-------------------|------------|-----------|------------| | Setup time | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes | | Total tools | 130 | 105 after pairing | 130 (Local Git) | Read-only subset | | Design creation | ✅ | ✅ | ✅ | ❌ | | Variable management | ✅ | ✅ | ✅ | ❌ | | Component instantiation | ✅ | ✅ | ✅ | ❌ | | FigJam boards | ✅ | ✅ | ✅ | ❌ | | Real-time monitoring | ✅ | ❌ | ✅ | ❌ | | Desktop Bridge plugin | ✅ | ✅ | ✅ | ❌ | | Variables (no Enterprise) | ✅ | ✅ | ✅ | ❌ | | Console logs | ✅ (zero latency) | ❌ | ✅ (zero latency) | ✅ | | Read design data | ✅ | ✅ | ✅ | ✅ | | Requires Node.js | Yes | No | Yes | No | | Authentication | PAT (manual) | OAuth (automatic) | PAT (manual) | OAuth (automatic) | | Automatic updates | ✅ (@latest) | ✅ | Manual (git pull) | ✅ | | Source code access | ❌ | ❌ | ✅ | ❌ |

Key insight: Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 130 tools.

📖 Complete Feature Comparison

---

🎯 Test Your Connection

After setup, try these prompts:

Basic test (all modes):

Navigate to https://www.figma.com and check status

Design system test (requires auth):

Get design variables from [your Figma file URL]

Cloud Mode test:

Connect to my Figma plugin

→ Follow the pairing flow, then try: "Create a simple blue rectangle"

Plugin test (Local Mode only):

Show me the primary font for [your theme name]

---

🔐 Authentication

Remote Mode - OAuth (Automatic)

When you first use design system tools: 1. Browser opens automatically to Figma authorization page 2. Click "Allow" to authorize (one-time) 3. Token stored securely and refreshed automatically 4. Works with Free, Pro, and Enterprise Figma plans

Local Mode - Personal Access Token (Manual)

1. Visit https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens 2. Generate token with scopes (all Read unless noted): File content, File versions, Library content, Library assets, Comments (Read and write), Current user, and Variables (Enterprise only, optional) 3. Add to MCP config as FIGMA_ACCESS_TOKEN environment variable

---

🛠️ Available Tools

Status & Diagnostics

• figma_get_status - Check WebSocket bridge connection and file context
• figma_diagnose - Designer-readable health check + setup guidance
• figma_reconnect - Force reconnect to the Desktop Bridge plugin
• figma_navigate - Switch the active file target among connected plugins (Local), or navigate the cloud headless browser (Remote/Cloud)
• figma_list_open_files - List files connected through the Desktop Bridge and which one is active (Local Mode)

Console Debugging

• figma_get_console_logs - Retrieve console logs
• figma_watch_console - Real-time log streaming
• figma_clear_console - Clear log buffer
• figma_reload_plugin - Reload current page

Visual Debugging

• figma_take_screenshot - Export an image of a page or node (Desktop Bridge first, REST fallback)
• figma_capture_screenshot - Render a node from the plugin runtime, reflecting changes that haven't reached the REST API yet

👁️ Real-Time Awareness (Local Mode only)

• figma_get_selection - The nodes currently selected in Figma
• figma_get_design_changes - Buffered document-change events, for polling what changed

Design System Extraction

• figma_get_design_system_kit - Full design system in one call — tokens, components, styles, visual specs
• figma_get_variables - Extract design tokens/variables
• figma_get_component - Get component data (metadata or reconstruction spec)
• figma_get_component_for_development - Component + image
• figma_get_component_image - Just the image
• figma_get_styles - Color, text, effect styles
• figma_get_file_data - Full file structure
• figma_get_file_for_plugin - Optimized file data
• figma_get_design_system_summary / figma_get_token_values - Compact design-system overview and variable values by mode (Local Mode only)
• figma_audit_design_system_report - Scored health audit for any MCP client — six-category report (naming, tokens, metadata, accessibility, consistency, coverage) with per-finding remediation ("can this MCP fix it?"), chunked per-category drill-down, live-first data with disclosed source, 5-minute cache

📚 Shared Library Inspection

• figma_get_library_component_by_key - Resolve any component key to full properties + variants + visual specs — without needing the source library file's URL. Works for both COMPONENT_SET and standalone COMPONENT keys. Adaptive compression at >500KB.
• figma_get_library_components - Discover all components in a library file (requires library file URL/key)
• figma_get_library_variables - List every variable from team libraries the current file has subscribed. Works on every Figma plan — uses the Plugin API path, not the Enterprise-only REST endpoint. Filter by libraryName, collectionName, or resolvedType.
• figma_import_library_variable - Import a library variable into the current file. Returns a local id ready to pass to figma_set_fills / figma_update_variable / any variable-binding tool.

☁️ Cloud Relay

• figma_pair_plugin - Generate a pairing code to connect a Desktop Bridge plugin via the cloud relay

✏️ Design Creation (Local Mode + Cloud Mode)

• figma_execute - Power tool: Run any Figma Plugin API code to create designs
• Create frames, shapes, text, components
• Apply auto-layout, styles, effects
• Build complete UI mockups programmatically
• Optional fileKey targets one specific connected file directly (Local Mode only), without touching the active file or target lock
• figma_execute_across_files - Local Mode only. Run the same script in several Desktop Bridge-connected files at once, concurrently, returning a per-file result map — for cross-file consistency checks and fixes across a multi-file design system, replacing "open file, run plugin, repeat per file"
• Name the files with fileKeys (from figma_list_open_files), or pass allFiles: true to hit every connected file — one of the two is required, so a script never fans out to files you didn't mean to touch
• Per-file timeouts and error isolation: one slow or failing file doesn't delay or fail the others
• figma_create_component_set - Create a component set with variants in one declarative call
• Generate every variant combination from an axes matrix (e.g. { State: ["default", "hover", "disabled"], Size: ["sm", "lg"] } → 6 variants) off a ba