Canvashand
Start free trial
All guides

Figma MCP in Claude Code: set up Canvashand in 5 minutes

Connect Claude Code to Figma with a local MCP server and plugin. Four setup steps, first prompts, subagents across files, and fixes for common errors.

Canvashand connects Claude Code to the Figma file you have open, so Claude can read the live canvas and write to it. You install the CLI, run canvashand setup claude-code in your project, import the plugin into Figma desktop once, and ask Claude to describe your selected frame. Claude Code talks to a local MCP server with 99 tools, and that server talks to the plugin inside your file. There is no Figma API token to create and no Figma rate limit to hit. This guide covers the setup, three prompts to try first, running subagents in several files, and what to do when something does not connect.

Set up Canvashand in Claude Code

You need three things before you start: Figma desktop, a Canvashand account (sign in with Google at the setup page), and Claude Code. The browser version of Figma cannot import a local plugin.

1. Install the CLI

curl -fsSL https://www.canvashand.com/install.sh | sh

The installer detects your platform, checks the SHA-256 checksum, and puts canvashand on your PATH. It also puts the Figma plugin in ~/.canvashand/canvashand-plugin. On Windows, or if you prefer to download by hand, use the download page.

2. Run setup for Claude Code

Go to the project where you want Claude Code to use Figma, then run:

canvashand setup claude-code

You can also run canvashand setup --all --scope project, which configures every AI client it detects on this machine or in this folder, Claude Code included. Naming the client always works. --all skips a client it finds no sign of.

Setup does two things in the current directory:

  • It adds a canvashand entry to .mcp.json. The entry is a stdio server that runs the canvashand command.
  • It installs the bundled canvashand skill in .claude/skills. The skill carries the design workflow that Claude follows for product UI work.

Setup edits your existing .mcp.json in place. It keeps your other servers, comments, and key order. canvashand setup writes only Claude Code's project config, so --scope user does not apply to it: canvashand setup claude-code --scope user stops with the message "claude-code has no user config; use --scope project".

3. Open the plugin in Figma

In Figma desktop, import the plugin once:

  1. Open Plugins, then Development.
  2. Choose Import plugin from manifest.
  3. Pick ~/.canvashand/canvashand-plugin/manifest.json.

The folder is hidden, so type its path in the file picker. On macOS, press Cmd+Shift+G and paste the path. On Windows, press Alt+D and paste %USERPROFILE%\.canvashand\canvashand-plugin. On Linux, press Ctrl+L and paste the path. If you imported Canvashand from a zip before, remove that plugin in Figma first. The plugin is not on Figma Community. It ships with your account.

Then open a file, run Plugins, Development, Canvashand, sign in with the same Google account, and keep the plugin window open.

4. Verify the connection

Start Claude Code in the project folder. The first time, Claude Code asks you to approve the servers in the project's .mcp.json: approve canvashand. /mcp shows whether it is connected. Then ask:

Use Canvashand to describe my selected frame.

Select a frame in Figma first. If Claude describes it, the whole chain works: Claude Code, the local server, the plugin, and your file. This is the test the setup page uses.

First prompts to try

Start with a read, because it changes nothing:

Read the selected frame and list its components, tokens, and text styles.

Then turn a design into code. Copy a link to a frame in Figma (right-click the frame, then Copy link to selection) and paste it into your request:

Build this screen in our app so it matches Figma exactly:
https://www.figma.com/design/<file-key>/<file-name>?node-id=12-34
Use canvashand. Reuse our components and tokens, and prove the match with screenshots.

Replace the link with your own. The file behind the link must be open in Figma with the plugin running. Claude converts node-id=12-34 to the node ID 12:34, reads the frame in small pieces, and builds from your repository's components and tokens. Turn a Figma link into code that matches shows the full loop, including the screenshot diff.

Last, let Claude design in Figma:

Design a mobile habit tracker called Streak: theme and tokens, shared components, and Today, Habit detail, and Add habit screens at 390 wide, wired into a flow. Use canvashand.

For a build like this, the canvashand skill starts a change session with begin_change_session, which saves a restore point in Figma version history. Claude then plans the screens with create_design_plan, builds them as high-fidelity frames, audits them with run_design_audit, and closes the session with end_change_session. If you do not like the result, rollback_changes deletes everything the session created. To undo edits to layers that already existed, restore the checkpoint in Figma version history. Run AI agents and subagents in Figma walks through each step.

Work across several files with subagents

Open the plugin in every file you want Claude to use. Each file joins the same local server, on port 21994 or the next free port up to 21998. You configure nothing extra.

  • list_files shows each connected file with its fileId and name.
  • select_file sets the default file for the current session.
  • Any tool accepts an optional fileId, which is how each subagent targets its own file.

Each file keeps its own change sessions, rollback journal, and credit lease. One agent's rollback never touches another file. Reopening the plugin in a file reconnects it under the same ID.

Claude Code supports subagents, so you can ask for them directly:

Use three subagents in parallel, one per open Figma file from list_files: the design system in 'Design system', the onboarding flow in 'Onboarding', and the settings screens in 'Settings'.

Name the file in each brief, so the subagent passes the right fileId. Parallel agents share one account quota: every file's lease draws on your plan's calls. Two separate Claude Code windows can also work in two files against the same server. See Several Figma files, several agents, one server.

Free includes 2,000 tool calls a month. Pro is $6.99 a month or $69.99 a year with unlimited calls, and starts with a 7-day trial. Check the pricing page for current plans. Parallel subagents use calls fast, so a long session may be more than Free covers.

Troubleshooting

canvashand: command not found. The install folder is not on your PATH. The installer prints the line to add. Otherwise, add this to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

macOS stops canvashand with no message. This happens only after a browser download of the binary, because macOS quarantines it. The installer script is not affected. Clear the flag once:

xattr -d com.apple.quarantine $(command -v canvashand)

Claude says tool calls are refused, or no active quota session. The server is running, but the plugin is not connected or not signed in. Open Canvashand in the Figma file and sign in with Google. Credits are leased by the plugin, so the server refuses tool calls without an active session. An error of plugin not connected has the same fix.

file "..." not connected. You named a fileId for a file that does not have the plugin open. The error lists the files that are connected. Open the plugin in that file, or call list_files and use one of the listed IDs.

Setup cannot parse .mcp.json. Setup then changes nothing and prints the entry for you to add by hand. It is the same entry described in step 2.

Setup refuses to write the skill. If .claude/skills/canvashand exists and setup did not create it, or you edited it, setup stops and asks you to move or remove it. It never overwrites an unmanaged skill.

After an upgrade. canvashand upgrade updates the CLI and the plugin. To refresh the .mcp.json entry and skill in a project that is already set up, run canvashand update from that folder.

Official Figma MCP vs Canvashand in Claude Code

Figma publishes its own MCP server, and it works in Claude Code too. Figma's help center describes two routes. The recommended one is the remote server: run claude plugin install figma@claude-plugins-official, restart Claude Code, then authorize figma from /plugin. The other is the desktop server, added with claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp, after you enable it in Dev Mode.

The official server is a good fit if you rely on Code Connect, want a first-party hosted server with no plugin to run, or read designs only a few times a day. Canvashand fits better if your agents loop over many reads, work in several files at once, or need per-file rollback and no API token. You can run both in one Claude Code project, because the two servers have different names. For limits, seats, and a tool-by-tool table, read Canvashand vs the official Figma MCP server. The per-seat call limits are in Figma MCP rate limits.

Sources

Figma and Claude Code are trademarks of their owners. Canvashand is independent and not affiliated with Figma, Inc. or Anthropic.