# Figma — how to use (mcp.ai)

A collaborative interface design tool.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_figma?ms=1781542020000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `figma_add_a_comment_to_a_file`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/figma`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/figma/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/figma/add/a/comment/to/a/file` — Posts a new comment to a figma file or branch, optionally replying to an existing root comment (replies cannot be nested); `region height` and `region width` in `client meta` must be positive if defin
  - body: { message: string, file_key: string, comment_id?: string, client_meta?: object }
- `POST https://api.mcp.ai/api/figma/add/a/reaction/to/a/comment` — Posts a specified emoji reaction to an existing comment in a figma file or branch, requiring valid file key and comment id.
  - body: { emoji: string, file_key: string, comment_id: string }
- `POST https://api.mcp.ai/api/figma/create/a/webhook` — Creates a figma webhook for a `team id` to send post notifications for an `event type` to a publicly accessible https `endpoint`; an initial ping is sent unless `status` is `paused`.
  - body: { status?: string, team_id: string, endpoint: string, passcode: string, event_type: string, description?: string }
- `POST https://api.mcp.ai/api/figma/create/dev/resources` — Creates and attaches multiple uniquely-urled development resources to specified figma nodes, up to 10 per node.
  - body: { dev_resources: object[] }
- `POST https://api.mcp.ai/api/figma/create/modify/delete/variables` — Manages variables, collections, modes, and their values in a figma file via batch create/update/delete operations; use temporary ids to link new related items in one request and ensure `variablemodeva
  - body: { file_key: string, variables?: object[], variableModes?: object[], variableModeValues?: object[], variableCollections?: object[] }
- `POST https://api.mcp.ai/api/figma/delete/a/comment` — Deletes a specific comment from a figma file or branch, provided the authenticated user is the original author of the comment.
  - body: { file_key: string, comment_id: string }
- `POST https://api.mcp.ai/api/figma/delete/a/reaction` — Deletes a specific emoji reaction from a comment in a figma file; the user must have originally created the reaction.
  - body: { emoji: string, file_key: string, comment_id: string }
- `POST https://api.mcp.ai/api/figma/delete/a/webhook` — Permanently deletes an existing webhook, identified by its unique `webhook id`; this operation is irreversible.
  - body: { webhook_id: string }
- `POST https://api.mcp.ai/api/figma/delete/dev/resource` — Deletes a development resource (used to link figma design elements to external developer information like code or tasks) from a specified figma file.
  - body: { file_key: string, dev_resource_id: string }
- `POST https://api.mcp.ai/api/figma/design/tokens/to/tailwind` — Convert design tokens to tailwind css configuration. takes the output from extractdesigntokens and generates: - tailwind.config.ts/js with theme extensions - optional globals.css with font imports not
  - body: { prefix?: string, tokens: object, config_format?: string, include_font_imports?: boolean }
- `POST https://api.mcp.ai/api/figma/detect/background` — Detect background layers for selected nodes. uses geometric analysis, z-index ordering, and visual properties to identify potential background layers.
  - body: { file_key: string, search_depth?: integer, target_node_ids: string[] }
- `POST https://api.mcp.ai/api/figma/discover/figma/resources` — 🔍 smart figma resource discovery - never guess ids again! 🎯 easiest method: just paste any figma url to get all ids: • file urls: https://www.figma.com/file/abc123/design → get file key • design url
  - body: { team_id?: string, file_key?: string, figma_url?: string, max_depth?: integer, project_id?: string }
- `POST https://api.mcp.ai/api/figma/download/figma/images` — Download images from figma file nodes. renders specified nodes as images and downloads them using mercury's filedownloadable infrastructure. supports png, svg, jpg, and pdf formats.
  - body: { scale?: number, images: object[], file_key: string, svg_include_id?: boolean, svg_outline_text?: boolean, svg_simplify_stroke?: boolean }
- `POST https://api.mcp.ai/api/figma/extract/design/tokens` — Extract design tokens from figma files. combines styles, variables, and extracted values to create a comprehensive design token system.
  - body: { file_key: string, include_variables?: boolean, extract_from_nodes?: boolean, include_local_styles?: boolean }
