Figma Native MCP

A local Model Context Protocol server that lets MCP clients inspect and edit the Figma document currently open in the official Figma desktop app.

The primary path uses a development plugin and the Figma Plugin API. It does not call Figma's hosted MCP service and does not consume Figma REST requests for normal document control. Optional REST tools are available behind an explicit opt-in.

[!IMPORTANT] The loopback bridge requires a high-entropy bearer token. Local image files and remote image URLs are denied unless you configure explicit allowlists. Arbitrary plugin JavaScript is disabled by default.

Architecture

MCP client
    │ stdio
    ▼
figma-native-mcp server
    │ token-authenticated loopback HTTP
    ▼
local bridge on 127.0.0.1:3845
    │ authenticated polling and results
    ▼
Figma development plugin
    │ Figma Plugin API
    ▼
currently open Figma document

Optional: figma-native-mcp server ── HTTPS ──► Figma REST API

A stdio server process can own the bridge itself or attach to a foreground/watcher-owned bridge after an authenticated identity check.

Requirements

• Node.js 20 or newer
• Figma desktop on Windows or macOS
• An MCP client that supports stdio servers
• A Figma REST token only if you explicitly enable REST tools

The Node server is cross-platform. This project does not claim a supported desktop-plugin workflow for Linux because Figma does not provide an official Linux desktop app.

Install

git clone https://github.com/tomasmarekk/native-figma-mcp.git
cd native-figma-mcp
npm ci

Generate a bridge token:

npm run --silent generate-token

PowerShell:

$env:FIGMA_MCP_BRIDGE_TOKEN = (npm run --silent generate-token).Trim()

POSIX shells:

export FIGMA_MCP_BRIDGE_TOKEN="$(npm run --silent generate-token)"

Keep this token secret. It is separate from any Figma API token. The exact same value must be supplied to every MCP server process, the Figma plugin, and the optional Windows watcher.

Figma development plugin

1. Open the Figma desktop app.
2. Choose Plugins → Development → Import plugin from manifest.
3. Select <absolute-path-to-repo>/plugin/manifest.json.
4. Run Figma Native MCP Bridge in the document you want to control.
5. Paste the generated bridge token into the plugin and click Save & connect.
6. Keep the plugin running while MCP tools need access to that document.

The plugin stores its URL and token using figma.clientStorage. The saved token is never displayed back in the UI. By default it connects only to http://127.0.0.1:3845; localhost is also accepted.

Configure an MCP client

Generic stdio configuration:

{
  "mcpServers": {
    "figma-native": {
      "command": "node",
      "args": ["/absolute/path/to/native-figma-mcp/server.mjs"],
      "env": {
        "FIGMA_MCP_BRIDGE_TOKEN": "replace-with-generated-token"
      }
    }
  }
}

Environment expansion is client-specific. Do not assume ${VAR} is expanded in generic MCP JSON.

Claude Code

POSIX:

claude mcp add \
  --scope user \
  --env "FIGMA_MCP_BRIDGE_TOKEN=$FIGMA_MCP_BRIDGE_TOKEN" \
  --transport stdio \
  figma-native \
  -- node "/absolute/path/to/native-figma-mcp/server.mjs"

PowerShell:

claude mcp add `
  --scope user `
  --env "FIGMA_MCP_BRIDGE_TOKEN=$env:FIGMA_MCP_BRIDGE_TOKEN" `
  --transport stdio `
  figma-native `
  -- node "C:\path\to\native-figma-mcp\server.mjs"

A shared Claude Code .mcp.json can forward the environment variable without committing its value:

{
  "mcpServers": {
    "figma-native": {
      "command": "node",
      "args": ["/absolute/path/to/native-figma-mcp/server.mjs"],
      "env": {
        "FIGMA_MCP_BRIDGE_TOKEN": "${FIGMA_MCP_BRIDGE_TOKEN}"
      }
    }
  }
}

Codex

Prefer forwarding an already-set environment variable from ~/.codex/config.toml:

[mcp_servers.figma-native]
command = "node"
args = ["/absolute/path/to/native-figma-mcp/server.mjs"]
env_vars = [
  "FIGMA_MCP_BRIDGE_TOKEN",
  "FIGMA_MCP_ASSET_ROOTS",
  "FIGMA_MCP_ASSET_HOSTS"
]

The CLI equivalent is:

codex mcp add figma-native \
  --env "FIGMA_MCP_BRIDGE_TOKEN=$FIGMA_MCP_BRIDGE_TOKEN" \
  -- node "/absolute/path/to/native-figma-mcp/server.mjs"

codex mcp add --env KEY=value persists the literal value; env_vars is preferable for forwarding an existing secret.

Claude Desktop

Configuration locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Use absolute paths for both Node and server.mjs, then fully restart Claude Desktop. Claude Desktop stores the literal token in its configuration.

Foreground bridge

The supported cross-platform lifecycle is a foreground process:

npm run bridge

Set FIGMA_MCP_BRIDGE_TOKEN first. The bridge binds to loopback only. GET /health is intentionally unauthenticated and reveals only service identity and version; authenticated GET /status proves the token matches and returns connection details.

Optional Windows watcher

Windows users can install an optional current-user Scheduled Task that starts the bridge while Figma.exe is running:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows-watcher.ps1

Rotate the stored token:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows-watcher.ps1 -PromptForToken

Uninstall and remove encrypted watcher data/logs:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-windows-watcher.ps1

Add -KeepData to retain them. The installer stores the token using current-user Windows DPAPI under %LOCALAPPDATA%\figma-native-mcp; it never places the token in Scheduled Task arguments or logs. The watcher does not enable plugin eval and stops only a bridge child it started.

On macOS and Linux, use npm run bridge or wrap it in your own user-level launchd/systemd configuration.

Tool groups

Area	Default	Authentication	Limits
Plugin bridge tools	Enabled	Bridge bearer token	Local Figma Plugin API
URL parsing and status	Enabled	Detailed bridge status requires token	Local only
Arbitrary plugin eval	Disabled	Token plus explicit eval opt-in	Trusted code in plugin context
Figma REST tools	Disabled	Figma PAT/OAuth plus REST opt-in	Figma scopes, plans and rate limits

Core plugin tools cover document/page metadata, selection, bounded trees/nodes, CSS inspection, renaming, frame/text creation, text updates, image placement, and live verification. REST tools cover account identity, files/nodes, image exports/fills, comments, versions, teams/projects, variables, and dev resources.

Environment variables

Variable	Default	Purpose
FIGMA_MCP_BRIDGE_TOKEN	required	Shared bridge bearer token, minimum 32 characters
FIGMA_MCP_BRIDGE_HOST	127.0.0.1	Loopback host; only 127.0.0.1, localhost, or ::1
FIGMA_MCP_BRIDGE_PORT	3845	Bridge port; the development manifest permits 3845
FIGMA_MCP_BRIDGE_ONLY	0	Run HTTP bridge without MCP stdio
FIGMA_MCP_ENABLE_PLUGIN_EVAL	0	Enable arbitrary plugin-context JavaScript
FIGMA_MCP_ENABLE_REST	0	Expose optional Figma REST tools
FIGMA_MCP_ASSET_ROOTS	empty	Allowed local asset roots, separated by the OS path delimiter
FIGMA_MCP_ASSET_HOSTS	empty	Comma-separated exact HTTPS hostnames for remote images
FIGMA_MCP_MAX_ASSET_BYTES	10485760	Maximum image size
FIGMA_MCP_MAX_REST_RESPONSE_BYTES	26214400	Maximum buffered Figma REST response
FIGMA_MCP_TIMEOUT_MS	30000	REST and asset timeout
FIGMA_MCP_PLUGIN_TIMEOUT_MS	30000	Plugin command timeout
FIGMA_MCP_PLUGIN_CLIENT_STALE_MS	60000	Plugin client staleness threshold
FIGMA_ACCESS_TOKEN, FIGMA_PERSONAL_ACCESS_TOKEN, FIGMA_TOKEN	empty	Figma personal-token aliases
FIGMA_OAUTH_TOKEN	empty	Figma OAuth bearer token
FIGMA_API_BASE_URL	https://api.figma.com	Advanced/testing REST base URL
FIGMA_MCP_WATCH_PROCESS_NAMES	Figma.exe	Windows watcher process list
FIGMA_MCP_WATCH_POLL_MS	2000	Watcher poll interval
FIGMA_MCP_WATCH_INACTIVE_GRACE_MS	4000	Delay before owned bridge shutdown

Asset access restrictions

Local paths are denied until FIGMA_MCP_ASSET_ROOTS is configured. Remote downloads are denied until FIGMA_MCP_ASSET_HOSTS is configured.

PowerShell:

$env:FIGMA_MCP_ASSET_ROOTS = "C:\design-assets;D:\shared-assets"
$env:FIGMA_MCP_ASSET_HOSTS = "images.example.com,cdn.example.com"

POSIX:

export FIGMA_MCP_ASSET_ROOTS="/srv/design-assets:$HOME/Pictures"
export FIGMA_MCP_ASSET_HOSTS="images.example.com,cdn.example.com"

Local paths are canonicalized and must remain inside an allowed root after resolving symlinks. Remote URLs must use HTTPS, match an exact allowlisted hostname, resolve only to public addresses, and remain allowlisted after every redirect. Image signatures are validated and downloads are streamed with a hard byte cap.

Plugin eval warning

FIGMA_MCP_ENABLE_PLUGIN_EVAL=1 lets authenticated MCP callers execute arbitrary JavaScript with the permissions of the development plugin. That code can read or change the current Figma document. Keep eval off unless every connected MCP client and prompt is trusted. The Windows watcher never enables it automatically.

Testing

npm run check
npm test
npm run smoke

With the updated development plugin open and configured in a Figma document:

npm run live:verify

REST verification is optional:

FIGMA_MCP_ENABLE_REST=1 \
FIGMA_VERIFY_REQUIRE_REST=1 \
FIGMA_TEST_FILE_KEY="SYNTHETIC_FILE_KEY" \
npm run live:verify

Troubleshooting

• 401/403: the MCP server, plugin, or watcher is using a different bridge token.
• Port occupied: another service or incompatible bridge owns port 3845. Stop it or use a matching custom port and development manifest.
• Plugin disconnected: keep the development plugin running in the target document; it reconnects after bridge restarts.
• Image denied: configure the correct local root or exact HTTPS hostname.
• Claude Desktop cannot start Node: use absolute executable and script paths and restart the app.
• Watcher logs: inspect %LOCALAPPDATA%\figma-native-mcp\logs\figma-bridge-watch.log; tokens and document metadata are not logged.

Limitations

• The development plugin must remain running in the target document.
• Plugin operations depend on Figma Plugin API capabilities and permissions.
• The committed manifest permits port 3845; custom ports require updating the imported development manifest.
• Multiple open plugin clients may require an explicit clientId when target selection matters.
• REST tools remain subject to Figma token scopes, product plans, rate limits and API behavior.
• Loopback plus a token does not protect against a compromised local account or administrator.
• There is no claimed official Linux desktop Figma workflow.

Contributing

Issues and pull requests are welcome. Keep security reports private as described in SECURITY.md. Run npm run check and npm test before opening a pull request.

License

MIT © 2026 Tomas Marek.

Figma is a trademark of Figma, Inc. This project is independent and unofficial. It is not affiliated with, sponsored by, or endorsed by Figma, Inc. Other product and company names are trademarks of their respective owners.