Troubleshooting

A detailed guide for troubleshooting common issues is coming soon. In the meantime, you can join our Discord server or leave an issue on Github and we'll help you out.

Cannot find module

If you encounter an error like Cannot find module 'xxxxx', it means that something went wrong with installation of the MCP server.

To fix this, close your client and try running the following command:

npx clear-npx-cache

Then open your client again. If the issue persists, please join our Discord server or leave an issue on Github and we'll help you out.

403 Forbidden when accessing Figma files

Even when you've connected to the MCP server correctly, you may still encounter an error like this:

Error fetching file: {"status":403,"err":"Forbidden"}

If you're seeing a "403 Forbidden" error, the issue is likely with file access permissions rather than your MCP setup. Here are the common causes and solutions:

Access Permissions

The Figma file needs to be either:

• Owned by the account associated with your access token
• Explicitly shared with your account
• If using a team/org file, your API token must have access to that team

Node ID Issues

Verify that you're using a valid node ID:

• Open the Figma file and select the element
• Copy the correct node ID from either the URL or developer tools
• Confirm the node exists in the current file version

File Access Settings

Check that the file is accessible via the API:

• Open the file in Figma
• Click the "Share" button
• Ensure the account linked to your access token has at least "View" permissions
• Check to make sure viewers can copy, share, and export from the file

429 Too Many Requests

If you encounter a 429: Too Many Requests error, it means you have exceeded the Figma API rate limits. There is no rate limiting built into the Framelink MCP itself; these limits come directly from Figma.

There are a few common causes and solutions for this issue.

Upgrade to a Paid Plan

Your rate limits depend on your Figma plan:

• Free Plan: Limited to approximately 6 requests per month.
• Any Paid Plan (including Dev Seats): Starts at 10 requests per minute for the endpoints used by Framelink.

For more details, see Figma's Rate Limit documentation.

Check File Ownership

Rate limits are determined by the file owner's plan in addition to your account's plan.

• If you are accessing a file in a Starter plan team/project, you will be subject to Starter limits (very low).
• Solution: Duplicate the file into your own paid workspace/team. Your paid plan limits will then apply to the copy.

Wait for API Limits to Update

If you recently upgraded to a paid plan, there might be a delay before the API limits are updated. Some users report this can take some time to propagate.

Claude Desktop: wrong Node version

If you use a version manager like NVM to manage your Node.js version, you may run into an issue where Claude Desktop ends up using the wrong version of Node.js.

To fix this, you can create a special version of npx for Claude Desktop to use that uses the right version of Node.js.

#!/bin/zsh

# You may need to update this path to match your shell. This line is meant
# to load the file that sets the path to the Node.js version you want.
source ~/.zshrc
exec npx "$@"

Then run chmod +x /usr/local/bin/npx-for-claude to make it executable. Update your configuration in Claude Desktop to use this new npx command instead of the default one.

{
  "mcpServers": {
    "Framelink MCP for Figma": {
      "command": "npx-for-claude",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}