figma2mobile-local

A local MCP server + Figma plugin that lets an AI agent read, edit, and export mobile UI directly on the Figma canvas. Import a frame → intermediate representation (IR) → edit → render back into Figma → export Android/iOS assets.

• Default transport: local (127.0.0.1) between the server and the Figma plugin.
• Optional fallback: read-only Figma REST API, only if you set FIGMA_TOKEN.
• Clients: Claude Code, Cursor, Codex CLI (auto-config), plus Claude Desktop (manual config).

One command, every OS. Works identically on Windows, macOS, and Linux. Requires Node.js ≥ 18 and Figma Desktop (the Figma web app cannot reach localhost).

Quick start

npx -y figma2mobile-local@latest install-plugin ./figma2mobile-local

This single command:

1. Unpacks the Figma plugin + the implementation skill into ./figma2mobile-local.
2. Registers the MCP server into the agent(s) you pick.
3. Prints the exact manifest.json path you import into Figma, plus manual config for every agent.

Note: install-plugin modifies the selected MCP client's local configuration files (~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml). Any existing file is backed up (.bak-<timestamp>) before it is changed. Re-running is idempotent — no duplicate entries.

Roughly what it prints:

✓ Plugin + skill extracted → ./figma2mobile-local
✓ MCP registered: Claude Code → ~/.claude.json (backup: ~/.claude.json.bak-...)
✓ Import this manifest into Figma Desktop:
    /abs/path/figma2mobile-local/plugin/manifest.json

Next: restart your MCP client, then import the manifest into Figma Desktop.

Then do the two manual steps it prints: restart your agent, and import the plugin into Figma Desktop.

Features

• Read — import frames/nodes into a compact IR (ui_import_source, ui_import_batch), inspect layout and structure (ui_read_layout, ui_read_ir, ui_read_raw, ui_get_node, ui_search_ir, ui_read_snapshot).
• Edit & write back — mutate the IR and render it onto the real canvas (ui_update_ir, ui_render_to_figma), validate structure before writing (ui_validate), diff two IRs (ui_diff_ir), trace a node's lineage (ui_trace).
• Export assets — PNG / Android VectorDrawable / PDF for Android & iOS (ui_export_assets), plus reference images for visual checks (ui_export_reference_image).
• Visual verification — capture a running device screen and compare it against the design (ui_capture_device_screen, ui_compare_images) to prove the built app matches Figma.
• Design tokens — extract and report colors/spacing/radii usage (ui_token_report).
• Observability — a local dashboard (opens automatically) plus ui_metrics, ui_cache_status, ui_cache_clear for token savings, cache hit/miss, and Figma API usage.
• Self-documenting — call ui_docs for the full tool reference and decision matrix.
• Status first — always call ui_status to see connection, session, and write permission.

All tools are prefixed ui_ (23 available in this release). Run ui_docs for the authoritative, always-current list.

Installation (3 steps, any OS)

Step 1 — Install Node.js ≥ 18 (if needed)

Check with node -v. If it is missing or below 18:

| OS | How to install | |---|---| | Windows | Download the LTS installer from https://nodejs.org and run the .msi, or winget install OpenJS.NodeJS.LTS | | macOS | Download the LTS installer from https://nodejs.org, or brew install node | | Linux | sudo apt install nodejs npm (Debian/Ubuntu), or via nvm: nvm install --lts |

Step 2 — Unpack the plugin & register the MCP server

# Windows (PowerShell / CMD), macOS, Linux — identical
npx -y figma2mobile-local@latest install-plugin ./figma2mobile-local

Run in an interactive terminal and it shows an agent picker (exactly one prompt):

Chon agent de dang ky MCP (tu ghi config, co backup):
  1. Claude Code
  2. Cursor
  3. Codex CLI
  a. Tat ca
Nhap so (vd 1,3 hoac 'a', Enter = tat ca):

After you choose, it merges the MCP config into each agent's own file (creating a .bak-<timestamp> backup if the file already exists), copies the skill, then prints the manual config and the Figma import path.

No prompt (CI / scripting) — pass flags:

npx -y figma2mobile-local@latest install-plugin --agent claude,cursor,codex ./figma2mobile-local

Auto-registrable agents: claude, cursor, codex. Re-running is idempotent (already-present entries are updated or left untouched, never duplicated).

Step 3 — Import the plugin into Figma Desktop

The command from Step 2 prints the absolute path to manifest.json — use it here:

1. Open Figma Desktop (not Figma web — web cannot reach localhost).
2. Menu → Plugins → Development → Import plugin from manifest…
3. Select figma2mobile-local/plugin/manifest.json (the exact path was printed by Step 2).
4. Run Plugins → Development → Figma2Mobile Local.
5. Restart your MCP client so it loads the new server → the agent now sees the ui_* tools.

Done. Select a frame in Figma and ask the agent to "import this frame".

Manual installation (any agent, or to double-check)

The install-plugin command always prints this, but here it is for reference. The MCP entry differs on Windows (see the note below).