- `POST https://api.mcp.ai/api/figma/extract/prototype/interactions` — Extract prototype interactions and animations from figma files. analyzes the prototype data to extract: - user interactions (clicks, hovers, etc.) - transition animations - component variant states - 
  - body: { file_key: string, analyze_components?: boolean, include_animations?: boolean }
- `POST https://api.mcp.ai/api/figma/get/a/webhook` — Retrieves detailed information about a specific webhook by its id, provided the webhook exists and is accessible to the user.
  - body: { webhook_id: string }
- `POST https://api.mcp.ai/api/figma/get/activity/logs` — Retrieves activity log events from figma, allowing filtering by event types, time range, and pagination.
  - body: { limit?: integer, order?: string, events?: string, end_time?: integer, start_time?: integer }
- `POST https://api.mcp.ai/api/figma/get/comments/in/a/file` — Retrieves all comments from an existing figma file, identified by a valid `file key`, returning details like content, author, position, and reactions, with an option for markdown formatted content.
  - body: { as_md?: boolean, file_key: string }
- `POST https://api.mcp.ai/api/figma/get/component` — Get component data with automatic simplification. returns clean, ai-friendly component structure.
  - body: { node_id: string, file_key: string, simplify?: boolean }
- `POST https://api.mcp.ai/api/figma/get/component/set` — Retrieves detailed metadata for a specific published figma component set using its unique `key`.
  - body: { key: string }
- `POST https://api.mcp.ai/api/figma/get/current/user` — Retrieves detailed information for the currently authenticated figma user.
- `POST https://api.mcp.ai/api/figma/get/dev/resources` — Retrieves development resources (e.g., jira/github links) for a figma main file, optionally filtering by specific node ids.
  - body: { file_key: string, node_ids?: string }
- `POST https://api.mcp.ai/api/figma/get/file/component/sets` — Retrieves all published component sets from the specified figma main file (file key must not be for a branch).
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/file/components` — Retrieves published components from a figma file, which must be a main file (not a branch) acting as a library.
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/file/json` — Get figma file data with automatic simplification. this enhanced version automatically transforms verbose figma json into clean, ai-friendly format with: - css-like property names - deduplicated varia
  - body: { ids?: string, depth?: integer, version?: string, file_key: string, geometry?: string, simplify?: boolean, branch_data?: boolean, include_raw?: boolean, plugin_data?: string }
