figma-mcp-free

Quota-aware, read-only Figma tooling for MCP clients, terminals, and code-generation workflows.

figma-mcp-free provides two explicit read paths:

1. a rate-aware Figma REST backend for files, nodes, components, tokens, and headless automation;
2. an authenticated, loopback-only Figma development-plugin bridge for a user-approved capture of the current selection without a PAT or REST request.

Both paths feed the same bounded inspection and React, Vue, Svelte, or HTML starter-code generation pipeline. Neither path writes to Figma.

Capability Matrix

This project does not replace Figma Dev Mode or the official Figma MCP server. It provides a transparent open-source read pipeline with explicit limits.

Why This Project Exists

Figma REST API limits depend on endpoint, seat, plan, and resource location. This project treats network requests as a budgeted resource:

• node IDs are de-duplicated and batched;
• identical in-flight reads are joined;
• successful responses use a bounded, short-lived memory cache;
• a hard per-client request budget is available;
• short-lived failures retry within configured ceilings;
• long-lived or plan-related 429 responses fail fast with structured metadata;
• response size can be bounded by depth or transformed into compact selection context;
• the local Plugin bridge can capture the current selection without spending REST quota.

See Figma’s official REST API rate-limit documentation for current limits. Figma may change them.

Features

• MCP STDIO server with stable, read-only tools.
• CLI for REST inspection, batch node reads, component search, token export, and code generation.
• Local bridge CLI for serving, listing, inspecting, generating from, and clearing the captured selection.
• Figma development plugin using JSON_REST_V1 after an explicit Capture & Send action.
• Full /file and /design URL parsing with numeric node-id=1-2 normalization to 1:2.
• Bounded implementation context through inspect_selection and inspect_current_selection.
• W3C-style design tokens for colors, sizes, spacing, typography, and shadows.
• Retry, timeout, cache, rate-limit metadata, request-budget, and cache-control APIs.
• Protected local PAT storage with atomic replacement and owner-only POSIX permissions.
• Automated, read-only fork-network auditing and contribution provenance.
• CI across Node.js 18, 20, and 22 with build, typecheck, tests, smoke tests, secret checks, fork checks, Plugin boundary checks, and package-content checks.

Try It Without Figma or a Token

git clone https://github.com/superdoccimo/figma-mcp-free.git
cd figma-mcp-free
pnpm install --frozen-lockfile
pnpm -r build
pnpm --filter figma-mcp-free dev -- \
  generate-from-json ./examples/sample-node.json \
  --framework react \
  --use-tokens ./examples/sample-tokens.json

The offline command does not contact Figma.

REST Quickstart

1. Select a frame or component in Figma and copy a link to the selection.
2. Use a /design or /file URL. /slides is not supported by this REST workflow.
3. Store a PAT locally or provide FIGMA_TOKEN in the environment.

pnpm --filter figma-mcp-free dev -- init

4. Diagnose the environment and selected node.

FIGMA_URL="https://www.figma.com/design//Example?node-id=1-2"
pnpm --filter figma-mcp-free dev -- doctor "$FIGMA_URL"

5. Inspect, batch-read, or generate.

pnpm --filter figma-mcp-free dev -- inspect-selection "$FIGMA_URL" --depth 2 --max-children 20

pnpm --filter figma-mcp-free dev -- nodes "$FIGMA_URL" 1:2 3:4 5:6 --depth 2

pnpm --filter figma-mcp-free dev -- generate "$FIGMA_URL" --framework react > Card.tsx

pnpm --filter figma-mcp-free dev -- generate-many "$FIGMA_URL" 1:2 3:4 5:6 \
  --framework react \
  --out-dir ./generated

Local Plugin Bridge Quickstart

The bridge is a development workflow, not a published Figma Community plugin.

1. Start the local server

pnpm --filter figma-mcp-free bridge -- serve

It prints a loopback URL, random session ID, and sensitive pairing token.

2. Generate a development manifest

Create a development plugin once in Figma Desktop, copy its numeric ID, then run:

node plugins/local-bridge/create-manifest.mjs  [BRIDGE_PORT]

Import plugins/local-bridge/manifest.json as a development plugin.

