figma-mcp-free

Supported Figma links (Important)

• ✅ Supports /file or /design links (e.g., https://www.figma.com/design/<FILE_ID>/...)
• ❌ /slides are not supported by the API (node information cannot be retrieved)
• Node ID format: Figma URLs use ?node-id=1-2, but the API/CLI requires 1:2 (hyphen to colon).

Quick check:

# If you can issue a temporary URL for an image (expires soon), it's OK.
curl -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/images/<FILE_ID>?ids=1:2&format=png"

Quick Start (from clone)

1. In Figma, get a /design (or /file) link and execute Link to selection on the target frame. → Convert the ?node-id=1-2 in the URL to 1:2 and make a note (this is <NODE_ID>)

2. Operation verification (optional)

curl -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/<FILE_ID>/nodes?ids=<NODE_ID>"

→ If JSON is returned, it's OK. Then execute the following commands.

• Star this repo to support the project!
• Clone: git clone https://github.com/superdoccimo/figma-mcp-free.git
• Install: cd figma-mcp-free && pnpm install && pnpm -r build
• Set token: pnpm --filter figma-mcp-free dev -- init
• Find components: pnpm --filter figma-mcp-free dev -- components <FILE_ID> --query Button --limit 5
• Generate (no tokens): pnpm --filter figma-mcp-free dev -- generate <FILE_ID> <NODE_ID> --framework react > out-no-tokens.jsx
• Export tokens: pnpm --filter figma-mcp-free dev -- export-tokens <FILE_ID> > tokens.json
• Generate (with tokens): pnpm --filter figma-mcp-free dev -- generate <FILE_ID> <NODE_ID> --framework react --use-tokens ./tokens.json > out-with-tokens.jsx

Assets / Images Handling (Important)

• Figma view URLs (/slides, /design, /file) are not direct image links.
• You can use temporary URLs from the Images API during development, but they expire quickly.
• For production, use (a) images exported from Figma to /public/images or (b) direct links from your own server/CDN.

Next.js configuration (when using external direct links):

// next.config.js
export default {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'minokamo.tokyo' },
      { protocol: 'https', hostname: 'vibelsd.com' }
      // If using temporary URLs, also add images.figma.com / s3-*.amazonaws.com etc.
    ]
  }
}

Troubleshooting: Only a black frame is displayed

• next/image allowed domain missing → /_next/image?... returns 400
• Temporary URL expired → 403/404
• Path/extension/case mismatch (e.g., expecting /public but file is not there)
• Export mismatch (e.g., using only rounded rectangles and forgetting to replace images)
• Mask/clip related issues → Try use_absolute_bounds=true with the Images API

Demo scripts

• Prerequisite: FIGMA_TOKEN, FILE_ID, and NODE_ID are all required (NODE_ID in 1:2 format).
• ./scripts/demo.sh runs the above end-to-end. Requires env: FIGMA_TOKEN, FILE_ID, NODE_ID.
• Offline fallback: pnpm --filter figma-mcp-free dev -- generate-from-json ./examples/sample-node.json --framework react --use-tokens ./examples/sample-tokens.json

Documentation map

• docs/quickstart.md – English quickstart covering install, token storage, and CLI usage.
• docs/troubleshooting.md – Common pitfalls (token scopes, rate limits) and recovery steps.
• index.md – Working draft for the detailed Japanese walkthrough.
• Campaign article (JP): https://minokamo.tokyo/2025/09/18/9360/
• Upcoming English deep dive: https://vibelsd.com/figma-mcp-free (placeholder)
• Upcoming Spanish deep dive: https://vibelsd.net/figma-mcp-free (placeholder)

Free, open MCP server alternative to Figma Dev Mode.

• Protocol: MCP STDIO
• API: Figma REST (Personal Access Token)
• Language: TypeScript / Node 18+

Getting started and roadmap: see figma_mcp_requirements.md and docs/.

• Campaign article for GitHub users (JP): jp/docs/marketing/github-article.md

• Japanese documentation: jp/README.md

• Setup notes: basic_notes.md

• Suggested commands: suggested_commands.md

• Example env: .env.example (do not commit real tokens)

Why this project exists

• Figma restricts its official MCP server to paid Dev Mode seats even though MCP itself is an open standard; Personal Access Tokens remain read-only.
• figma-mcp-free proves that the read-only API still unlocks practical workflows and challenges enclosure strategies around open technology.

Note: The Figma REST API is fundamentally read-only. Writing operations such as adding, editing, or moving designs cannot be done via REST. If necessary, use the Figma Plugin API (executed within the editor) or browser automation.

Visual comparison

What read-only access still delivers

Note: Figma REST API is primarily read-only. Adding/editing/moving designs cannot be done through REST. For write operations, use the Figma Plugin API (runs inside the editor) or browser automation.

• Extract design tokens -> generate CSS/Tailwind/W3C design token JSON
• Inspect component structure -> output React/Vue/Svelte/HTML code
• Capture layout data -> plan responsive implementation
• Gather color/typography info -> feed themes and design systems
• Inventory assets -> seed an image optimization pipeline

Even if you need write access, there are free-tier detours:

• Figma Plugin: execute figma.createComponent(componentData); inside a plugin to write back
• Browser automation: drive the web UI via Playwright/Puppeteer
• Import workflow: export with figma-mcp-free -> tweak locally -> re-import via SVG or other supported formats

Package capabilities

Architecture overview

Basic usage (client only)

• Set FIGMA_TOKEN in your environment (or wire into the server/CLI later)
• Use FigmaClient to call the API:

