Figma MCP prototype
FigmaMCP lets Claude Code or Codex read and replace prototype reactions on layers in the Figma file you have open, and write annotations that explain a design to developers. Four tools cover this: reaction_list, reaction_update, annotation_list and annotation_set. Every write names its target layer, and the name must match.
Tools
| Task | Tool | Writes to the file? |
|---|---|---|
| See existing interactions | reaction_list | No. Reads the reactions on the layers you name and on their descendants. |
| Add or change an interaction | reaction_update | Yes. Replaces the whole reaction array of one layer. |
| Read annotations | annotation_list | No. Reads one page or one layer and its subtree. |
| Write annotations | annotation_set | Yes. Appends annotations to one or more layers in one batch. |
What reaction_update can set
FigmaMCP’s reaction_update tool takes the layer’s ID, its exact current name, and the full list of reactions that layer should have afterwards. Each reaction has a trigger and an action, or a list of actions. A trigger has a type such as ON_CLICK or ON_HOVER, and can carry a delay or key codes.
| Action type | What it does in the prototype |
|---|---|
NODE | Goes to a destination layer, with a navigation type and an optional transition. |
URL | Opens a link. |
BACK, CLOSE | Goes back, or closes an overlay. |
SET_VARIABLE, SET_VARIABLE_MODE | Changes a variable value or a variable mode. |
CONDITIONAL | Runs different actions depending on a condition. |
UPDATE_MEDIA_RUNTIME | Controls media playback. |
How to change an interaction safely
FigmaMCP replaces the whole reaction array and does not patch one reaction inside it. Order matters.
- Read the layer with
node_infoand copy its exact name. - Call
reaction_listfor that layer, so you know which reactions exist now. - Call
reaction_updatewith the full array: the reactions you keep plus the new one. - Call
reaction_listagain and check the flow in Figma’s prototype view.
If you skip step 2, the new array can remove interactions you wanted to keep. The tool reads and writes native reaction data only. It cannot draw a flow diagram for you. The read may not return every field Figma stores for a reaction, so check the result in prototype view.
Annotations for developers
FigmaMCP’s annotation_list needs exactly one of pageId or nodeId. It returns the annotations grouped by the layer that owns them. It also returns the file’s annotation categories, unless you pass includeCategories: false. Check coverage.complete before you say that a page has no notes.
annotation_set takes a list. Each item has nodeId, nodeName and labelMarkdown, which must not be blank. It can also take a categoryId from annotation_list and a list of property references, such as fills or itemSpacing. Figma refuses a property the layer type does not support, and that item fails on its own.
Errors you can meet
| Error | Meaning | What to do |
|---|---|---|
NAME_MISMATCH | The name you sent is not the layer’s current name. It arrives as UNKNOWN_ERROR. | Read the layer again with node_info, then retry with the real name. |
READ_ONLY_MODE | The plugin’s AI can edit this file switch is off. | Turn the switch on. Reads still work. |
ANNOTATION_CATEGORY_NOT_FOUND | The categoryId does not exist in this file. | Call annotation_list and pass back a category ID it returned, or leave it out. |
Annotation writes add to what exists. A repeat does not replace, and it can make a duplicate. When an item reports partial_success or an unknown outcome, call annotation_list before you retry.
Download for Mac Version 0.1.20 macOS 14+ · Intel & Apple Silicon · ~155 MB
Related: All tools · Write tools · Edit Figma with AI
Questions
Can it link every button to a screen?
Does reaction_update keep the reactions that are already there?
Can FigmaMCP draw a connector diagram or flow chart?
Will it add the same annotation twice if I run the request again?
Last updated: