Troubleshooting

A detailed guide for troubleshooting common issues with the Framelink Figma MCP server 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

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 Figma MCP": {
      "command": "npx-for-claude",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}