figma-mcp-server

A Model Context Protocol (MCP) server for the Figma REST API.
Gives any MCP-compatible AI agent a structured, rate-limited interface to Figma — designed to help agents read design files, extract tokens, and build pixel-perfect UI.

Authentication: Personal Access Token (PAT)
Transport: stdio
Runtime: Node.js ≥ 18 (uses native fetch — zero third-party HTTP dependencies)

Why this MCP?

The official Figma MCP requires the Figma desktop app running with Dev Mode. This server uses the REST API + a Personal Access Token, which means it works headless — in CI/CD, Docker, GitHub Actions, remote agents, or any MCP host without a browser. It also adds figma_build, an agent-optimized read path that collapses Figma's verbose REST JSON into a compact JSX-shaped DSL with design tokens inlined at every use site — the same information density the official Dev Mode MCP provides.

Tools

The server exposes 5 tools covering 25 actions across the Figma REST API.

figma_build (start here)

Agent-optimized read path for turning Figma designs into pixel-perfect UI code. This tool returns compact, token-aware output instead of raw REST JSON.

| Action | Description | |---|---| | get_outline | Compact XML-like structural tree (~80 bytes/node). One element per node with only id, name, position, size, and component references. Instance internals are collapsed by default (matching the official Dev Mode MCP's get_metadata). Use this to navigate a file before fetching details. | | get_context | Agent-ready build kit for a single subtree. Returns: (1) <DevResources> — designer-linked Storybook/GitHub/docs URLs, (2) <Tokens> — every design variable and legacy style referenced, resolved to default-mode values, (3) JSX-shaped DSL body with layout/bg/border/radius/shadow/font collapsed into terse attributes with token names inlined, (4) <Components> — auto-inlined main component layouts with a <Variants> block listing every variant axis and its options, (5) inline 2x PNG screenshot. One call, everything an agent needs. |

figma_file

Read and export content from a specific Figma file.

| Action | Description | |---|---| | get_file | Full document tree. Use depth=2 for a quick overview of pages and frames. | | get_file_meta | Lightweight metadata — name, owner, last modified, branch info. No document tree. | | get_file_versions | Named version history. Get version IDs to pin work to an approved snapshot. | | get_nodes | Fetch specific nodes by ID with their full subtrees. More efficient than get_file when you know which frames to inspect. | | export_nodes | Render nodes as downloadable images (SVG / PNG / JPG / PDF). SVG for icons and vectors; PNG for complex components. | | get_image_fills | Resolve download URLs for raster images embedded as fills. Expires in ~14 days. |

figma_design_system

Browse the reusable design language — components, styles, and design tokens.

| Action | Description | |---|---| | get_file_components | All published components in a file. | | get_component | Single component metadata and thumbnail by library key. | | get_file_component_sets | Component variant groups (e.g. Button with size × state matrix). | | get_component_set | Single component set metadata by library key. | | get_team_components | Paginated team-wide component library. | | get_team_component_sets | Paginated team-wide component set library. | | get_file_styles | All styles in a file, grouped by type: FILL, TEXT, EFFECT, GRID. | | get_style | Single style metadata by library key. | | get_team_styles | Paginated team-wide style library. | | get_local_variables | Design tokens as typed variables with multi-mode support (Light/Dark/etc). Returns a CSS variable preview. Requires Enterprise plan. | | get_published_variables | Published tokens available for cross-file use. Requires Enterprise plan. |

figma_workspace

Navigate the workspace — find projects and files, discover linked code, verify auth.

| Action | Description | |---|---| | get_team_projects | List all projects in a team. First step when you only have a team ID. | | get_project_files | List all files in a project with thumbnails and last-modified timestamps. | | get_dev_resources | Fetch code links attached to design nodes — Storybook, GitHub, docs, etc. | | get_me | Verify the PAT is valid and return the active user profile. |

figma_comments

Read and write threaded comments on a Figma file.

| Action | Description | |---|---| | get_comments | All comments as threaded conversations (root + replies). Designer annotations often contain critical implementation notes. | | post_comment | Post a comment. Pin to a node (node_id), a canvas position (canvas_x/canvas_y), or reply to a thread (comment_id). | | delete_comment | Delete a comment created by the authenticated user. |

Setup

1. Generate a Figma Personal Access Token

1. Open Figma → click your avatar → Settings
2. Scroll to Personal access tokens → Generate new token
3. Select the scopes you need (see Scopes below)
4. Copy the token — it starts with figd_

2. Install

npm install -g @nexus2520/figma-mcp-server

Or use directly without installing via npx — no install step needed.

3. Configure your MCP host

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@nexus2520/figma-mcp-server"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@nexus2520/figma-mcp-server"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
      }
    }
  }
}

VS Code (with MCP extension)

{
  "mcp.servers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@nexus2520/figma-mcp-server"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
      }
    }
  }
}

