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)

Remote Mode - Runs in Cloudflare Workers (cloud, read-only)
Cloud Mode - Runs in Cloudflare Workers + Cloud Write Relay (cloud, read/write)
Local Mode - Runs on your machine (Node.js, full capabilities)

Setup Methods (How You Connect)

Remote SSE/HTTP - URL-based connection (uses Remote Mode, read-only)
Cloud Mode - Remote endpoint + Cloud Write Relay via Desktop Bridge plugin (uses Cloud Mode)
NPX - npm package distribution (uses Local Mode)
Local Git - Source code clone (uses Local Mode)

Authentication Methods (How You Authenticate)

OAuth - Automatic browser-based auth (Remote SSE only)
Personal Access Token (PAT) - Bearer token (Remote /mcp endpoint, Cloud Mode)
Personal Access Token (PAT) - Environment variable (NPX + Local Git)
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)	114	Yes	Yes	Yes
Cloud Mode (Remote + Relay)	101	Yes	No	No
Remote Mode (read-only)	9	No	No	No

Bottom line: Remote mode is read-only (9 tools). Cloud Mode adds write access (101 tools) without Node.js. Local has everything (114 tools) including real-time monitoring.

Use NPX Setup (Recommended for Most Users)

✅ All 114 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)

✅ 101 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 114 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
❌ Only 9 tools — 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	9 (read-only)	93 (read/write)	101 (full)	101 (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 Extraction	✅	✅	✅	Variables, components, styles via Figma API
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
9 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
101 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 114 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:

Open Claude Desktop → Settings → Connectors
Click “Add Custom Connector”
Paste URL: https://figma-console-mcp.southleft.com/sse
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:

Connect your web AI client to the /mcp endpoint with your Figma PAT
Tell your AI to connect to your Figma plugin (natural language)
AI generates a 6-character pairing code
In the Desktop Bridge plugin, toggle “Cloud Mode” and enter the code
Done ✅ — 101 tools with full write access

NPX

Prerequisites:

Node.js 18+
Figma Desktop installed
Figma Personal Access Token (get one)

Setup Time: 10 minutes Steps:

Get Figma Personal Access Token
Add to MCP config with FIGMA_ACCESS_TOKEN env var
Install the Desktop Bridge Plugin (one-time — Plugins → Development → Import from manifest)
Restart your MCP client

Local Git

Prerequisites:

Node.js 18+
Git
Figma Desktop installed
Figma Personal Access Token (get one)

Setup Time: 15 minutes Steps:

Clone repository: git clone https://github.com/southleft/figma-console-mcp.git
Run npm install && npm run build:local
Get Figma Personal Access Token
Configure MCP client JSON config with path to dist/local.js
Set FIGMA_ACCESS_TOKEN environment variable
Install the Desktop Bridge Plugin (one-time — Plugins → Development → Import from manifest)
Restart your MCP client

Authentication Comparison

Remote SSE - OAuth (Automatic) ⭐ Simplest

Method: Remote read-only mode (SSE endpoint) How it works:

First design system tool call triggers OAuth
Browser opens automatically to Figma authorization page
User authorizes app (one-time)
Token stored in Cloudflare KV (persistent across sessions)
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:

User creates PAT and provides it as Bearer token when connecting to /mcp endpoint
AI generates a 6-character pairing code (valid for 5 minutes)
User enters code in Desktop Bridge plugin (Cloud Mode toggle)
Relay authenticates the plugin-to-cloud connection
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:

User creates PAT at https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
Set as FIGMA_ACCESS_TOKEN environment variable in MCP config
MCP server uses PAT for all API calls
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 114 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:

Open Figma Desktop (normal launch — no debug flags needed)
Go to Plugins → Development → Import plugin from manifest…
Select figma-desktop-bridge/manifest.json from the figma-console-mcp directory
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 114 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. 101 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 94-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)
❌ 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 114 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): 9 tools — view data, screenshots, design system extraction
Cloud Mode: 101 tools — adds full write access (create, edit, delete) via relay
Local Mode (NPX/Git): 114 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

