Figma MCP not working: find your symptom
Most FigmaMCP problems come from three things: the agent started before setup, the plugin is not open, or the file is set to read-only. This page covers FigmaMCP. For Figma’s own server, see Figma’s docs.
| What you see | Cause | Fix |
|---|---|---|
| The agent has no Figma tools | It was running before setup | Restart Claude Code or Codex. |
| FigmaMCP is missing from the Plugins menu | The plugin is not installed | Open the FigmaMCP app and click Add to Figma. |
PLUGIN_PEER_UNAVAILABLE, or no plugin connected | The plugin is not open in this file | Open the file in the desktop app. Then choose Plugins, Development, FigmaMCP. Allow Accessibility if you want the app to do this for you. |
CHANNEL_NOT_BOUND, or the agent asks which file | The plugin is open in more than one file | Give your agent a Figma link to the file you mean, or close the plugin in the others. |
READ_ONLY_MODE, or it reads but does not edit | AI can edit this file is off | Turn the switch on in the plugin. |
| The name does not match | The layer changed after the agent read it | Ask your agent to read the layer again and retry. |
| Edit refused inside an instance | Structure inside an instance cannot change | Edit the main component, or change the instance’s properties and overrides. |
| A library asset is read-only | It belongs to another file | Edit it in its source library. |
PLUGIN_DISCONNECTED | The plugin closed or reloaded during a command | Reopen the plugin. Check whether the last edit applied before you repeat it. |
VERSION_MISMATCH | The app and plugin versions differ | Download the latest FigmaMCP, run its checklist, and restart your agent. |
CHANNEL_IN_USE | Too many agent sessions use this file | End one of the other sessions. |
| Nothing happens in browser Figma | FigmaMCP needs the desktop app | Open the file in the Figma desktop app. |
Still stuck?
Open an issue on the releases page. Include what you asked, the exact error and your macOS version. Do not include private design content. See also the setup guide.
Questions
Do I need to reinstall when something fails?
Usually not. Check that your agent was restarted, that the plugin is open, and that the switch is on.
Why does a retry give the same error?
These errors come from fixed rules. Change the condition first, for example open the plugin or refresh the layer name.
Does this page apply to Figma's official MCP server?
No. It covers FigmaMCP only.