import { FigmaClient } from "@figma-mcp-free/figma-client";
const client = new FigmaClient({ token: process.env.FIGMA_TOKEN! });
const file = await client.getFile("<FILE_ID>");
const components = await client.getComponents("<FILE_ID>");
const frames = await client.listFrames("<FILE_ID>");

Run MCP Server (stdio)

• Build packages: pnpm -r build
• Ensure FIGMA_TOKEN is set in environment
• Start server: node packages/mcp-server/dist/index.js

Security: Handling FIGMA_TOKEN

• Save it in .env or local configuration, and do not commit it to Git (refer to .env.example)
• Inject it as an environment variable in CI (-- init --token <FIGMA_TOKEN> is also possible)
• In case of leakage, Revoke and re-issue from Figma's Personal access tokens settings.

CLI token setup

• Save token locally: pnpm --filter figma-mcp-free dev -- init (or -- init --token <FIGMA_TOKEN> for CI)
• Check status: pnpm --filter figma-mcp-free dev -- config get token
• If FIGMA_TOKEN is not present in the environment, the server falls back to the local config (@figma-mcp-free/config).

Security: FIGMA_TOKEN Handling

• Store in .env or local config, never commit to Git (see .env.example)
• For CI: inject via environment variables (-- init --token <FIGMA_TOKEN> is also supported)
• If leaked: go to Figma Personal access tokens -> Revoke -> regenerate

CLI commands

• Generate code: pnpm --filter figma-mcp-free dev -- generate <FILE_ID> <NODE_ID> --framework react
• Export tokens: pnpm --filter figma-mcp-free dev -- export-tokens <FILE_ID>
• List components: pnpm --filter figma-mcp-free dev -- components <FILE_ID> [--query <text>] [--limit <n>] [--json]
  • Optional: --use-tokens ./tokens.json [--var-prefix --] replaces hex colors with CSS variables derived from a W3C design token JSON (e.g., var(--color-page-frame-shape)).
  • With tokens, typography values map to variables when matches exist (font-size, line-height, letter-spacing, font-family, font-weight).
  • Size/spacing tokens map width, height, and padding pixel values to var(--size-...) / var(--spacing-...) when exact matches exist.
  • Shadow tokens map DROP_SHADOW/INNER_SHADOW styles to var(--shadow-...) when the design token index contains a matching shadow.

Exporting design tokens

• Tool: export_tokens (input: { fileId: string })
• Output: W3C Design Tokens (module v1)
  • color: SOLID fills -> color tokens (#RRGGBB / #RRGGBBAA)
  • spacing: padding on each edge (where present) -> spacing/<path>-padding-{top|right|bottom|left}
  • size: width/height (absoluteBoundingBox) -> size/<path>-{width|height}
  • typography: TEXT node fontFamily/fontSize/lineHeight/letterSpacing/fontWeight -> typography/<path>
  • shadow: DROP_SHADOW/INNER_SHADOW -> shadow/<path> (CSS box-shadow syntax, multiple shadows comma-separated)
  • Token keys reflect the node path, e.g. page/frame/shape

List components (normalized)

• Tool: get_components (input: { fileId: string, q?: string, limit?: number })
• Optional filters: { q?: string, limit?: number }
• Output: [{ key, nodeId, name }]

Generate code from a node

• Tool: generate_code (input: { fileId: string, nodeId: string, framework: "react" | "vue" | "svelte" | "html" })
• Minimal implementation inspects node type/size/fills and TEXT characters, building simple nested markup.
• Also maps basic styles when available: border (stroke), border radius, padding, auto-layout (flex direction/gap), and text styles (font size/line-height/weight/align).
• Enhanced mapping: text color from fills, font-family, letter-spacing, flex alignment (justify/align), and absolute positioning (layoutPositioning=ABSOLUTE uses left/top).
• Shadows: convert DROP_SHADOW/INNER_SHADOW to box-shadow (substituting tokens when available).
• Shadow tokens: when a shadow structure matches tokens.shadow, output var(--shadow-...) instead.
• Tokens support: pass { tokens, varPrefix? } to substitute colors/typography/size/spacing/shadow with CSS variables.

MCP example (generate_code) Input (JSON):

{
  "fileId": "<FILE_ID>",
  "nodeId": "<NODE_ID>",
  "framework": "react",
  "tokens": { "$schema": "https://design-tokens.github.io/community-group/format/module.v1.json", "color": { "page/frame/shape": { "value": "#112233" } } },
  "varPrefix": "--"
}

Output: Code string with color replaced by var(--color-page-frame-shape) when matched.

Sample output (React)

export function ButtonPrimary() {
  return (
    <div
      style={{
        backgroundColor: "var(--color-page-frame-shape)",
        borderRadius: "12px",
        padding: "var(--spacing-page-frame-shape-padding-top) var(--spacing-page-frame-shape-padding-right)",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
      }}
    >
      <span
        style={{
          color: "#FFFFFF",
          fontFamily: "'Inter', sans-serif",
          fontSize: "16px",
          fontWeight: 600,
        }}
      >
        Get Started
      </span>
    </div>
  );
}

End-to-end workflow

Community

• File an issue if you hit a missing endpoint or authenticator gap.
• Start a discussion to share workflows or request new framework/token support.
• PRs welcome—see CONTRIBUTING.md for required checks.

Resources

Tutorials & Guides

• 🌐 English: Comprehensive Setup Guide
• 🌍 Español: Guía de Configuración
• 🇯🇵 日本語: 詳細セットアップガイド

Video Tutorials

• 🎥 English: figma-mcp-free Setup Tutorial
• 🎥 日本語: figma-mcp-free セットアップチュートリアル