- `POST https://api.mcp.ai/api/figma/get/file/styles` — Retrieves a list of published styles (like colors, text attributes, effects, and layout grids) from a specified main figma file (not a branch).
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/files/in/a/project` — Fetches a list of files in a figma project, optionally including branch metadata.
  - body: { project_id: string, branch_data?: boolean }
- `POST https://api.mcp.ai/api/figma/get/image/fills` — Retrieves temporary (14-day expiry) download urls for all image fills in a figma file; requires `imageref` from `paint` objects to map urls.
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/component/action/data` — Retrieves component insertion and detachment analytics for a specified figma library, groupable by 'component' or 'team' and filterable by a date range (yyyy-mm-dd).
  - body: { cursor?: string, end_date?: string, file_key: string, group_by: string, start_date?: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/component/usage/data` — Retrieves component usage analytics for a specified figma library file (identified by `file key`), with data groupable by 'component' or 'file'.
  - body: { cursor?: string, file_key: string, group_by: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/style/action/data` — Retrieves style usage analytics (insertions, detachments) for a figma library, grouped by 'style' or 'team'; if providing a date range, ensure end date is not before start date.
  - body: { cursor?: string, end_date?: string, file_key: string, group_by: string, start_date?: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/style/usage/data` — Retrieves style usage analytics for a figma library (specified by a valid `file key`), allowing data to be grouped by 'file' or 'style'.
  - body: { cursor?: string, file_key: string, group_by: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/variable/action/data` — Retrieves weekly, paginated analytics data on variable insertions and detachments for a specified figma library (identified by `file key`), groupable by 'variable' or 'team', and filterable by an opti
  - body: { cursor?: string, end_date?: string, file_key: string, group_by: string, start_date?: string }
- `POST https://api.mcp.ai/api/figma/get/library/analytics/variable/usage/data` — Retrieves paginated analytics data on variable usage from a specified figma library, grouped by 'file' or 'variable', for libraries with enabled analytics.
  - body: { cursor?: string, file_key: string, group_by: string }
- `POST https://api.mcp.ai/api/figma/get/local/variables` — Retrieves all local/remote variables for a figma file/branch; crucial for obtaining mode-specific values which `/v1/files/{file key}/variables/published` omits.
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/payments` — Retrieves a user's payment information for a figma plugin, widget, or community file; the authenticated identity must own the resource.
  - body: { user_id?: integer, plugin_id?: integer, widget_id?: integer, community_file_id?: integer, plugin_payment_token?: string }
- `POST https://api.mcp.ai/api/figma/get/projects/in/a/team` — Retrieves projects within a specified figma team that are visible to the authenticated user.
  - body: { team_id: string }
- `POST https://api.mcp.ai/api/figma/get/published/variables` — Retrieves variables published from a specified figma file; this api is available only to full members of enterprise organizations.
  - body: { file_key: string }
- `POST https://api.mcp.ai/api/figma/get/reactions/for/a/comment` — Retrieves reactions for a specific comment in a figma file.
  - body: { cursor?: string, file_key: string, comment_id: string }
- `POST https://api.mcp.ai/api/figma/get/style` — Retrieves detailed metadata for a specific style in figma using its unique style key.
  - body: { key: string }
- `POST https://api.mcp.ai/api/figma/get/team/component/sets` — Retrieves a paginated list of published component sets (collections of reusable ui elements) from a specified figma team's library.
  - body: { after?: integer, before?: integer, team_id: string, page_size?: integer }
- `POST https://api.mcp.ai/api/figma/get/team/components` — Retrieves components published in a specific figma team's library; the team must have published components, otherwise an empty list is returned.
  - body: { after?: integer, before?: integer, team_id: string, page_size?: integer }
- `POST https://api.mcp.ai/api/figma/get/team/styles` — Retrieves a paginated list of published styles, such as colors or text attributes, from a specified figma team's library.
  - body: { after?: integer, before?: integer, team_id: string, page_size?: integer }
- `POST https://api.mcp.ai/api/figma/get/team/webhooks` — Retrieves all webhooks registered for a specified figma team.
  - body: { team_id: string }
- `POST https://api.mcp.ai/api/figma/get/versions/of/a/file` — Retrieves the version history for a figma file or branch, as specified by its `file key`.
  - body: { after?: integer, before?: integer, file_key: string, page_size?: integer }
- `POST https://api.mcp.ai/api/figma/get/webhook/requests` — Retrieves a history of webhook requests for a specific figma webhook subscription; data is available for requests sent within the last seven days.
  - body: { webhook_id: string }
- `POST https://api.mcp.ai/api/figma/render/images/of/file/nodes` — Renders specified nodes from a figma file as images (jpg, pdf, png, svg), returning a map of node ids to image urls (or `null` for failed nodes); images expire after 30 days and are capped at 32 megap
  - body: { ids: string, scale?: integer, format?: string, version?: string, file_key: string, contents_only?: boolean, svg_include_id?: boolean, svg_outline_text?: boolean, svg_include_node_id?: boolean, svg_simplify_stroke?: boolean, use_absolute_bounds?: boolean }
- `POST https://api.mcp.ai/api/figma/update/a/webhook` — Updates an existing figma webhook, identified by `webhook id`, allowing modification of its event type, endpoint, passcode, status, or description.
  - body: { status?: string, endpoint: string, passcode: string, event_type: string, webhook_id: string, description?: string }
- `POST https://api.mcp.ai/api/figma/update/dev/resources` — Updates the name and/or url of one or more existing figma dev resources, each identified by its unique `id`.
  - body: { dev_resources: object[] }

## More
- Page: https://mcp.ai/figma
- Agent spec (llms.txt): https://mcp.ai/figma/llms.txt
- Postman collection: https://mcp.ai/figma/postman.json