{
  "markdown": "# Figma MCP Server (Apify Actor)\n\nModel Context Protocol (MCP) server that exposes **Figma REST API** capabilities to AI assistants (Cursor, Claude, custom agents). Runs as a **long-running web server** on the [Apify](https://apify.com) platform (standby / container URL) or locally via `apify run`.\n\n## Features\n\n- **File analysis** — structure, metadata, styles, depth-limited trees  \n- **Components** — list, details, usage  \n- **Assets** — export nodes (PNG, SVG, PDF, JPG)  \n- **Comments** — read and create  \n- **Projects / teams** — listings and metadata  \n- **MCP resources & prompts** for guided workflows  \n\n## Authentication\n\n### Personal Access Token (default)\n\nRecommended for solo use. Set **`figmaAccessToken`** in Actor input (or `FIGMA_ACCESS_TOKEN` in env).\n\n- Generate: [Figma → Settings → Security → Personal access tokens](https://www.figma.com/settings)  \n- API header: `X-Figma-Token`  \n- **When PAT is set, OAuth is disabled** for API calls (and `/oauth/*` routes return an error).\n\n### OAuth 2.0 (optional — team / shared files)\n\nUse when you **omit** `figmaAccessToken` and provide a Figma OAuth app:\n\n| Input | Purpose |\n|--------|---------|\n| `oauthClientId` | From [Figma → Developers → Apps](https://www.figma.com/developers/apps) |\n| `oauthClientSecret` | Same app |\n| `oauthRedirectUri` | **Exact** redirect URL registered on the app, e.g. `https://<your-run>.runs.apify.net/oauth/callback` |\n| `oauthScopes` | Optional; comma-separated scopes. Must be a subset of the app’s configured scopes. Defaults include `file_content:read`, `file_content:write`, `file_comments:read`, `file_comments:write`. |\n\n**Flow**\n\n1. Start the Actor with OAuth fields filled and **no** PAT.  \n2. Open **`GET https://<container-url>/oauth/authorize`** in a browser (normal browser — not an embedded WebView; [Figma requirement](https://developers.figma.com/docs/rest-api/authentication/)).  \n3. After consent, Figma redirects to **`/oauth/callback`**; tokens are stored in the run’s default **key-value store** (`FIGMA_OAUTH_SESSION`) and refreshed when near expiry.  \n\nToken exchange uses Figma’s documented endpoints (`https://api.figma.com/v1/oauth/token` and `.../oauth/refresh`). Codes expire quickly — complete the redirect promptly.\n\n## Requirements\n\n- **Node.js** ≥ 20  \n- **Apify account** (for cloud)  \n- **Figma** PAT and/or OAuth app  \n\n## Quick start (Apify Cloud)\n\n```bash\nnpm install\napify login\napify push\n```\n\nIn [Apify Console](https://console.apify.com), open the Actor, set input (at minimum `figmaAccessToken`), start with **web server / long-running** as required by your template, then use the **Container URL** from the run.\n\nDeploy reference: `apify push` builds and publishes; see [Apify CLI](https://docs.apify.com/cli).\n\n## Configuration (input)\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `figmaAccessToken` | string | — | **PAT (recommended).** If set, used for all Figma API calls. |\n| `port` | integer | `8080` | HTTP listen port (Apify may override via `web_server_port`). |\n| `oauthClientId` | string | — | OAuth app client ID (only if not using PAT). |\n| `oauthClientSecret` | string | — | OAuth app secret (secret input). |\n| `oauthRedirectUri` | string | — | Must match Figma app redirect URI exactly. |\n| `oauthScopes` | string | — | Optional scope override (comma-separated). |\n| `maxConcurrentRequests` | integer | `10` | Reserved / future use. |\n| `enableCaching` | boolean | `true` | Cache GET responses from Figma. |\n\nLocal / CLI input file example (`apify run`):\n\n```json\n{\n  \"figmaAccessToken\": \"figd_...\",\n  \"port\": 8080\n}\n```\n\n## HTTP API\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/` | Service info and endpoint list |\n| `GET` | `/health` | Liveness; includes `auth_mode`: `pat` \\| `oauth` \\| `pending_oauth`, `figma_authenticated` |\n| `POST` | `/mcp` | **MCP JSON-RPC 2.0** (primary transport for this server) |\n| `GET` | `/oauth/authorize` | Start OAuth (browser); disabled if PAT is set |\n| `GET` | `/oauth/callback` | OAuth redirect handler |\n\n**Apify MCP path:** `.actor/actor.json` sets `webServerMcpPath` to **`/mcp`**. Your MCP client URL is typically:\n\n`https://<container-id>.runs.apify.net/mcp`\n\n(Use the **Container URL** from the run page + `/mcp`.)\n\n## Cursor IDE\n\n1. Deploy and start the Actor; copy the run **Container URL** (while status is **RUNNING**).  \n2. Edit **`~/.cursor/mcp.json`** (paths differ on Windows/Linux — see Cursor docs).  \n\nExample (remote HTTP MCP — adjust to your Cursor version’s expected shape):\n\n```json\n{\n  \"mcpServers\": {\n    \"figma-mcp-standby\": {\n      \"url\": \"https://YOUR_RUN_ID.runs.apify.net/mcp\"\n    }\n  }\n}\n```\n\n**Notes**\n\n- **`env.APIFY_TOKEN`** in `mcp.json` is **not** passed to this Node process; it does not replace Figma auth. Use **`figmaAccessToken`** (or OAuth) in **Actor input**.  \n- Container URLs are **per run** and stop working when the run ends; update `mcp.json` and restart Cursor after a new run.  \n- If connection fails, use **Cursor → Output → MCP** and `curl https://.../health`.  \n\n## Claude Desktop / other clients\n\nUse your client’s supported way to attach a **remote MCP** URL (e.g. `mcp-remote` pointing at `https://.../mcp`). Paths and query params depend on the client version.\n\n## Local development\n\n```bash\nnpm install\napify run\n```\n\nOr run the entry with Node if you inject env / input yourself:\n\n```bash\nexport FIGMA_ACCESS_TOKEN=\"figd_...\"\nnode src/main.js\n```\n\nCheck health (port from logs or input):\n\n```bash\ncurl -s http://localhost:8080/health | jq .\n```\n\nSample MCP initialize:\n\n```bash\ncurl -s -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}'\n```\n\n## Project structure\n\n```\nfigma_mcp_actor/\n├── .actor/\n│   ├── actor.json           # Apify Actor metadata (incl. webServerMcpPath: /mcp)\n│   ├── input_schema.json\n│   ├── output_schema.json\n│   └── dataset_schema.json\n├── src/\n│   ├── main.js              # Express app, /mcp, /oauth/*, Apify bootstrap\n│   ├── figma/\n│   │   ├── auth.js          # PAT + OAuth token exchange, refresh, KV hook\n│   │   └── client.js        # Figma REST wrapper\n│   ├── oauth/\n│   │   └── persist.js       # Apify KV: FIGMA_OAUTH_SESSION\n│   ├── mcp/                 # Protocol, handlers, server\n│   ├── tools/\n│   ├── resources/\n│   └── prompts/\n├── Dockerfile\n├── package.json\n└── README.md\n```\n\n## MCP tools (overview)\n\nIncludes (names may vary slightly in code): file analysis (`analyze_file`, `get_file_structure`, …), components (`list_components`, …), export (`export_node`, …), comments (`get_comments`, `create_comment`, …), design modification helpers, plus **resources** (`figma://file/...`, etc.) and **prompts** for common tasks.\n\n## Limitations\n\n- **REST vs Plugin API** — deep design writes may need the Plugin API; this Actor uses REST where supported.  \n- **Ephemeral Apify URLs** — each run has a new base URL unless you use a stable hosting pattern.  \n- **OAuth** — single stored session per run (KV); not multi-user concurrent OAuth in one process.  \n\n## Scripts\n\n```bash\nnpm run lint\nnpm run lint:fix\nnpm run format\n```\n\n## License\n\nISC\n\n## Changelog\n\n### 0.2\n\n- Optional **OAuth 2.0** (Figma authorization code + refresh); **PAT remains default** when set.  \n- **`/oauth/authorize`** and **`/oauth/callback`**; session persisted in default KV (`FIGMA_OAUTH_SESSION`).  \n- Input: `oauthRedirectUri`, `oauthScopes`.  \n- Health JSON: `auth_mode`, `figma_authenticated`.  \n\n### 0.1 / 0.0.1\n\n- Initial MCP + Figma REST integration, PAT, long-running server, `/mcp` JSON-RPC.\n\n---\n\n**References:** [Apify Actors](https://docs.apify.com/platform/actors) · [Figma REST API](https://developers.figma.com/docs/rest-api/) · [Model Context Protocol](https://modelcontextprotocol.io)\n",
  "bytes": 7851,
  "sha": "59efb63f86bd28265da471d71b8f10b0216969d73d5fa94a9f1a713725936abc",
  "repo_slug": "oabolade/figma_mcp_server_actor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_oabolade_figma_mcp_server_acto_726345f7/readme"
}