Figma MCP in Claude Code: Setup, the Errors People Hit, and What Fixes Them

Direct answer

Run claude plugin install figma@claude-plugins-official, restart Claude Code, open /plugin, select the figma server, authenticate in the browser, then give Claude a link to a Figma frame. Manual alternative: claude mcp add --transport http figma https://mcp.figma.com/mcp, then /mcp and Authenticate. Figma recommends the remote server over the desktop one.

What you need, and which server to use

The Figma MCP server lets an agent such as Claude Code read a Figma file and, on supported clients, write to it. MCP, the Model Context Protocol, is the open standard that lets a client like Claude Code call tools exposed by a separate server. Here the server is run by Figma and the client is Claude Code.

Setup takes one command and one browser approval. What takes longer is knowing which of two servers you want, and what limits come with your plan. Both are decided before you type anything.

• Claude Code installed, with a terminal where you can run the claude command.
• A Figma account. Figma says the remote server is available on all seats and plans, though a free Starter plan comes with a small monthly call allowance (see the limits section).
• A Figma file you can open, and a link to one frame or layer in it. The remote server reads what a link points to, not what you have selected.

Everything below that is a command or a setting comes from Figma's or Anthropic's own documentation, fetched on October 1, 2026. The errors section also draws on GitHub issues and forum threads, and labels those as community-reported.

Figma ships two servers. The remote server is hosted by Figma at https://mcp.figma.com/mcp. The desktop server runs on your own machine through the Figma desktop app, at http://127.0.0.1:3845/mcp.

Figma's own docs state a preference in so many words:

The link-versus-selection row matters more than it looks. If you set up the remote server and then tell Claude to build "the frame I have selected", there is nothing on the server side that knows about your selection. This is an inference from the documented behaviour, not a quoted error, but it explains a common confusion: a prompt written for one server fails on the other.

For this guide the remote server is the default path. The desktop server gets its own short section below.

Connect Figma to Claude Code, then send a first prompt

Figma's help centre lists a plugin install as the recommended route for the remote server. The manual command is the fallback, and the one to use if you want the server in a specific scope.

1. Install: claude plugin install figma@claude-plugins-official.
2. Restart Claude Code.
3. In Claude Code, type /plugin, press the right arrow to reach the Installed tab, select figma, and press Enter.
4. Press Enter again to start authentication. A browser page opens; click Allow access.
5. Return to the terminal and run /plugin again. The figma server should show as active.

The scope flag is Claude Code's, not Figma's. Anthropic's MCP documentation lists three scopes: local, the default, loads only in the current project and is stored in ~/.claude.json; project writes .mcp.json in the project root so a team can share it through version control; user loads in all your projects. Pick project only if you want teammates to receive the entry, since each person still authenticates with their own Figma account.

Sources for both routes: Figma's Claude Code setup article, the remote server installation page, and Anthropic's Claude Code MCP documentation.

Use the desktop server only when you have a reason, such as an organisation that requires it. Figma's setup page lists the requirements: the latest Figma desktop app, and a Design file.

1. Open a Design file in the Figma desktop app and switch to Dev Mode (shortcut Shift+D).
2. In the MCP server section of the right sidebar, click Enable desktop MCP server. The server runs at http://127.0.0.1:3845/mcp.
3. In your terminal run claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp.
4. Restart Claude Code.

A warning about older tutorials. Some guides still show claude mcp add --transport sse figma-dev-mode-mcp-server http://127.0.0.1:3845/sse, for example Builder.io's walkthrough published July 28, 2025. That command used an older SSE endpoint. Figma's current documentation uses the HTTP transport and the /mcp path, so copy from the vendor page, not from a post that predates it. We have not tried either command, and cannot say whether the old one still connects.

Check the connection before you write a prompt. In Claude Code, /mcp (or /plugin if you used the plugin) lists each server's state: connected, needs authentication, or failed to connect. Anthropic documents those three states. If figma is not connected, nothing the prompt says will help.

Then give the remote server a link. In Figma, copy the link to a frame or layer. Figma's docs say the server extracts the node-id from that URL to find the object, so a link to the file's front page identifies nothing specific.

A first prompt can be as plain as: "Implement this Figma frame as a React component: [link]." Claude then calls tools on the server. Figma's tools page lists read tools including get_design_context, get_metadata, get_screenshot, download_assets and get_variable_defs, and write tools including use_figma, generate_figma_design, create_new_file, upload_assets and generate_diagram.

Start with a small frame, such as one card or one form, not a full page. The reason is documented in the next section: large frames produce large responses, and Claude Code caps how much of one it accepts.

The errors people hit and what fixes them

The table matches each symptom to its likely cause and the fix. Where Figma or Anthropic documents the fix, it says so. Where the fix comes from a GitHub issue or forum thread, it is marked community-reported, which means one person's experience, not a guarantee.

The sections below explain the entries that need more than a table cell.

Token limits and authentication: the documented and the reported

Figma's known-issues page documents one Claude Code error by name. It reads: Error: MCP tool "get_design_context" response (351378 tokens) exceeds maximum allowed tokens (25000). Figma's resolution is to raise the MAX_MCP_OUTPUT_TOKENS environment variable, with 50000 or 100000 as suggested values, and restart.

Anthropic's documentation confirms the numbers on its side: Claude Code shows a warning above 10,000 tokens of tool output and enforces a default maximum of 25,000. Its example sets the variable in the shell before launching:

• export MAX_MCP_OUTPUT_TOKENS=50000
• claude

