custom-figma-mcp

A lightweight local MCP (Model Context Protocol) server that gives AI coding agents (like OpenCode) structured, read-only access to Figma files — file hierarchies, node properties, and rendered images — without needing Figma's hosted/remote MCP integration.

Figma's official remote MCP server is gated behind an allowlisted Client ID, which isn't practical for individual developers wiring up their own agent tooling. This project sidesteps that by talking directly to Figma's public REST API using a personal access token, exposed to the agent through a standard MCP tool interface over stdio.

How to let opencode know what figma page your working on

Open the figma page in your browser, copy the URL, give it to the opencode along with your prompt.

Related MCP server: figma-mcp

Why This Exists

Figma's official remote MCP server is gated behind an allowlisted Client ID, which isn't practical for individual developers wiring up their own agent tooling. This project sidesteps that by talking directly to Figma's public REST API using a personal access token, exposed to the agent through a standard MCP tool interface over stdio.

Architecture

OpenCode (MCP client)
      │  stdio (JSON-RPC)
      ▼
custom-figma-mcp (this server)
      │  HTTPS + X-Figma-Token
      ▼
Figma REST API (api.figma.com/v1)

The server is a single Node.js process that:

1. Starts up and registers itself over stdio using @modelcontextprotocol/sdk.

2. Advertises a fixed set of tools to the MCP client (OpenCode) via ListToolsRequestSchema.

3. Executes tool calls via CallToolRequestSchema, proxying them to Figma's REST API with your personal access token attached as a header.

4. Returns structured JSON (or image URLs) back to the calling agent.

Because it only ever uses GET requests with a read-scoped token, it cannot modify, comment on, or delete anything in Figma — it's strictly read-only by design.

Tools Exposed

get_figma_file_structure

Returns the page/frame hierarchy of a file, depth-limited to avoid dumping the entire node tree (which can be tens of thousands of nodes on large files).

Input:

{ "fileKey": "string", "depth": 2 }

Maps to: GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

Fetches full properties for specific node IDs — auto-layout config, padding/gap values, fills, strokes, typography, constraints, component properties, etc. This is the primary tool used for accurate code generation.

Input:

{ "fileKey": "string", "nodeIds": ["1:2", "104:15"] }

Maps to: GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

Renders a specific node as a PNG and returns a temporary signed URL, useful for visually cross-checking generated code against the design.

Input:

{ "fileKey": "string", "nodeId": "104:15", "scale": 2 }

Maps to: GET /v1/images/:fileKey?ids=104:15&scale=2

Why Three Separate Tools (Instead of One)

Figma files can be enormous — a single GET /files/:key call with no depth limit can return megabytes of deeply nested JSON, which blows through an LLM's context window instantly. Splitting the interface into three targeted tools lets the agent:

1. First get a lightweight outline (get_figma_file_structure) to identify relevant frames/nodes.

2. Drill into only the specific nodes it needs (get_figma_node_details).

3. Optionally render an image only when visual confirmation is needed (get_figma_node_image).

This mirrors how a human developer would inspect a design — skim first, then zoom in — rather than ingesting the entire file at once.

Authentication

Authentication uses a Figma Personal Access Token (PAT), scoped to file_content:read. The token is loaded from a local .env file (never hardcoded) and attached to every outbound request as the X-Figma-Token header. The token never leaves the local machine except in requests directly to api.figma.com.

Error Handling

All tool handlers are wrapped in try/catch. On failure (invalid file key, no access, rate limiting, etc.), the server returns an MCP-compliant error response:

{
  "content": [{ "type": "text", "text": "Figma API Error: <details>" }],
  "isError": true
}

This lets the calling agent see the actual failure reason instead of crashing silently.

Project Structure

custom-figma-mcp/
├── index.js        # server entrypoint — tool definitions + handlers
├── package.json    # dependencies, "type": "module" for ESM imports
├── .env            # local only — holds FIGMA_PAT, never committed
└── .gitignore

Local Development

Run the server directly for debugging (it communicates over stdio, so you won't see typical HTTP server logs):

node index.js

In practice, you don't run this manually — OpenCode spawns it as a subprocess based on the command defined in opencode.json.

Extending This Server

To add a new tool:

1. Add its schema to the tools array returned by ListToolsRequestSchema.

2. Add a matching if (name === "...") branch inside the CallToolRequestSchema handler.

3. Map it to the relevant Figma REST endpoint under figmaApi (an axios instance pre-configured with the base URL and auth header).

Keep new tools read-only and scoped — avoid dumping full unfiltered API responses where possible, to keep agent context usage low.