# 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','<YOUR_FIGMA_TOKEN>','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.