Skip to content
Weavz
Menu

Read selected Figma design context

Map a Figma file, expand selected nodes, and read layout and component references without loading a whole design into your agent.

Start with a file outline, choose the frames that matter, then request their design details. This keeps your agent focused on the design you selected. Rendered images and image-fill URLs are separate actions.

Before you start

Add Figma and connect an account with access to the file. These two read actions use the connection's file_content:read permission. File access still depends on your Figma account and the file's sharing settings.

In For your AI, open Apps, choose Figma and connect your account. Follow AI clients to connect your client. In For your product, create a Figma auth configuration from Apps, then execute with the intended connection or end-user identity.

Existing MCP servers

An existing server keeps its selected tools when the integration catalog gains an action. In the server's tool configuration, add get_file_outline and get_node_design_context explicitly, using the intended Figma alias and connection. Keep your existing tools and settings; you do not need to remove the integration or recreate the server.

Refresh the tool list in your AI client after adding the actions. Some clients require an administrator to review an updated tool list. For new workspace setups, the configured app action selection determines which tools are initially added to the server.

1. Map the file

Call get_file_outline with a file key or an HTTPS Figma design, file, or prototype URL. Without a selected parent, the action requests a shallow file outline. It returns compact IDs, names, node types and available geometry rather than the full design tree.

typescript
const outline = await client.actions.execute('figma', 'get_file_outline', {
  workspaceId: '123e4567-e89b-12d3-a456-426614174000',
  input: { fileKey: 'YOUR_FIGMA_FILE_KEY', maxNodes: 100 },
})

To expand a returned node, call the action again with parentNodeId and a depth of 1 or 2. A node-id in a Figma URL can supply the parent when parentNodeId is omitted. This is selection-based expansion, not a pagination cursor. Figma may also return ancestors or dependencies.

2. Read the selected design

Use get_node_design_context for one to ten selected node IDs. Always choose a depth of 1 or 2; the default is 1. You can supply comma-separated nodeIds, or one node through the file URL's node-id parameter.

typescript
const context = await client.actions.execute('figma', 'get_node_design_context', {
  workspaceId: '123e4567-e89b-12d3-a456-426614174000',
  input: {
    fileKey: 'YOUR_FIGMA_FILE_KEY',
    nodeIds: '1:2,1:3',
    depth: 1,
  },
})
python
context = client.actions.execute_typed(
    "figma",
    "get_node_design_context",
    workspace_id="123e4567-e89b-12d3-a456-426614174000",
    input={"fileKey": "YOUR_FIGMA_FILE_KEY", "nodeIds": "1:2,1:3", "depth": 1},
)

The output distinguishes requested nodes, missing or null nodes, and additional nodes returned by Figma. It includes available layout, spacing, typography, paint, effect and component properties. Component and style metadata are matched to the references in the selected response. Variable references retain their IDs; this action does not resolve whole libraries or variable values.

Inspect truncated, per-node truncatedFields, omitted-node counts and hints before treating the response as complete. Some reference metadata or nodes may be omitted to stay within the response budget. Ask for a narrower selection when necessary.

The outline response is limited to 24 KiB and design context to 48 KiB. Individual strings, arrays and nested objects are also bounded. Upstream responses larger than 2 MiB are rejected with guidance to narrow the selection; a request and its response read have a 15-second deadline.

3. Inspect images separately

  • render_images returns rendered-image URLs for selected IDs. Check for null results rather than assuming every node rendered.
  • list_image_fills returns image-fill URLs separately from node context.
  • These context helpers do not download image bodies or embed image data. An AI client must support fetching and viewing an image before it can claim visual inspection.

Figma image URLs expire. Request fresh URLs when an old link stops working. For the provider's current behavior, see Figma's image endpoints.

References, Code Connect and editing

These actions return Figma REST design data. They do not generate implementation code, supply Code Connect mappings or edit the native canvas. Compare component and style references with the actual components in your codebase before reusing them.

Figma's own remote MCP server and Code Connect have separate setup, client, seat and access requirements. See Figma's MCP documentation for those capabilities. Existing Weavz Figma comment, variable, development-resource and webhook actions remain separate operations; a context read does not perform them.

Recover from a failed read

  • Forbidden: check the connected account's file access and file_content:read permission.
  • Not found or missing node: confirm the file key, selected node IDs and optional version. Missing nodes are reported explicitly.
  • Rate limited: respect the returned retry guidance. Avoid repeatedly reading the whole file.
  • Too large or timed out: request fewer nodes or expand one parent at a time.
  • Truncated output: retain the source IDs and request the omitted context before drawing conclusions from it.

Read the action execution guide for connection selection and result handling, or browse the Figma integration for all supported actions.