Internal docs / Design tooling / Figma Console MCP setup

Figma Console MCP setup

Connect your AI client to Figma so it can read, debug and create designs directly in your files. This guide covers Claude Desktop, Claude Code (CLI) and Codex (CLI) on macOS, about ten minutes from start to finish.

Platform macOS
Clients Claude Desktop · Claude Code · Codex
Time required ~10 minutes
Tools unlocked 100+

Prerequisites

Three things to have ready before you start.

  1. Node.js 18 or newer. Open Terminal and run node --version. If you see anything below 18 (or "command not found"), grab the installer from nodejs.org.
  2. Figma Desktop app. The native macOS app, not the browser version. Download from figma.com/downloads.
  3. One of these AI clients:
    • Claude Desktop — the native Mac app.
    • Claude Code — Anthropic's CLI (brew install --cask claude-code or npm i -g @anthropic-ai/claude-code).
    • Codex CLI — OpenAI's CLI (brew install codex or npm i -g @openai/codex).
1

Get a Figma personal access token

2 min
  1. Go to figma.com/developers/api#access-tokens.
  2. Click Get personal access token.
  3. Description: Figma Console MCP.
  4. Scopes: File content (Read), File versions (Read), Variables (Read), Comments (Read and write).
  5. Copy the token immediately. It starts with figd_ and Figma only shows it once.
!
Save it somewhere safe.

1Password, Bitwarden, or a locked Note. You'll need it in step 3. If you lose it, generate a new one.

2

Download the repo and place it in your home directory

2 min

You need a local copy of the repo so Figma can import the Desktop Bridge plugin manifest from a stable path.

  1. Open github.com/southleft/figma-console-mcp.
  2. Click the green Code button, then Download ZIP.
  3. Unzip the file. You'll get a folder named figma-console-mcp-main.
  4. Rename it to figma-console-mcp and move it into your home directory so the final path is:
    macOS path ~/figma-console-mcp/
i
Quickest way on macOS.

After unzipping, open Finder, press Cmd+Shift+H to jump to your home folder, then drag the renamed folder in.

3

Configure your AI client

3 min

Pick the tab for the client you use. Swap in your real token from step 1 wherever you see figd_YOUR_TOKEN_HERE.

Open Claude Desktop and go to Settings → Developer → Edit Config. That opens the config file in your default editor. If the menu isn't there, the file lives here:

macOS path ~/Library/Application Support/Claude/claude_desktop_config.json

Paste the block below. If there's already content, merge the figma-console entry into the existing mcpServers object.

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

Save the file, then fully quit Claude Desktop (Cmd+Q or right-click the dock icon → Quit). Reopen it.

One terminal command sets everything up. It registers the server at the user scope, so it's available across all your projects.

Terminal 
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

Then verify it's wired up:

Terminal 
claude mcp list

You should see figma-console in the list. If you ever need to edit the config by hand, it lives at ~/.claude.json.

i
Inside an existing Claude Code session?

Type /mcp to see live status and connect/disconnect. After running the add command above, restart the session for the server to be picked up.

Codex stores its MCP servers in TOML, not JSON. Open the config file:

macOS path ~/.codex/config.toml

If the file doesn't exist yet, create it. Append the block below (or merge it if you already have other [mcp_servers.*] entries):

~/.codex/config.toml 
[mcp_servers.figma-console]
command = "npx"
args = ["-y", "figma-console-mcp@latest"]
env = { FIGMA_ACCESS_TOKEN = "figd_YOUR_TOKEN_HERE", ENABLE_MCP_APPS = "true" }

Save the file. Any new Codex session will pick up the server automatically. Verify with:

Terminal 
codex mcp list
!
TOML, not JSON.

Codex uses TOML even though most other MCP clients use JSON. Watch the syntax, no trailing commas, quoted strings.

i
Why ENABLE_MCP_APPS=true?

Turns on the optional MCP Apps protocol, which unlocks richer in-client experiences (interactive token browsers, design audits) on clients that support it. Safe to leave on.

4

Install the Desktop Bridge plugin in Figma

3 min

The Desktop Bridge plugin is what lets your AI client actually talk to your Figma file. Same setup regardless of which client you picked in step 3.

  1. Open any Figma file in Figma Desktop.
  2. Go to Plugins → Development → Import plugin from manifest…
  3. Navigate to ~/figma-console-mcp/figma-desktop-bridge/ and select manifest.json.
    manifest ~/figma-console-mcp/figma-desktop-bridge/manifest.json
  4. The plugin now lives under Plugins → Development → Figma Desktop Bridge. Run it from any file you want the AI to interact with.
i
One-time import.

The plugin uses a bootloader, so it pulls the latest UI from your local MCP server every time it runs. You don't need to re-import when the server updates.

!
The plugin must be running.

Keep the Figma Desktop Bridge window open in the file you want to edit. Close it and the AI loses its WebSocket connection.

5

Test the connection

<1 min

Open your AI client (Claude Desktop / Claude Code / Codex) and send:

