# figma-mcp-proxy

A small, read-only MCP compatibility proxy for Figma's REST API. It is intended for MCP clients that cannot complete the official Figma remote MCP OAuth flow.

This is **not** the official Figma MCP server. It returns raw Figma REST API data and does not provide Figma's generated framework code, design-system search, or write-to-canvas tools.

## Requirements

- Node.js 18.18 or newer
- A Figma personal access token with the minimum read scopes needed for your files

Create a token in Figma account settings and keep it private. Each user supplies their own token; this project never contains or hosts tokens.

## Run with npx

Until the package is published to the npm registry, run the public GitHub package directly:

```text
npx --yes --package=github:dgehriger/figma-mcp-proxy -- figma-mcp-proxy
```

Set `FIGMA_ACCESS_TOKEN` in the environment used by your MCP client, then configure the server:

```json
{
  "mcpServers": {
    "figma": {
      "type": "local",
      "command": "npx",
      "args": [
        "--yes",
        "--package=github:dgehriger/figma-mcp-proxy",
        "--",
        "figma-mcp-proxy"
      ],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${env:FIGMA_ACCESS_TOKEN}"
      }
    }
  }
}
```

For GitHub Copilot Desktop, the file is `%USERPROFILE%\\.copilot\\mcp-config.json`. Set the token in the parent process environment before starting Copilot, or replace the environment reference with a locally managed secret mechanism supported by your installation. Do not commit the token to a config file.

## Available tools

- `get_design_context` — read a file or selected node from a Figma URL or file key
- `get_file` — read a file document
- `get_file_nodes` — read selected nodes
- `get_images` — request rendered image URLs
- `get_comments` — read file comments
- `get_current_user` — verify the configured token

## Agent guidance

The server sends a generalized Figma inspection workflow in the MCP
initialization instructions, so an agent does not need a separate Figma skill
to use this proxy correctly. The workflow teaches the agent to:

- request a direct design URL or file key and clarify the inspection goal;
- discover pages with shallow `get_file` calls before expanding a node tree;
- inspect targeted pages, sections, and frames with `get_file_nodes`;
- identify concrete `FRAME` nodes before requesting context or images;
- report node IDs, evidence, ordering, and access limitations; and
- avoid requesting credentials through chat.

Clients that support MCP prompts can invoke `figma_inspection_workflow` with a
goal and optional file URL or node ID. The same guidance is available as the
`figma://workflow/inspection` resource.

The guidance is intentionally generic. It does not assume a particular Figma
team, project naming scheme, browser session, or organization.

## Development

```text
npm install
npm test
npm run check
```

The package is intentionally read-only. The official Figma remote MCP server remains the better option when a client can complete its OAuth flow.