3. Capture deliberately

1. Paste the loopback URL and pairing token into the plugin UI.
2. Select one or more nodes.
3. Press Capture & Send.

Nothing is sent when the selection merely changes. The plugin contains no Figma document-write APIs.

4. Use the snapshot

export FIGMA_PLUGIN_BRIDGE_URL=http://127.0.0.1:3845
export FIGMA_PLUGIN_BRIDGE_TOKEN=''

pnpm --filter figma-mcp-free bridge -- status
pnpm --filter figma-mcp-free bridge -- current
pnpm --filter figma-mcp-free bridge -- inspect --index 0 --depth 2 --max-children 20
pnpm --filter figma-mcp-free bridge -- generate --index 0 --framework react
pnpm --filter figma-mcp-free bridge -- clear

See Local Figma Plugin Bridge for setup, limits, threat model, and MCP configuration.

CLI Commands

REST and offline CLI

Network-reading commands accept --refresh to bypass the process-local cache.

Local bridge CLI

Prefer FIGMA_PLUGIN_BRIDGE_TOKEN over --token so the token does not enter shell history.

MCP Server

Build and start the STDIO server:

pnpm -r build
node packages/mcp-server/dist/index.js

Example client configurations are in:

• examples/codex-config/mcp.json
• examples/cursor-config/mcp.json

REST MCP tools

Local Plugin MCP tools

The bridge URL and token are process environment variables. They never appear in model-visible MCP tool schemas.

Environment tuning

Architecture

REST path
Figma REST API -> rate-aware FigmaClient -> MCP / CLI -> inspect / tokens / generate

Local path
Figma selection -> explicit development-plugin capture -> authenticated loopback bridge
                -> MCP / bridge CLI -> inspect / generate

The paths share output consumers, not credentials. There is no silent fallback from REST to the Plugin bridge.

Forks Are First-Class

The repository includes a read-only fork intelligence workflow. It detects its canonical upstream from GitHub metadata, compares forks, and highlights unique downstream commits without pushing, merging, opening issues, or modifying forks.

GITHUB_TOKEN=... node tools/audit-forks.mjs --repo owner/repository

See Forks, downstreams, and contribution flow. Operational code is checked for owner-specific paths so a renamed fork can build and run normally.

Security

REST controls:

• Prefer FIGMA_TOKEN for ephemeral sessions and CI secrets.
• Local config writes are atomic.
• On POSIX systems, the config directory is restricted to 0700 and the token file to 0600 where supported.
• Token values are never printed by init, doctor, or config get token.
• The REST cache is bounded, memory-only, and disappears when the process exits.

Local bridge controls:

• loopback-only bind and remote-address validation;
• loopback Host-header validation against DNS rebinding;
• high-entropy bearer token with timing-safe comparison;
• no non-loopback override;
• redirect refusal;
• one bounded, memory-only snapshot;
• request body, selection, node, depth, header, and timeout limits;
• no token persistence in the plugin;
• static checks for Figma write APIs.

Figma’s plugin Fetch API requires wildcard CORS for reachable APIs, so the token and local transport controls are the authorization boundary. Never commit tokens, private file IDs, raw private API responses, captured snapshots, or generated manifests.

Sensitive reports should follow SECURITY.md.

Current Boundaries

• Neither backend can create, edit, move, delete, or publish Figma objects.
• The local bridge is a development plugin and still requires a real Figma Desktop smoke test before release.
• REST and Plugin APIs have different capabilities and limits.
• Code generation is a starter implementation, not a pixel-perfect compiler guarantee.
• /slides links are not supported by the REST pipeline.
• Images API URLs are temporary and should not be committed as durable assets.
• Packages are prepared and checked for distribution but are not published from this repository yet. Use a source checkout.

Project Structure

Further reading:

• Documentation index
• Local Plugin bridge
• Architecture
• REST quickstart
• Troubleshooting
• Fork support
• Roadmap
• Japanese guide
• Changelog

Contributing

pnpm install --frozen-lockfile
pnpm run check

See CONTRIBUTING.md. Fork-originated fixes should include source commit and author provenance so useful downstream work does not disappear into branches.