Documentation Index

Fetch the complete documentation index at: https://docs.figma-console-mcp.southleft.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Figma Console MCP - Setup Guide

​

🎯 Choose Your Setup

​

⚠️ Important: Capability Differences

Bottom line: Remote mode is read-only with 22 tools. Cloud Mode adds write access ((83 tools)) without Node.js. Local (NPX/Git) has everything (94+ tools) including real-time monitoring.

​

🎓 Community Setup Guides

​

🚀 NPX Setup (Recommended)

​

Prerequisites Checklist

• Node.js 18+ installed — Check with node --version (Download)
• 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 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:

💡 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 — it uses a graphical interface instead of JSON config files.

​

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

• macOS / Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

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

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

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 bootloader scans ports 9223–9232, loads the latest UI from the MCP server, and connects automatically

One-time setup. The plugin uses a bootloader architecture — Figma caches a thin loader that dynamically fetches the full plugin UI from the MCP server each time it opens. When the MCP server updates, the plugin automatically gets the new code without re-importing.

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.

​

Multi-Instance / Port Conflicts

• 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 or re-importing needed

​

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)

Check Figma status

Search for button components

Create a simple frame with a blue background

​

🔧 Local Git Setup (Alternative)

​

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

# 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

​

Step 3: 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 -- node /absolute/path/to/figma-console-mcp/dist/local.js

• macOS / Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

{
  "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.)

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

• 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

​

Step 5: Restart Your MCP Client and Test

​

Updating

cd figma-console-mcp
git pull
npm install
npm run build:local

​

☁️ Cloud Mode (Web AI Clients)

​

Prerequisites

• Figma Personal Access Token — Create one here (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)

​

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 small “MCP ready” indicator

First time? Import the plugin once: In Figma go to Plugins → Development → Import plugin from manifest → select ~/.figma-console-mcp/plugin/manifest.json. This is a one-time step — the bootloader handles all future updates automatically.

​

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 (44 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)

Want write access? See Cloud Mode above — same remote endpoint, plus Desktop Bridge pairing for full design creation.

​

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)

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! ✅

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

​

Option B: Streamable HTTP Endpoint (AI Code Generators)

​

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

​

🤖 GitHub Copilot (VS Code)

​

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)

# 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"}'

code --add-mcp '{"name":"figma-console","type":"sse","url":"https://figma-console-mcp.southleft.com/sse"}'

​

Manual Configuration

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

​

Prerequisites

• OpenAI Codex desktop app installed
• Node.js 18+ installed
• Figma Desktop installed
• Figma Personal Access Token (get one)

​

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:

6. Click Save

💡 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

​

Step 3: Test It

Use the Figma Console connector to check Figma status

​

Equivalent JSON Config

​

🛠️ Troubleshooting

​

Quick Fixes

​

Node.js Version Issues

# Check your version
node --version

# Should show v18.x.x or higher

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

# This has a known bug
claude mcp add figma-console --transport sse https://figma-console-mcp.southleft.com/sse

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

claude mcp add figma-console -s user -- npx -y figma-console-mcp@latest

​

Config File Syntax Errors

1. Validate your JSON: Use a tool like 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
2. Ask in 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

Note: MCP Apps require a client with ext-apps protocol support.

​

Next Steps

1. Try example prompts: See Use Cases for workflow examples
2. Explore all tools: See Tools Reference for the complete tool list
3. Learn about the Desktop Bridge plugin: See Desktop Bridge README for advanced configuration

​

Support

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📊 Mode Comparison