figma-query

Token-efficient Figma MCP server with image export, query DSL, and design token support.

Installation

npm

npm install -g @standardbeagle/figma-query

Or use with npx:

npx @standardbeagle/figma-query

Python (uvx/pipx)

# Using uvx (recommended)
uvx figma-query

# Using pipx
pipx install figma-query

# Using pip
pip install figma-query

Configuration

Environment Variables

• FIGMA_ACCESS_TOKEN - Your Figma personal access token (required)
• FIGMA_EXPORT_DIR - Directory for file exports (default: ./figma-export)

Claude Desktop / MCP Client

Add to your MCP configuration:

{
  "mcpServers": {
    "figma-query": {
      "command": "npx",
      "args": ["@standardbeagle/figma-query"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "figma-query": {
      "command": "figma-query",
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Using uvx (Python):

{
  "mcpServers": {
    "figma-query": {
      "command": "uvx",
      "args": ["figma-query"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Tools

Export Tools

Tool	Description
sync_file	Export entire file to nested folders (includes assets by default)
export_assets	Export images/icons for specific nodes
export_tokens	Export design tokens to CSS/JSON/Tailwind
download_image	Download images by ref ID or render nodes as images

Query Tools

Tool	Description
query	Query nodes with JSON DSL and data shaping
search	Full-text search across names, text, properties
get_tree	Get file structure as ASCII tree with node IDs
list_components	List all components with usage stats
list_styles	List all styles (color, text, effect, grid)

Detail Tools

Tool	Description
get_node	Get full details for a specific node
get_css	Extract CSS properties for node(s)
get_tokens	Get design token references and resolved values

Other Tools

Tool	Description
wireframe	Generate annotated wireframe with node IDs
diff	Compare exports or file versions
info	Help and status

Projections

Use projections in the select array to get specific property groups:

Projection	Properties
@structure	id, name, type, visible
@bounds	x, y, width, height
@css	fills, strokes, effects, cornerRadius, opacity
@layout	layoutMode, padding, itemSpacing, constraints
@typography	fontFamily, fontSize, fontWeight, lineHeight
@tokens	boundVariables
@images	imageRefs (from fills/strokes/backgrounds), exportSettings
@all	All properties

Examples

Query all buttons

{
  "file_key": "abc123",
  "q": {
    "from": ["COMPONENT"],
    "where": { "name": { "$match": "Button*" } },
    "select": ["@structure", "@css"]
  }
}

Get images from a node

{
  "file_key": "abc123",
  "q": {
    "from": ["FRAME"],
    "select": ["@structure", "@images"]
  }
}

Download image fills

{
  "file_key": "abc123",
  "image_refs": ["ref123", "ref456"],
  "output_dir": "./images"
}

License

MIT