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

Open Figma → click your avatar → Settings
Scroll to Personal access tokens → Generate new token
Select the scopes you need (see Scopes below)
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/figma-mcp-server@1.0.0"].

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

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

figma-mcp-server

Why this MCP?

Tools

`figma_build` (start here)

`figma_file`

`figma_design_system`

`figma_workspace`

`figma_comments`

Setup

1. Generate a Figma Personal Access Token

2. Install

3. Configure your MCP host

Claude Desktop

Cursor

VS Code (with MCP extension)

Scopes

Rate Limits

Recommended Agent Workflow

Quick path (2 calls)

Full exploration path (for complex workflows)

How to Find IDs

Development

Project Structure

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

figma-mcp-server

Why this MCP?

Tools

figma_build (start here)

figma_file

figma_design_system

figma_workspace

figma_comments

Setup

1. Generate a Figma Personal Access Token

2. Install

3. Configure your MCP host

Claude Desktop

Cursor

VS Code (with MCP extension)

Scopes

Rate Limits

Recommended Agent Workflow

Quick path (2 calls)

Full exploration path (for complex workflows)

How to Find IDs

Development

Project Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`figma_build` (start here)

`figma_file`

`figma_design_system`

`figma_workspace`

`figma_comments`