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)

Tools

The server exposes 4 tools covering all 22 actions across the Figma REST API.

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

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

# Step 2 — Understand structure: get top-level frames
figma_file → get_file (file_key, depth=2)

# Step 3 — Deep-dive: get the specific screen to implement
figma_file → get_nodes (file_key, [frame_node_id])

# Step 4 — Visual reference: see what it should look like
figma_file → export_nodes (file_key, [frame_node_id], format=png, scale=2)

# Step 5 — Design tokens: extract colors, spacing, typography
figma_design_system → get_local_variables (file_key)   ← preferred (modern)
figma_design_system → get_file_styles (file_key)        ← fallback (legacy)

# Step 6 — Components: understand reusable parts
figma_design_system → get_file_components (file_key)
figma_design_system → get_file_component_sets (file_key)

# Step 7 — Check for existing code implementations
figma_workspace → get_dev_resources (file_key, node_id)

# Step 8 — Read designer annotations
figma_comments → get_comments (file_key)

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

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 4 tool schemas (MCP inputSchema)
├── utils/
│   ├── api-client.ts           # Figma API client + token-bucket rate limiter
│   ├── formatters.ts           # Design-aware response formatters
│   └── tool-response.ts        # Typed MCP result builder
└── handlers/
    ├── 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