# Figma API Integration

**Last Updated:** 2026-02-04

This document describes how to configure and use the Figma REST API in this project via a personal access token, and how to integrate Figma with Cursor via MCP (recommended: official Figma MCP, no token in project).

**Token and one-time setup:** The token is set once by you (environment or config file) so that scripts and optionally an MCP server can read it at runtime. The AI does not store or persist the token; tools read it from env/config when needed.

## Cursor MCP integration (recommended for chat)

For implementing designs from Figma links directly in Cursor chat, use an MCP server. Two options below; the **official Figma MCP** is the simplest (no token, OAuth once).

---

### How to install: Official Figma MCP (recommended, no token)

1. **Open the install link in Cursor.**

   - **Option A:** Go to [Figma MCP – Remote server installation](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/), scroll to the **Cursor** section, and click the **“Figma MCP server deep link”** there. That should open Cursor and show the MCP install screen.
   - **Option B:** Paste this URL into your browser’s address bar and press Enter; when prompted, choose to open Cursor:  
     `cursor://anysphere.cursor-deeplink/mcp/install?name=Figma&config=eyJ1cmwiOiJodHRwczovL21jcC5maWdtYS5jb20vbWNwIn0=`
   - **Option C (manual):** In Cursor go to **Settings → MCP** (or **Cursor Settings → Features → MCP**), add a new server with **URL** `https://mcp.figma.com/mcp` and **Type** `http`, then start the server.

2. **Install the server.**  
   In the MCP configuration screen that opens, click **Install** under “Install MCP Server?”.

3. **Connect to Figma.**  
   Click **Connect** next to “Figma” to start Figma’s OAuth flow.

4. **Sign in and allow access.**  
   When the browser opens, sign in to Figma if needed, then click **Allow access** (or **Open** then **Allow access**).

5. **Use it in chat.**  
   Paste a Figma file, frame, or layer link in a Cursor chat and ask to implement the design. The AI will use the MCP to read design context (no token to store).

**Reference:** [Figma – Remote server installation (Cursor section)](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/).

---

### How to install: Community figma-developer-mcp (token-based)

If you prefer a token-based MCP (e.g. same token as your scripts):

1. **Open Cursor MCP settings.**  
   **Cursor menu → Settings** (or **Cmd+,**), then open **MCP** (or **Features → MCP**). If you see “Edit Config” or “Open MCP configuration”, use that to open the JSON file where MCP servers are listed.

2. **Add the figma-developer-mcp server.**  
   In the `mcpServers` section, add an entry like this (use your real token only locally; **do not commit** this file with the token):

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

   Replace `YOUR_FIGMA_TOKEN_HERE` with your Figma personal access token (same value as `FIGMA_ACCESS_TOKEN` for scripts). Save the config.

3. **Restart or enable the server.**  
   Restart Cursor if needed, or in MCP settings click **Start** / enable the “figma-developer-mcp” server.

4. **Use it in chat.**  
   Paste a Figma link in chat and ask to implement; the AI will use this MCP. Keep the token secret and revoke it in Figma if it is ever exposed.

**Example (placeholder only):** `.cursor/mcp.json.example` in this repo shows the structure; never commit the real token.

---

**Recommendation:** Prefer the **official Figma MCP** (first section): no token, one-time OAuth, paste link → implement. Use the community server only if you want a single token for both Cursor and your CLI scripts.

---

### Verify the Figma MCP is working

1. **Check it’s enabled:** In Cursor go to **Settings → MCP** (or **Features → MCP**). You should see **Figma** in the list and it should be connected/started (no red or warning state).
2. **Quick test:** In a Cursor chat, paste a **Figma file, frame, or layer link** (e.g. from the browser address bar when you have a frame selected in Figma). Then ask: _"Implement this design as HTML/CSS"_ or _"Generate React components from this Figma frame."_ The AI should use the Figma MCP to fetch design context and generate code. If it works, the MCP is working.
3. **Remote server (official):** You must paste a **link**; selection-based prompting only works with the Figma desktop app. The link should include the file and optionally `?node-id=...` for a specific frame/layer.