Auto-registered by the installer: Claude Code, Cursor, Codex CLI. Manual only: Claude Desktop (paste the JSON below into its config file — see the table).

macOS / Linux — MCP config JSON

For Claude Code, Cursor, and Claude Desktop:

{
  "mcpServers": {
    "figma2mobile-local": {
      "command": "npx",
      "args": ["-y", "figma2mobile-local"]
    }
  }
}

Windows — MCP config JSON

On Windows, npx resolves to npx.cmd, which many MCP clients cannot spawn without a shell. Wrap it with cmd /c:

{
  "mcpServers": {
    "figma2mobile-local": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "figma2mobile-local"]
    }
  }
}

The install-plugin command detects Windows and writes this variant automatically.

Codex CLI — TOML (~/.codex/config.toml)

# macOS / Linux
[mcp_servers.figma2mobile-local]
command = "npx"
args = ["-y", "figma2mobile-local"]

# Windows
[mcp_servers.figma2mobile-local]
command = "cmd"
args = ["/c", "npx", "-y", "figma2mobile-local"]

Config file locations per agent

| Agent | Config file | Notes | |---|---|---| | Claude Code | ~/.claude.json (mcpServers) | or claude mcp add figma2mobile-local -- npx -y figma2mobile-local | | Cursor | ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project) | JSON mcpServers | | Codex CLI | ~/.codex/config.toml | [mcp_servers.figma2mobile-local] block | | Claude Desktop | Win %APPDATA%\Claude\claude_desktop_config.json · macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Linux ~/.config/Claude/claude_desktop_config.json | JSON mcpServers |

Running with npm / npx

As an end user

# Run once, no global install (recommended — always current):
npx -y figma2mobile-local@latest

# Or install globally:
npm install -g figma2mobile-local@latest
figma2mobile-local install-plugin ./figma2mobile-local   # CLI name is unscoped

Interactive / everyday use: @latest (a stale npx cache won't have the newest tools or skill). CI / reproducible environments: pin an exact version instead, e.g. npx -y [email protected].

Subcommands

| Command | What it does | |---|---| | figma2mobile-local | Boot the MCP server on stdio (this is what your agent runs). | | figma2mobile-local install-plugin [dir] | Unpack plugin + skill into dir (default ./figma2mobile-local) and register agents. | | install-plugin --agent claude,cursor,codex | Register specific agents without the interactive menu. | | install-plugin --yes | Non-interactive: unpack only, does not modify any agent config. |

How to use it

Inside your MCP client:

1. ui_status — check plugin connection, active session, and write permission.
2. Select a frame in Figma → ui_import_source (or ui_import_batch for several frames).
3. ui_read_layout / ui_read_ir — read the UI structure.
4. Edit via ui_update_ir → ui_render_to_figma — write changes back to the canvas.
5. ui_export_assets — export PNG / VectorDrawable / PDF for Android & iOS.

Call ui_docs for the full tool reference. The observability dashboard (token savings, cache, Figma API calls) opens automatically when the server runs.

Optional: Figma API token

If you cannot open the plugin, the server can read (read-only) through the Figma REST API — this needs a token. Paste it into the "Figma API token" panel on the dashboard, or export FIGMA_TOKEN. The live plugin is always the preferred source and the only write path.

Privacy & network model

Local-first. By default the server communicates with the Figma plugin over 127.0.0.1; no design data is sent to third-party servers by the local bridge. Design data leaves the machine only if you explicitly set FIGMA_TOKEN, in which case read-only requests may be sent to Figma's REST API.

| Path | Default | |---|---| | Server ↔ Figma plugin | local bridge on 127.0.0.1 | | Plugin write-back (render, export) | local bridge only | | Figma REST API | disabled unless FIGMA_TOKEN is set — read-only | | Remote MCP endpoint | not required | | Agent config files | backed up before the installer modifies them |

Distribution

The published npm package is a production distribution: it ships a protected runtime build and the compiled Figma plugin, and does not include the original project source. This raises the cost of casual inspection and redistribution — it is not cryptographic secrecy, since client-side code must ultimately run on the user's machine.

Troubleshooting

| Symptom | Fix | |---|---| | node: command not found | Node is not installed — see Step 1. | | Agent does not see the ui_* tools | Fully restart the MCP client (not just reconnect). | | On Windows the server never starts / spawn error | Use the cmd /c MCP entry (Windows section above). install-plugin writes it automatically. | | ui_status reports plugin_not_open | Open Figma Desktop and run the plugin (Step 3). | | BRIDGE_UNAVAILABLE | Transient — call again once; if it persists, fully quit and reopen the MCP client. | | First run is slow | First run does a one-time setup; subsequent runs start instantly. |

License

UNLICENSED — proprietary. This software is not open source, and no license is granted to copy, modify, redistribute, or create derivative works from it. By installing and using it, you agree to these terms. You are welcome to trust the package as-is, or to freely inspect it for malware — either is fine.

Node ≥ 18. Build: fba3a8d-20260802112357