FigmaMCP

Audit a Figma file with AI

FigmaMCP lets Claude Code or Codex audit a Figma file with reads only: unnamed frames, text with no style, hard-coded colors and components with no properties. Reads never change the file, so an audit is a safe first job. You can switch off edits while it runs. Notes are the only write, and they are optional.

What to ask for

Audit requests
QuestionReads
Which layers are still named “Frame 12”?page_info, node_info
Which text uses no text style?node_info, style_list
Which fills are hard-coded, not variables?node_info, variable_list
Which components have no description or properties?component_list

How the agent reads a file

FigmaMCP’s page_info lists the pages, and with page IDs it returns each page’s top-level layers, up to 25 pages per call. node_info reads layers and their children. You choose the properties, a filter and a depth. For an audit, useful properties are boundVariables, fillStyleId, strokeStyleId, effectStyleId and textStyleId. A layer with no style or no bound variable shows up as a finding.

style_list returns the local paint, text, effect and grid styles. variable_list returns local variables and collections. With a variable ID and includeConsumers, it also lists which layers use that variable. component_list can filter by local or remote, and by page or whole document. Styles and variables from shared libraries do not appear in these lists. The agent finds them through a layer that uses them.

Check that the read was complete

A read that returns without an error can still be partial. FigmaMCP’s multi-page reads return a coverage object. Read coverage.complete before you say that a page is clean. coverage.pageErrors names each page that failed and gives a reason.

Read errors in an audit
CodeMeaningWhat to do
PAGE_LOAD_FAILEDOne page refused to load.Retry once. If it fails again, continue with the other pages and report that page.
PAGE_SCAN_FAILEDThe page loaded, but reading it failed.Narrow the read to one page, one layer or fewer properties.
PAGE_LOAD_TIMEOUTA page did not load in time.Retry once, then continue without it and say so.
PAGE_NOT_FOUNDThe page ID does not exist.Get fresh IDs from page_info.

Write the findings into the file

The agent can report in chat. It can also write each finding as a native annotation with annotation_set. That tool needs the layer ID, the exact layer name and a Markdown label. This is a write, so the AI can edit this file switch must be on. Without it you get READ_ONLY_MODE. Annotations are appended. Run annotation_list first, so a second audit does not add the same note again.

A sensible order

  1. Ask for one page at a time. Large files take many calls.
  2. Ask for a short report that groups findings by type.
  3. Fix what you agree with using bulk edits.

Download for Mac Version 0.1.20 macOS 14+ · Intel & Apple Silicon · ~155 MB

Related: All tools · Design system · Variables

Questions

Can an audit change my file?
No. Reads never change the file. Only annotation_set writes, and only if you ask for notes in the file.
Can it read a very large file?
Large files take more calls. Ask for one page at a time.
How do I know the audit covered every page?
Check coverage.complete in the result. If it is false, coverage.pageErrors names the pages that failed, and the findings do not cover them.
Does it list styles and variables from shared libraries?
Not directly. style_list and variable_list return local items only. The agent finds library items through the layers that use them, with node_info.

Last updated: