io.github.oabolade/figma_mcp_server_actor

Official

by oabolade · JavaScript

Figma MCP Server

MCP server enabling AI assistants to interact with Figma designs via natural language commands

Interact with Figma designs using natural language commands.

README.md8 KBView on GitHub

Figma MCP Server (Apify Actor)

Model 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 platform (standby / container URL) or locally via apify run.

Features

File analysis — structure, metadata, styles, depth-limited trees
Components — list, details, usage
Assets — export nodes (PNG, SVG, PDF, JPG)
Comments — read and create
Projects / teams — listings and metadata
MCP resources & prompts for guided workflows

Authentication

Personal Access Token (default)

Recommended for solo use. Set figmaAccessToken in Actor input (or FIGMA_ACCESS_TOKEN in env).

Generate: Figma → Settings → Security → Personal access tokens
API header: X-Figma-Token
When PAT is set, OAuth is disabled for API calls (and /oauth/* routes return an error).

OAuth 2.0 (optional — team / shared files)

Use when you omit figmaAccessToken and provide a Figma OAuth app:

Input	Purpose
`oauthClientId`	From Figma → Developers → Apps
`oauthClientSecret`	Same app
`oauthRedirectUri`	Exact redirect URL registered on the app, e.g. `https://<your-run>.runs.apify.net/oauth/callback`
`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`.

Flow

Start the Actor with OAuth fields filled and no PAT.
Open GET https://<container-url>/oauth/authorize in a browser (normal browser — not an embedded WebView; Figma requirement).
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.

Token exchange uses Figma’s documented endpoints (https://api.figma.com/v1/oauth/token and .../oauth/refresh). Codes expire quickly — complete the redirect promptly.

Requirements

Node.js ≥ 20
Apify account (for cloud)
Figma PAT and/or OAuth app

Quick start (Apify Cloud)

bash

npm install
apify login
apify push

In Apify Console, 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.

Deploy reference: apify push builds and publishes; see Apify CLI.

Configuration (input)

Parameter	Type	Default	Description
`figmaAccessToken`	string	—	PAT (recommended). If set, used for all Figma API calls.
`port`	integer	`8080`	HTTP listen port (Apify may override via `web_server_port`).
`oauthClientId`	string	—	OAuth app client ID (only if not using PAT).
`oauthClientSecret`	string	—	OAuth app secret (secret input).
`oauthRedirectUri`	string	—	Must match Figma app redirect URI exactly.
`oauthScopes`	string	—	Optional scope override (comma-separated).
`maxConcurrentRequests`	integer	`10`	Reserved / future use.
`enableCaching`	boolean	`true`	Cache GET responses from Figma.

Local / CLI input file example (apify run):

json

{
  "figmaAccessToken": "figd_...",
  "port": 8080
}

HTTP API

Method	Path	Description
`GET`	`/`	Service info and endpoint list
`GET`	`/health`	Liveness; includes `auth_mode`: `pat` \| `oauth` \| `pending_oauth`, `figma_authenticated`
`POST`	`/mcp`	MCP JSON-RPC 2.0 (primary transport for this server)
`GET`	`/oauth/authorize`	Start OAuth (browser); disabled if PAT is set
`GET`	`/oauth/callback`	OAuth redirect handler

Apify MCP path: .actor/actor.json sets webServerMcpPath to /mcp. Your MCP client URL is typically:

https://<container-id>.runs.apify.net/mcp

(Use the Container URL from the run page + /mcp.)

Cursor IDE

Deploy and start the Actor; copy the run Container URL (while status is RUNNING).
Edit ~/.cursor/mcp.json (paths differ on Windows/Linux — see Cursor docs).

Example (remote HTTP MCP — adjust to your Cursor version’s expected shape):

json

{
  "mcpServers": {
    "figma-mcp-standby": {
      "url": "https://YOUR_RUN_ID.runs.apify.net/mcp"
    }
  }
}

Notes

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.
Container URLs are per run and stop working when the run ends; update mcp.json and restart Cursor after a new run.
If connection fails, use Cursor → Output → MCP and curl https://.../health.

Claude Desktop / other clients

Use 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.

Local development

bash

npm install
apify run

Or run the entry with Node if you inject env / input yourself:

bash

export FIGMA_ACCESS_TOKEN="figd_..."
node src/main.js

Check health (port from logs or input):

bash

curl -s http://localhost:8080/health | jq .

Sample MCP initialize:

bash

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Project structure

code

figma_mcp_actor/
├── .actor/
│   ├── actor.json           # Apify Actor metadata (incl. webServerMcpPath: /mcp)
│   ├── input_schema.json
│   ├── output_schema.json
│   └── dataset_schema.json
├── src/
│   ├── main.js              # Express app, /mcp, /oauth/*, Apify bootstrap
│   ├── figma/
│   │   ├── auth.js          # PAT + OAuth token exchange, refresh, KV hook
│   │   └── client.js        # Figma REST wrapper
│   ├── oauth/
│   │   └── persist.js       # Apify KV: FIGMA_OAUTH_SESSION
│   ├── mcp/                 # Protocol, handlers, server
│   ├── tools/
│   ├── resources/
│   └── prompts/
├── Dockerfile
├── package.json
└── README.md

MCP tools (overview)

Includes (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.

Limitations

REST vs Plugin API — deep design writes may need the Plugin API; this Actor uses REST where supported.
Ephemeral Apify URLs — each run has a new base URL unless you use a stable hosting pattern.
OAuth — single stored session per run (KV); not multi-user concurrent OAuth in one process.

Scripts

bash

npm run lint
npm run lint:fix
npm run format

License

ISC

Changelog

0.2

Optional OAuth 2.0 (Figma authorization code + refresh); PAT remains default when set.
/oauth/authorize and /oauth/callback; session persisted in default KV (FIGMA_OAUTH_SESSION).
Input: oauthRedirectUri, oauthScopes.
Health JSON: auth_mode, figma_authenticated.

0.1 / 0.0.1

Initial MCP + Figma REST integration, PAT, long-running server, /mcp JSON-RPC.

References: Apify Actors · Figma REST API · Model Context Protocol

Install

Configuration

Environment variables

FIGMA_ACCESS_TOKENrequiredsecret

Figma Personal Access Token for API authentication. Get yours at https://www.figma.com/developers/api#access-tokens

claude_desktop_config.json

{
  "mcpServers": {
    "figma_mcp_server_actor": {
      "command": "npx",
      "args": [
        "-y",
        "@oabolade-pegasus/figma-mcp-server@2.1.0"
      ],
      "env": {
        "FIGMA_ACCESS_TOKEN": "<YOUR_FIGMA_ACCESS_TOKEN>"
      }
    }
  }
}