FigmaMCP

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

Prototype and note tools
TaskToolWrites to the file?
See existing interactionsreaction_listNo. Reads the reactions on the layers you name and on their descendants.
Add or change an interactionreaction_updateYes. Replaces the whole reaction array of one layer.
Read annotationsannotation_listNo. Reads one page or one layer and its subtree.
Write annotationsannotation_setYes. 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.

Reaction action types
Action typeWhat it does in the prototype
NODEGoes to a destination layer, with a navigation type and an optional transition.
URLOpens a link.
BACK, CLOSEGoes back, or closes an overlay.
SET_VARIABLE, SET_VARIABLE_MODEChanges a variable value or a variable mode.
CONDITIONALRuns different actions depending on a condition.
UPDATE_MEDIA_RUNTIMEControls media playback.

How to change an interaction safely

FigmaMCP replaces the whole reaction array and does not patch one reaction inside it. Order matters.

  1. Read the layer with node_info and copy its exact name.
  2. Call reaction_list for that layer, so you know which reactions exist now.
  3. Call reaction_update with the full array: the reactions you keep plus the new one.
  4. Call reaction_list again 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

Prototype and annotation errors
ErrorMeaningWhat to do
NAME_MISMATCHThe 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_MODEThe plugin’s AI can edit this file switch is off.Turn the switch on. Reads still work.
ANNOTATION_CATEGORY_NOT_FOUNDThe 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?
It can, if you say which screens. Review the flow in prototype view.
Does reaction_update keep the reactions that are already there?
No. It replaces the whole array on that layer. Read the reactions with reaction_list first and send back the ones you want to keep.
Can FigmaMCP draw a connector diagram or flow chart?
No. FigmaMCP has no tool that discovers connector templates or builds a flow diagram. It reads and replaces native prototype reactions, and it reads and appends annotations.
Will it add the same annotation twice if I run the request again?
It can. Annotations are appended, so a repeat makes a second note. Run annotation_list first and compare, then write only what is missing.

Last updated: