Figma Proxy MCP

Official registry Developer tools

Figma → code: tokenized IR, PNG renders and SSIM/pixel visual diff to verify builds.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package figma-proxy-mcp
Claude Code
claude mcp add figma-proxy-mcp -e 'FIGMA_API_KEY=<your figma_api_key>' -- npx -y figma-proxy-mcp@1.1.1 --stdio
JSON configuration (Claude Desktop, Cursor, VS Code)
{
    "mcpServers": {
        "figma-proxy-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "figma-proxy-mcp@1.1.1",
                "--stdio"
            ],
            "env": {
                "FIGMA_API_KEY": "<your figma_api_key>"
            }
        }
    }
}

Environment variables

  • FIGMA_API_KEY required secret Figma personal access token (read-only file content scope)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. figma-proxy-mcp
  2. 1. Requirements
  3. 2. Get your Figma token (2 minutes)
  4. 3. Connect to your AI tool (npx, recommended)
  5. 4. Check your setup
  6. 5. Alternative: run from a git clone
  7. 6. HTTP mode (scripts / agents that start it on demand)
  8. 7. Recommended workflow
  9. 8. Environment variables
  10. Troubleshooting
  11. Development
  12. Security
  13. License

figma-proxy-mcp

MCP server for Figma → code pipelines. It reads Figma through the REST API and returns data an agent can use directly, instead of the raw Figma tree:

ToolWhat it gives the agent
get_figma_componentNormalised IR of a node: summary:true (sections + boxes + tokens), format:"flat", lean:true (flat node list with coordinates relative to the root), CSS variables and a ready Tailwind theme
render_node_pngReference render of a node (PNG, base64 + image URL)
verify_renderRenders your HTML in headless Chromium and diffs it against the Figma render → SSIM, pixel-diff %, clustered diff regions
export_svg, migrate_all_svgs, list_svg_cacheIcon / vector export
get_figma_file, get_cached_components, get_component_by_nameFile tree and component cache

Read-only: it never writes to your Figma files. Every host it contacts and every file it writes is listed in SECURITY.md.


1. Requirements

  • Node.js 20+ (https://nodejs.org, LTS). Check with node -v.
  • A Figma personal access token (next section).
  • Optional, only for verify_render: Chromium for Playwright (step 4).

2. Get your Figma token (2 minutes)

  1. Open Figma (web or desktop) → click your avatar → Settings.
  2. Tab Security → Personal access tokens → Generate new token.
  3. Name: figma-proxy-mcp. Expiration: your choice (90 days is fine).
  4. Scopes: File content → Read-only (enough for everything here). Optionally Dev resources → Read-only.
  5. Click Generate token and copy it now. It starts with figd_ and is shown only once.

The token can read every file your account can open. To work with someone else's file, ask them to share it with your Figma account (view access is enough).

No clone needed. npx downloads and runs the published package.

Claude Code (run in your project folder):

claude mcp add figma-proxy -e FIGMA_API_KEY=figd_your_token -- npx -y figma-proxy-mcp --stdio

Add --scope project to share the server with your team via .mcp.json, but then do not put the token in that file: export FIGMA_API_KEY in your shell instead.

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json) / Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "figma-proxy": {
      "command": "npx",
      "args": ["-y", "figma-proxy-mcp", "--stdio"],
      "env": { "FIGMA_API_KEY": "figd_your_token" }
    }
  }
}

Restart the app after editing the config.

Token lookup order: environment variable (the env block above) → .env in the working directory → .env next to the package. Never commit a real token.

4. Check your setup

FIGMA_API_KEY=figd_your_token npx -y figma-proxy-mcp --check

It checks the Node version, that the token is set (the value is never printed), that Figma accepts it (GET /v1/me, only the HTTP status is shown), and whether Chromium is available. Exit code 0 = ready, 1 = something required is missing.

For verify_render, install Chromium once:

npx playwright install chromium

Already have Chrome/Chromium and cannot download? Set FIGMA_PROXY_CHROME_PATH to its binary.

5. Alternative: run from a git clone

git clone https://github.com/Semmargl/figma-proxy-mcp.git
cd figma-proxy-mcp
npm install
npx playwright install chromium     # only for verify_render
cp .env.example .env                # then put your token in .env
npm run check

Connect with the absolute path to proxy-mcp.js:

claude mcp add figma-proxy -- node /ABS/PATH/figma-proxy-mcp/proxy-mcp.js --stdio
{ "mcpServers": { "figma-proxy": { "command": "node", "args": ["/ABS/PATH/figma-proxy-mcp/proxy-mcp.js", "--stdio"] } } }

The .env next to proxy-mcp.js is found whatever the working directory is.

6. HTTP mode (scripts / agents that start it on demand)

npx -y figma-proxy-mcp     # → http://127.0.0.1:4444/mcp  (JSON-RPC: initialize, tools/list, tools/call)
curl -s 127.0.0.1:4444/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_figma_component","arguments":{"figmaUrl":"<link with node-id>","summary":true}}}'

It binds to loopback only. Change with FIGMA_PROXY_PORT / FIGMA_PROXY_HOST.

The server also sends this to MCP clients as instructions on initialize.

  1. Links must contain node-id: in Figma right-click a frame → Copy link to selection.
  2. get_figma_component {figmaUrl, summary:true}: tokens, Tailwind theme, registry, root box, sections with relativeBox.
  3. Per section: get_figma_component {figmaUrl, format:"flat", lean:true}.
  4. Build the markup with the $--var tokens and relativeBox coordinates.
  5. render_node_png {figmaUrl, scale:2} for the reference image.
  6. verify_render {htmlPath, frameWidth, figmaUrl, scale:2}, fix only the reported regions, repeat until SSIM ≥ threshold (default 0.95).

verify_render needs htmlPath (absolute path to a self-contained HTML file) and frameWidth (the Figma frame width = root w from the summary).

8. Environment variables

VariableDefaultPurpose
FIGMA_API_KEY(required)Figma personal access token
FIGMA_FILE_DEPTH / FIGMA_NODE_DEPTH4 / 12Fetch depth for helper scripts
FIGMA_PROXY_CACHE_DIR<os temp>/figma-proxy-mcpBase dir for everything the server writes
FIGMA_PROXY_DATA_DIR<cache>/dataComponent registry
FIGMA_PROXY_VERIFY_DIR<cache>/verify-outverify_render diff images
FIGMA_PROXY_SVG_DIR./exported-svgsDefault SVG output dir
FIGMA_PROXY_CHROME_PATH(Playwright's Chromium)Use an existing Chrome/Chromium binary
FIGMA_PROXY_PORT / FIGMA_PROXY_HOST4444 / 127.0.0.1HTTP mode
FIGMA_PROXY_NO_DOTENVunset1 = ignore .env files

Troubleshooting

SymptomFix
FIGMA_API_KEY is not setAdd it to the client's env block, or to .env (section 3 / 5). Run --check.
403 / token invalidToken expired, revoked or wrong: generate a new one.
404 on a nodeNo access to the file, or wrong node-id.
Invalid Figma file keyUse the key from the file URL: figma.com/design/<fileKey>/...
verify_render: Chromium not installednpx playwright install chromium, or set FIGMA_PROXY_CHROME_PATH.
--check: cannot reach api.figma.comNetwork/firewall. Behind an HTTP proxy, Node 22.21+/24 needs NODE_USE_ENV_PROXY=1 with HTTPS_PROXY set.
EADDRINUSE :4444HTTP mode already running, or set FIGMA_PROXY_PORT.

Development

npm test     # offline smoke tests: stdio + HTTP JSON-RPC, doctor, image diff

scripts/capture.js and scripts/inspect-ir.js are dev-only helpers (not in the npm package): they save a raw Figma response to ./fixtures/ and print IR statistics for it.

Security

See SECURITY.md. Changes: CHANGELOG.md.

License

MIT

Frequently asked questions

What is Figma Proxy MCP?

Figma → code: tokenized IR, PNG renders and SSIM/pixel visual diff to verify builds.

How do I install Figma Proxy MCP?

It runs on your machine. In Claude Code: claude mcp add figma-proxy-mcp -e 'FIGMA_API_KEY=<your figma_api_key>' -- npx -y figma-proxy-mcp@1.1.1 --stdio. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Figma Proxy MCP need an API key?

Yes. It expects FIGMA_API_KEY, which you set in its configuration.

Is Figma Proxy MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Figma Proxy MCP?

It is published by Semmargl. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.