Note: npx -y downloads and runs the latest published version automatically. If you prefer a pinned version, use "args": ["-y", "@nexus2520/[email protected]"].

Scopes

When generating your PAT, enable the scopes your use case requires:

| Scope | Required for | |---|---| | file_content:read | get_file, get_nodes, get_image_fills, export_nodes | | file_metadata:read | get_file_meta | | file_versions:read | get_file_versions | | file_comments:read | get_comments | | file_comments:write | post_comment, delete_comment | | file_dev_resources:read | get_dev_resources | | file_variables:read | get_local_variables, get_published_variables | | library_content:read | get_file_components, get_file_component_sets, get_file_styles | | team_library_content:read | get_team_components, get_team_component_sets, get_team_styles | | projects:read | get_team_projects, get_project_files |

For a read-only agent that only inspects designs, the minimum required scopes are:
file_content:read, file_metadata:read, library_content:read, projects:read

Rate Limits

The server implements a per-tier token-bucket rate limiter that matches Figma's published limits.
Requests automatically queue — you will never get a 429 error from this server.

| Tier | Limit | Used for | |---|---|---| | Tier 1 | 300 req/min | export_nodes | | Tier 2 | 120 req/min | get_comments, post_comment, delete_comment, get_dev_resources, get_local_variables, get_published_variables | | Tier 3 | 30 req/min | All file, node, component, style, and project reads |

Recommended Agent Workflow

Quick path (2 calls)

For most UI generation tasks, figma_build handles everything:

# Step 1 — Navigate: find the frame you want to build
figma_build → get_outline (file_key, node_id=<page or top frame>)
  → read the compact tree, pick the node id of the section to implement

# Step 2 — Build: get the full context in one call
figma_build → get_context (file_key, node_id=<target frame>)
  → returns:
     • <DevResources> — Storybook/GitHub links (check first!)
     • <Tokens>       — resolved design tokens scoped to the subtree
     • JSX-shaped DSL — layout + fills + typography with token names inlined
     • <Components>   — auto-inlined main component layouts with <Variants>
     • Inline PNG     — 2x screenshot for visual verification

# → Agent now has everything needed for pixel-perfect code generation

Full exploration path (for complex workflows)

When you need to explore across files, extract team-wide tokens, or post comments:

# Orient: find the right file
figma_workspace → get_team_projects (team_id)
figma_workspace → get_project_files (project_id)

# Read designer annotations
figma_comments → get_comments (file_key)

# Team-wide design system
figma_design_system → get_team_components (team_id)
figma_design_system → get_local_variables (file_key)   ← Enterprise
figma_design_system → get_file_styles (file_key)        ← legacy fallback

# Raw node data (when figma_build's DSL isn't enough)
figma_file → get_nodes (file_key, [node_id])
figma_file → export_nodes (file_key, [node_id], format=svg)

How to Find IDs

File key — the segment in a Figma file URL:
figma.com/design/{file_key}/... or figma.com/file/{file_key}/...

Team ID — the segment in a Figma team URL:
figma.com/files/team/{team_id}/...

Node ID — right-click any layer in Figma → Copy link to selection → the URL contains node-id={node_id}.
Node IDs look like 1:23 or I422:8745;1:9.

Development

# Watch mode (recompiles on save)
pnpm run dev

# Build
pnpm run build

# Start (requires FIGMA_ACCESS_TOKEN to be set)
FIGMA_ACCESS_TOKEN=figd_... pnpm start

Project Structure

src/
├── index.ts                     # Server entry point and tool dispatch
├── tools/
│   └── definitions.ts           # All 5 tool schemas (MCP inputSchema)
├── utils/
│   ├── api-client.ts            # Figma API client + token-bucket rate limiter
│   ├── formatters.ts            # Design-aware response formatters (raw REST path)
│   ├── outline-formatter.ts     # Compact XML-like outline for get_outline
│   ├── build-formatter.ts       # JSX-shaped DSL emitter for get_context
│   ├── token-resolver.ts        # Per-file variable + style cache with alias resolution
│   └── tool-response.ts         # Typed MCP result builder
└── handlers/
    ├── build-handlers.ts        # figma_build: get_outline, get_context
    ├── file-handlers.ts         # get_file, get_file_meta, get_file_versions
    ├── node-handlers.ts         # get_nodes
    ├── image-handlers.ts        # export_nodes, get_image_fills
    ├── component-handlers.ts    # get_file_components, get_component, ...
    ├── style-handlers.ts        # get_file_styles, get_style, get_team_styles
    ├── variable-handlers.ts     # get_local_variables, get_published_variables
    ├── comment-handlers.ts      # get_comments, post_comment, delete_comment
    ├── project-handlers.ts      # get_team_projects, get_project_files
    └── dev-resource-handlers.ts # get_dev_resources

License

MIT