Raising the cap treats the symptom. The error happens because the frame you pointed at is large, and a larger cap also means a larger share of the model's context goes to one design. A cheaper habit, which is our inference and not Figma's advice, is to link the component you want built instead of the page that contains it, and let Claude work through the page one piece at a time.

The official sources describe the happy path and nothing more. The failure reports come from users filing issues against Claude Code, and all three below were closed without a fix recorded in the issue.

• Issue 35957, March 18, 2026, Claude Code 2.0.25 on macOS: authentication completed, Claude Code received the callback, but no token was written to the configuration. Closed as not planned. The reporter tried restarting, re-adding the server and repeating the flow without success.
• Issue 55943, May 4, 2026, Claude Code 2.1.126: the token was stored but the reconnect hung for 30 seconds and failed with a restart message. The reporter's workaround was to quit and relaunch, after which the token worked. Closed as not planned.
• Issue 61265, May 21, 2026, Claude Code 2.1.142: only authentication tools appeared and the loop repeated. Closed as a duplicate.

These are individual reports against specific versions, and Claude Code ships often. A bug seen on 2.1.126 may not exist on the version you run. Check the issue dates and versions against your own before concluding anything.

The commands Anthropic documents for managing a stuck login are /mcp with Re-authenticate or Clear authentication, and claude mcp login <name> or claude mcp logout <name> from the shell. claude mcp remove <name> deletes the entry so you can add it again cleanly.

One more case, on the desktop server. A January 2026 forum thread reports a 403 when asking Claude Code to implement a design from a URL. A community-support reply listed three checks: that the account has Dev Mode MCP access, that the OAuth token is valid, which you test by reconnecting the server, and that a Full or Dev seat exists in the relevant team. A 403 typically points at permission, not a malformed command (inference).

Rate limits: a working install that stops working

The calls Claude makes to read from Figma count against an allowance tied to your plan and seat. Figma's rate limits page gives the figures below. Per-minute limits apply in addition to the daily or monthly ones.

Two details are easy to miss. Education plans follow the Professional Dev and Full seat limits, up to 200 calls per day and 10 per minute. And three tools are excluded from the limits: add_code_connect_map, create_new_file and whoami.

The table lists Starter once, as 20 calls per month. Figma's page says so in its upgrade text, and a Figma staff reply on the forum confirms the same figure and adds that it is separate from Figma AI credits:

Twenty calls is thin for agent work, because one design-to-code request can involve several tool calls (context, screenshot, variables). Figma's page does not publish an error message for hitting the limit, and the forum poster in that thread reported being rate-limited and asked for a usage count and reset date. Figma's documented remedy is to upgrade the seat or plan. We cannot say how many calls a given prompt will consume, since that depends on the model's choices.

Is it practical? What practitioners report

Official docs show how to connect it. They say little about whether the output is good. The evidence available is thin and mixed, and some of it is old.

We tried to read the r/FigmaDesign discussions on this topic, but Reddit blocked automated access, so none are cited here. What we can point to is written by named people elsewhere.

Anthropic's own account announced a Claude Code to Figma flow in February 2026:

Practitioner reports are less rosy. Vishwas Gopinath at Builder.io, writing in July 2025 about the desktop server, listed limits he saw: it struggles to make small edits to code that already exists, multi-frame flows must be converted frame by frame and stitched together by hand, and the command-line workflow keeps non-developers out. That was an earlier version of the server, so treat it as dated.

On Figma's own forum, a poster in June 2025 reported wrong colours, fonts and styling from Claude Code and Cursor, and later wrote that restarting Figma before using the MCP fixed it for them. A Figma staff reply in the same thread said the server then ran locally inside the desktop app. A single user's fix, but a cheap thing to try on the desktop server.

Our reading, which is interpretation: the server is a reliable way to give an agent structured design context when the connection works and the frame is small. It is a poor fit for large pages, free-plan usage, and edits to existing code. Whether the generated code matches your design depends on your design system and prompts, and nobody has published a measurement we could verify.

A first-run checklist that separates setup from prompt problems

When something fails, the order below finds the layer at fault with the fewest steps. Each check maps to a row in the failure table.

1. Run /mcp (or /plugin). If figma is not connected, fix authentication first: Re-authenticate, claude mcp login figma, then a full quit and relaunch of Claude Code.
2. Confirm which server you added: claude mcp list shows names. A figma entry pointing at https://mcp.figma.com/mcp needs a link in the prompt; a figma-desktop entry needs the desktop app open with Dev Mode enabled.
3. Use a link to one small frame, copied from Figma so it includes the node-id.
4. If you see a token-limit error, raise MAX_MCP_OUTPUT_TOKENS to 50000, or link a smaller frame.
5. If calls fail after a few successes, check your plan and seat against the limits table before changing anything else.
6. If a 403 appears, confirm your seat type and reconnect the server.

Worked example. Suppose Claude says it cannot access the design, you are on the remote server, and /mcp shows connected. That rules out authentication. The remaining suspects are the link (does it carry a node-id?), the account's permission to view that file, and the plan's call allowance. Checking those three takes a minute and does not need a reinstall.

Where this leaves you

You can connect Figma to Claude Code in a few minutes with Figma's documented commands: a plugin install or claude mcp add --transport http figma https://mcp.figma.com/mcp, followed by browser authentication. The remote server is the one Figma recommends, and it works from links.

The setup rarely fails on the command. It fails on authentication persistence in some Claude Code versions, on the 25,000-token default output cap, on plan call allowances, and on links that carry no node. Match the symptom to the table above, and use the official fixes first.

All limits and commands here are as of October 1, 2026, and Figma and Anthropic may change them. Check the linked pages before relying on a number.