# Figma MCP — token-based connection (headless, works from Claude Code + Cursor)

A **token-in-a-file / env** setup so the design reads the same whether you run from **Claude Code** or **Cursor**,
without repeating an OAuth flow. Uses the community **Framelink** server (`figma-developer-mcp`), which reads a
Figma **Personal Access Token** and talks to the Figma REST API — headless, no desktop app needed.

> The **official** Figma server (`https://mcp.figma.com/mcp`) is **OAuth-only** — no token-in-a-file. Use it if you
> want the official Dev Mode code context; use **this** (Framelink) when you want a token-based, portable setup.

---



## 1) One-time — generate a Figma token

Figma → **Settings → Security → Personal access tokens → Generate** (scope: **File content = Read**).
Copy it. **You keep it — never commit it, never paste it into a tracked file.**

## 2) Put the token in ONE place — an env var (recommended)

Set it once (machine-wide); every tool inherits it. Windows (PowerShell):

```powershell
[Environment]::SetEnvironmentVariable('FIGMA_API_KEY','figd_bk_0vtAbmChpF57q26VQJrKE9dMnaXtDRaSgJQ5F','User')
```

Then **restart** Cursor / the terminal so the new env var is picked up.

## 3) Wire it into both tools



### Claude Code

This repo ships a committed template — `[.mcp.json](../.mcp.json)` — with **no token** (it inherits `FIGMA_API_KEY`
from the env). Claude Code auto-loads it (approve the trust prompt). For a global (all-projects) install instead:

```bash
claude mcp add --scope user --env FIGMA_API_KEY=<YOUR_TOKEN> figma-token -- npx -y figma-developer-mcp --stdio
```



### Cursor

Global config `~/.cursor/mcp.json` (private — already holds your other tokens; **keep it out of git**):

```json
{
  "mcpServers": {
    "figma-token": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": { "FIGMA_API_KEY": "PUT_YOUR_FIGMA_TOKEN_HERE" }
    }
  }
}
```

Replace `PUT_YOUR_FIGMA_TOKEN_HERE` with your real token (this private file already stores literal secrets, so a
literal token here is fine), **or** delete the `env` block to inherit `FIGMA_API_KEY` from step 2. Restart Cursor.

## 4) Verify

Ask the assistant to read a node, e.g. `get_figma_data` / the design tools with a file URL
(`https://www.figma.com/design/<fileKey>/...?node-id=<id>`). It should return the screen structure + images with
no auth prompt.

---



## Reading tips (already enforced in `build/build-schema.md` §1)

- `get_metadata` on a big node can be **huge** (overflows) — list pages first, drill into specific frames.
- **Prefer screenshots** for reading Arabic labels at breadth — cheaper and clearer, especially for files that were
**imported from HTML** (noisy `DIV`/`INPUT` trees).



## Security

- **Never commit the token.** Keep it in the `FIGMA_API_KEY` env var, or in the **private, gitignored** tool config
(`~/.cursor/mcp.json`, Claude user config). The committed `[.mcp.json](../.mcp.json)` intentionally holds **no**
token — it only inherits the env var.