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

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

Tool	Purpose
figma_list_frames	List selectable Frames, Components, Instances, and Component Set variants, including those nested under Sections.
figma_prepare_design	Fetch one root, normalize it, batch-render PNG assets, and persist an active or diagnostic Packet.
figma_inspect_design	Inspect summary, full, tree, nodes, assets, slices, unity_profile, or unity_plan.
figma_generate_unity_prefab	Transactionally write and statically pre-verify a UGUI Direct YAML Prefab.
figma_verify_unity_prefab	Independently verify YAML, Sprite meta files, source map, ownership, fileIDs, and Unity version.

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, semantic ruleset, and an explicit version-id when one is requested. Frame listings and Packets for different explicit versions are kept in separate cache namespaces. 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.
• Hidden Figma nodes become inactive GameObjects. Group opacity uses one CanvasGroup; leaf opacity is applied once to its generated Graphic.
• Simple solid rectangles become UGUI Images. Vector, image fill, gradient, rounded, stroked, or effect-heavy visual leaves become PNG sprites.
• Rotated visual leaves and containers use rendered PNGs so rotation is baked accurately. A rotated container keeps its descendant hierarchy and source mapping, while descendant source visuals are suppressed to avoid duplication.
• 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 unchanged files already owned by the same Packet manifest can be replaced; every existing file is checked against its previous SHA-256. If an owned file was edited manually, generation returns owned_asset_modified. Set force_overwrite_modified=true together with overwrite=true only when those edits may be discarded. Direct YAML regeneration replaces complete owned files; field-level preservation hints describe a future editor-side importer, not the current writer. 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