Figma MCP

Figma MCP is a local FastMCP 3 server that converts a selected Figma Design Frame, Component, or Instance into an inspectable packet and a static Unity UGUI Direct YAML Prefab.

The project is intentionally small and independent. It uses the Figma REST API, stores rendered PNGs locally, and does not require a Figma plugin, OAuth flow, or Unity Editor extension.

中文文档：README.zh-CN.md

Requirements

• Python 3.10+

• uv (recommended) or another Python environment manager

• A Figma personal access token with file_content:read

• Unity 2022.3 LTS or Unity 6 LTS for generated output

Related MCP server: Figma MCP Server

Install

uv sync --extra dev
cp .env.example .env

Set the token only in your local .env:

FIGMA_TOKEN=figd_your_token_here

The token is used only in X-Figma-Token headers sent to https://api.figma.com. Render downloads use a separate unauthenticated HTTP client. The token is not stored in packets, generated assets, source maps, or error details.

Run

Loopback HTTP (default):

uv run figma-mcp

The endpoint is http://127.0.0.1:8127/mcp. Non-loopback HTTP binding is rejected.

stdio:

./run-stdio.sh

or:

MCP_TRANSPORT=stdio uv run figma-mcp

Tools

Example flow:

1. Call figma_list_frames with a Figma Design URL or file key.

2. Call figma_prepare_design with a node id, exact/unique partial name, or 1-based list index. A URL node-id takes precedence.

3. Inspect view="unity_plan" and review warnings.

4. Call figma_generate_unity_prefab with an absolute Unity project path.

5. Call figma_verify_unity_prefab, then open the project in Unity for actual import, compile, and visual validation.

Cache behavior

Successful active Packets use a stable key derived from the Figma file key, node id, image scale, and semantic ruleset. They persist across server restarts. force_refresh=true is the only normal way to bypass a complete cache.

Refreshes download into a temporary staging directory. A complete refresh writes an immutable asset version and atomically replaces the active Packet pointer. If any render is missing or fails, the previous active Packet is preserved and a separate diagnostic Packet is saved with generation_ready=false.

Figma render URLs are never treated as cache entries. Every rendered PNG is downloaded immediately and stored with its SHA-256 hash.

Figma-to-Unity rules

• Figma child order is preserved. Increasing z_index is bottom-to-top and Unity creates same-parent nodes in ascending order.

• Coordinates are rebased to the selected root and use a top-left origin.

• Standard constraints map to RectTransform anchors.

• horizontal/vertical Auto Layout maps to LayoutGroup and LayoutElement hints. Wrap/grid combinations retain snapshot coordinates and emit warnings.

• Editable text becomes UnityEngine.UI.Text; unmatched fonts fall back to built-in Arial with a warning.

• Simple solid rectangles become UGUI Images. Vector, image fill, gradient, rounded, stroked, or effect-heavy visual leaves become PNG sprites.

• Complex containers remain hierarchical. Rectangular clipsContent maps to RectMask2D where safe; unsupported container visuals emit fidelity warnings.

Interactive generation defaults to conservative: confidence must be at least 0.8, review must not be required, and all references must be complete. structure_only suppresses inferred Button/Toggle/Input/Dropdown/Slider/ ScrollRect components while retaining presentation hierarchy and safe layout or mask components.

Explicit name tags include @button, @toggle, @input, @dropdown, @slider, @scroll, @scrollbar, @tab, @radio, @mask, and @ignore. They never create business scripts, UnityEvent bindings, navigation, or data bindings.

Unity ownership policy

The default output root is Assets/FigmaMCP. Generation uses staging, static pre-verification, deterministic GUIDs, a source map, and an ownership manifest.

overwrite=false is the default. With overwrite=true, only files already owned by the same Packet manifest can be replaced. Historical orphaned files are reported but not deleted. A failed commit rolls back files changed during that transaction.

Contracts

All responses use api_version: "0.1" and a success/error envelope. Public schemas are version 1:

• figma-mcp.packet

• figma-mcp.unity-plan

• figma-mcp.prefab-source-map

• figma-mcp.ownership-manifest

Generated JSON Schemas are in schemas/.

Development

uv run pytest
uv run pytest --cov=figma_mcp --cov-report=term-missing
uv run ruff check src tests
uv run mypy src
uv build

The test suite is offline: it mocks Figma REST and creates temporary Unity project structures. Passing tests prove the contracts, generated files, and static checks; they do not prove compatibility with every real Figma document, Unity Editor import/compilation, or visual parity.

Scope exclusions

Version 0.1.0 does not implement OAuth, Figma variables, FigJam/Slides, plugin templates, real Unity Prefab Instances/Variants, C# importers, visual diff, or a publishing pipeline.

License

MIT