Check Figma status

You should see a connection status confirming the WebSocket transport is active. If that works, try a write test:

Create a simple frame with a blue background

If a frame appears in your open Figma file, you're done. Welcome aboard.

Key guidelines

How to actually get good results out of this thing, learned the hard way. Read these once before you start.

01

Open one Figma file, then run the plugin

The plugin connects to whichever file is in front when you launch it. Open the right file first, then run Plugins → Development → Figma Desktop Bridge. Switching files mid-session can confuse the AI about which document it's editing.

02

Start every session with "Check Figma status"

Confirms the bridge is alive before you ask the AI to do real work. Saves you from a debugging spiral when it turns out the plugin just wasn't running.

03

Lean on your design system, don't recreate it

Ask the AI to find components first ("search for a Button component"), then instantiate them. Letting it draw raw rectangles produces designs that ignore your tokens and conventions.

04

Be specific about constraints

"Create a login card" produces generic output. "Create a login card, 480px wide, 32px padding, 16px radius, using the Input and PrimaryButton components" produces something you can ship.

05

Ask for screenshots, then iterate

After any non-trivial creation, ask the AI to take a screenshot and critique its own work. The built-in visual validation loop catches alignment and spacing issues that the code-side review misses.

06

Work in a scratch frame, not on the canvas

Have the AI place new work inside a named Section or Frame, never floating on the page. Keeps the file tidy and makes it easy to throw away experiments without leaving orphan layers everywhere.

07

Use the design system as the source of truth

If you spot drift between Figma and code, decide which side is canonical before asking the AI to sync. "Update Figma to match the code" and "update the code to match Figma" are very different operations.

08

Treat variables like a database

Use the batch variable tools (figma_batch_create_variables, figma_batch_update_variables) for anything more than a handful of tokens. 10-50x faster, and the AI gets fewer chances to mess up halfway through.

09

Keep your token secret

The Figma token is yours alone. Never paste it into a shared chat, a screenshot, or a commit. If you suspect it's leaked, revoke and rotate from Figma settings immediately.

10

Read the diff before accepting big changes

The AI can make sweeping changes very quickly. For bulk edits (renaming variables, restructuring component sets), use Figma's version history and review what changed before continuing.

The "Visual Validation" loop the server enforces

When you ask the AI to create or modify designs, it follows this loop. Don't fight it, it's what makes the output usable.

  1. Create — execute the design code in Figma.
  2. Screenshot — capture the result.
  3. Analyse — check alignment, spacing, proportions, visual balance.
  4. Iterate — fix issues (up to 3 times by default).
  5. Verify — final screenshot to confirm.

Troubleshooting

The usual suspects, in order of frequency.

"Command not found: npx"

Node.js isn't installed properly. Reinstall from nodejs.org, then fully quit and reopen Terminal (and your AI client) so they pick up the new PATH.

"Check Figma status" reports not connected

The Desktop Bridge plugin needs to be actively running in your open Figma file. Re-run it from Plugins → Development → Figma Desktop Bridge. The plugin window must stay open during the session.

Claude Code doesn't see the server

Run claude mcp list. If figma-console isn't there, the add command didn't land, re-run it. If it's there but disconnected, start a fresh Claude Code session, then run /mcp inside it to inspect status.

Codex can't find the server

Confirm ~/.codex/config.toml exists and your block is under the right section header ([mcp_servers.figma-console], with the dot). Run codex mcp list to verify. If the syntax is wrong, Codex usually ignores the file silently.

Claude Desktop doesn't see any Figma tools at all

Did you fully quit Claude Desktop? Closing the window isn't enough on macOS, use Cmd+Q or right-click the dock icon and select Quit, then reopen.

JSON or TOML errors when saving the config

For JSON: watch for trailing commas, missing brackets, or smart quotes (" instead of "). Paste into jsonlint.com to find the issue. For TOML: no trailing commas inside inline tables, no curly quotes, header line must be exactly [mcp_servers.figma-console].

The token doesn't seem to work

Double-check it starts with figd_, with no spaces or line breaks. Make sure the scopes are set (File content, File versions, Variables, Comments). If in doubt, generate a fresh token from Figma.

macOS blocks opening the plugin folder

If Gatekeeper grumbles about ~/.figma-console-mcp, the folder is hidden by default. In Finder, press Cmd+Shift+G and paste the path directly. Only happens once.

Example prompts

A sampler of what to ask the AI once everything's connected.

Extraction
Get all design variables from [Figma URL]
Audit
Audit the design system and show the scorecard
Creation
Create a notification toast with icon, title, dismiss
Components
Arrange these button variants into a component set
Tokens
Browse the design tokens (opens interactive browser)
Styles
Extract the colour styles and show CSS exports
Parity
Compare this Button in Figma to the React component
History
When was the danger colour token added, and by whom?

Full tool reference: docs.figma-console-mcp.southleft.com.

Source View on GitHub → Reference Full documentation →

Internal documentation for the IFG / Cur8 design team.