​Installation Methods & Execution Modes - Complete Comparison

​Understanding the Architecture

​Execution Modes (Where Code Runs)

​Setup Methods (How You Connect)

​Authentication Methods (How You Authenticate)

​🎯 Quick Decision Guide

​⚠️ Critical: Tool Count Differences

​Use NPX Setup (Recommended for Most Users)

​Use Cloud Mode (Web AI Clients)

​Use Local Git (For Contributors)

​Use Remote Mode (Read-Only Exploration)

​Setup Methods Comparison

​Feature Availability Matrix

​Legend

​Architecture Comparison

​Remote Mode Architecture (Read-Only)

​Cloud Mode Architecture (Read/Write via Relay)

​Local Mode Architecture (Full Capabilities)

​Tool Availability by Mode

​Core Tools Available in Both Modes

​Key Differences

​Prerequisites & Setup Time

​Remote (Read-Only)

​Cloud Mode

​NPX

​Local Git

​Authentication Comparison

​Remote SSE - OAuth (Automatic) ⭐ Simplest

​Cloud Mode - PAT + Pairing Code

​NPX + Local Git - Personal Access Token (Manual)

​Figma Desktop Bridge Plugin

​Required for Both Local Mode and Cloud Mode

​Plugin Does NOT Work with Remote Read-Only Mode

​When to Switch Modes

​Switch from Remote (read-only) → Cloud Mode if:

​Switch from Remote (read-only) → NPX/Local Git if:

​Switch from Cloud Mode → NPX/Local Git if:

​Switch from NPX/Local Git → Cloud Mode if:

​Switch from NPX/Local Git → Remote (read-only) if:

​Switch from NPX → Local Git if:

​Switch from Local Git → NPX if:

​Cost Comparison

​Remote / Cloud Mode (Free - Hosted by Project)

​NPX (Free - Self-Hosted)

​Local Git (Free - Self-Hosted)

​Troubleshooting by Mode

​Remote Mode Common Issues

​Cloud Mode Common Issues

​Local Mode Common Issues

​Summary

Installation Methods & Execution Modes - Complete Comparison

Understanding the Architecture

Execution Modes (Where Code Runs)

Setup Methods (How You Connect)

Authentication Methods (How You Authenticate)

🎯 Quick Decision Guide

⚠️ Critical: Tool Count Differences

Use NPX Setup (Recommended for Most Users)

Use Cloud Mode (Web AI Clients)

Use Local Git (For Contributors)

Use Remote Mode (Read-Only Exploration)

Setup Methods Comparison

Feature Availability Matrix

Legend

Architecture Comparison

Remote Mode Architecture (Read-Only)

Cloud Mode Architecture (Read/Write via Relay)

Local Mode Architecture (Full Capabilities)

Tool Availability by Mode

Core Tools Available in Both Modes

Key Differences

Prerequisites & Setup Time

Remote (Read-Only)

Cloud Mode

NPX

Local Git

Authentication Comparison

Remote SSE - OAuth (Automatic) ⭐ Simplest

Cloud Mode - PAT + Pairing Code

NPX + Local Git - Personal Access Token (Manual)

Figma Desktop Bridge Plugin

Required for Both Local Mode and Cloud Mode

Plugin Does NOT Work with Remote Read-Only Mode

When to Switch Modes

Switch from Remote (read-only) → Cloud Mode if:

Switch from Remote (read-only) → NPX/Local Git if:

Switch from Cloud Mode → NPX/Local Git if:

Switch from NPX/Local Git → Cloud Mode if:

Switch from NPX/Local Git → Remote (read-only) if:

Switch from NPX → Local Git if:

Switch from Local Git → NPX if:

Cost Comparison

Remote / Cloud Mode (Free - Hosted by Project)

NPX (Free - Self-Hosted)

Local Git (Free - Self-Hosted)

Troubleshooting by Mode

Remote Mode Common Issues

Cloud Mode Common Issues

Local Mode Common Issues

Summary