**If tools don’t load or you get errors:** See Figma’s troubleshooting (e.g. [tools not loading](https://developers.figma.com/docs/figma-mcp-server/tools-not-loading), [getting 500 error](https://developers.figma.com/docs/figma-mcp-server/getting-500-error)). Ensure you clicked **Connect** and completed OAuth; try disconnecting and reconnecting Figma in MCP settings.

---

### What the Figma MCP can do (official server)

Once connected, the AI can use these tools when you paste a Figma link:

- **get_design_context** — Layout and styling for a frame/layer (for implementing UI).
- **get_metadata** — IDs, names, types, position, sizes (sparse structure).
- **get_variable_defs** — Variables and styles (colors, spacing, typography).
- **get_screenshot** — Screenshot of the selection (helps layout fidelity).

**Tips:** Be specific in your prompt (e.g. “using our Tailwind components”, “in `v2/components/...`”). The more you specify framework, file path, and existing components, the better the output. See [Figma – Write effective prompts](https://developers.figma.com/docs/figma-mcp-server/write-effective-prompts).

## Generating a token

1. Log in to [Figma](https://www.figma.com).
2. Open **Settings** (account menu → Settings).
3. Go to the **Security** tab.
4. Under **Personal access tokens**, click **Generate new token**.
5. Set expiration and **scopes**. Required: **`file_content:read`** (for files, nodes, and content). Optional: **`file_metadata:read`** (for file metadata).
6. Click **Generate token**. Copy the token immediately; Figma shows it only once.

Manage tokens: [Figma Settings → Security](https://www.figma.com/settings) (Personal access tokens).

## Setting the token

**Never commit the token.** Use one of these methods:

### Option 1: Environment variable (recommended for scripts)

```bash
export FIGMA_ACCESS_TOKEN=figd_...
```

Add to your shell profile (e.g. `~/.zshrc`) or to a local env file that is **not** committed.

### Option 2: Config file (PHP)

1. Copy the example: `cp v2/config/figma-api-key.php.example v2/config/figma-api-key.php`
2. Edit `v2/config/figma-api-key.php` and set `'access_token' => 'figd_...'`

The file `v2/config/figma-api-key.php` is in `.gitignore` and must not be committed.

**Priority:** If `FIGMA_ACCESS_TOKEN` is set in the environment, it overrides the config file.

## Security

- Do **not** commit the token or paste it in logs, docs, or chat.
- **If the token was ever pasted in chat or committed:** Treat it as exposed. Revoke it in Figma (Settings → Security → Personal access tokens) and generate a new token; then set only the new token in env or config. Do not paste the new token in chat.
- Use **granular scopes**: at minimum `file_content:read`; avoid deprecated `files:read`.

## Getting file key and node ID from a Figma URL

- **File key:** From any Figma file URL: `https://www.figma.com/.../FILE_KEY/...` — the long alphanumeric segment before the file name.
- **Node ID:** From the URL when a node is selected: `?node-id=53851-1051`. In the API, use `53851:1051` (colon). For multiple nodes, use comma-separated IDs.

## Usage

### Verify token

```bash
export FIGMA_ACCESS_TOKEN=figd_...
# Optional: use a real file key to confirm file access
export FIGMA_TEST_FILE_KEY=your_file_key
python3 v2/scripts/nano-ai/verify-figma-token.py
```

Exit 0 = token valid (or file not found but token accepted). Exit 1 = token missing or invalid.

### Fetch file or nodes JSON

```bash
export FIGMA_ACCESS_TOKEN=figd_...
python3 v2/scripts/nano-ai/fetch-figma-file.py <file_key>
python3 v2/scripts/nano-ai/fetch-figma-file.py <file_key> --ids "53851:1051,53851:1052" -o output.json
python3 v2/scripts/nano-ai/fetch-figma-file.py --help
```

### Extract design tokens from Figma API

When `FIGMA_ACCESS_TOKEN` and `FIGMA_FILE_KEY` are set, the extract script uses the API first; otherwise it uses screenshots.

```bash
export FIGMA_ACCESS_TOKEN=figd_...
export FIGMA_FILE_KEY=your_file_key
# Optional: limit to specific nodes
export FIGMA_NODE_IDS=53851:1051,53851:1052
python3 v2/scripts/nano-ai/extract-figma-design-tokens.py
```

Output: `docs/data/nano-figma-design-tokens.json` (colors and dimensions from node JSON).

## PHP usage

Include the config and use the helper:

```php
require_once __DIR__ . '/v2/config/figma-config.php';
$token = figma_access_token();
if ($token !== '') {
    // Use header: X-Figma-Token: $token
    // Base URL: FIGMA_API_BASE_URL (https://api.figma.com/v1)
}
```

## API reference

- **Authentication:** [Figma REST API – Authentication](https://developers.figma.com/docs/rest-api/authentication/) (personal token in `X-Figma-Token` header).
- **File endpoints:** [Figma REST API – File endpoints](https://developers.figma.com/docs/rest-api/file-endpoints/) (`GET /v1/files/:key`, `GET /v1/files/:key/nodes`).
- **Scopes:** [Figma REST API – Scopes](https://developers.figma.com/docs/rest-api/scopes/).

## Rate limits

File and node endpoints are **Tier 1**. Respect rate limits; cache file JSON when possible to avoid repeated calls.