figmingo-mcp

Local-first Figma MCP server. Full read-side parity with the official Figma MCP on free Figma plans (Personal Access Token + public REST API — no seat quotas, no monthly caps), HTML 1:1 replica tooling with built-in three-gate acceptance, and write-to-canvas through a companion plugin bridge.

中文文档 →

Architecture

flowchart LR
    subgraph clients["AI clients"]
        A["Cursor · Claude Code · Claude Desktop<br/>VS Code · Kimi CLI · Codex"]
    end
    A -- "stdio / Streamable HTTP" --> B["figmingo-mcp<br/>local server"]
    B -- "REST + Personal Access Token" --> C[("Figma REST API<br/>(free plan OK)")]
    B <-- "WebSocket ws://127.0.0.1:39220" --> D["companion plugin<br/>(Figma desktop)"]
    D -- "Plugin API writes" --> E[("Your canvas")]
    B --- F[("disk cache<br/>docs 15 min · renders 30 days")]

    style B fill:#6e56cf,color:#fff
    style D fill:#0d9e6e,color:#fff

Everything runs on your machine: no relay servers, no accounts besides your own Figma PAT, no data leaves localhost except calls to api.figma.com.

Related MCP server: figma-mcp

Why figmingo?

Install

One command (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/wenym8/figmingo-mcp/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/wenym8/figmingo-mcp/main/scripts/install.ps1 | iex

The installer checks Node ≥ 18, installs the package, installs the Playwright Chromium browser (~170MB, one-time — required by the HTML render/extract/compare tools), writes MCP config into Cursor (~/.cursor/mcp.json), Claude Code (~/.claude.json), Claude Desktop, VS Code, Kimi CLI (~/.kimi/mcp.json), and Codex CLI (~/.codex/config.toml, TOML — only the [mcp_servers.figmingo] section is touched; the original is backed up to config.toml.figmingo-bak), copies the companion plugin (manifest + code.js + ui.html) to ~/.figmingo/plugin, and prints next steps. Re-running is idempotent and never wipes a previously configured Figma token.

After installing, run figmingo-mcp doctor to verify the whole environment (Node, Figma token validity, Chromium, plugin files + version drift, client config entries, bridge port) — every check prints a ✓/✗ with a fix hint, and the exit code is 0 only when all checks pass.

Manual setup (any client):

{
  "mcpServers": {
    "figmingo": {
      "command": "npx",
      "args": ["-y", "figmingo-mcp"],
      "env": { "FIGMA_API_KEY": "figd_..." }
    }
  }
}

• Kimi CLI — same JSON shape in ~/.kimi/mcp.json (merge into mcpServers).

• Codex CLI — TOML in ~/.codex/config.toml:

  [mcp_servers.figmingo]
  command = "figmingo-mcp"
  args = []
  
  [mcp_servers.figmingo.env]
  FIGMA_API_KEY = "figd_..."

  (omit the [mcp_servers.figmingo.env] table if you configure the token another way; use command = "npx", args = ["-y", "figmingo-mcp"] for a zero-install run)

Get a Personal Access Token: Figma → Settings → Security → Personal access tokens → Generate new token (read scopes are enough for the read tools).

Usage

figmingo-mcp                      # stdio transport (default, what AI clients use)
figmingo-mcp --http --port 3845   # Streamable HTTP at http://127.0.0.1:3845/mcp
figmingo-mcp cache-clear          # wipe ~/.figmingo/cache
figmingo-mcp --help

Flags: --token <pat> · --http · --port <n> · --bridge-port <n> · --no-bridge · --cache-ttl <min> · --cache-root <path> · --no-cache.

Tools (15)

Read tools (REST + PAT, free plan OK)

Every read tool accepts either fileKey or a full url (the node-id query param is honored).

Replica tools (the differentiator)

compare_html_to_image methodology (also returned in every response):

• per-pixel threshold: pixelmatch threshold (default 0.1) decides whether two pixels count as different.

• anti-alias accounting: pixelmatch flags anti-aliased pixels; the primary diffPixels/diffRatio count excludes them (antiAliasCountedInDiff: false). antiAliasPixels is reported separately (derived from a second includeAA run) so you can tell "text-edge jitter" apart from real mismatches.

• pass line: passed = diffRatio <= maxRatio, default 0.01 (1 %). Sizes must match within a 2 px crop tolerance or the call returns size_mismatch.

The output schema of get_html_replica_spec is the input schema of verify_html_parity (specPath or inline spec) — the closed loop.

Tolerances (ported from production-proven internal tooling):

POS_TOL = 4        FONT_SIZE_TOL = 1      LS_TOL = 0.5
LH_TOL  = 2        COLOR_TOL     = 2/255  VISUAL_MAX_RATIO = 0.01 (crop ≤ 2px)

Everything brand-specific is parameterized via options: skipSections, sectionMap, expectedCounts ({logos, assets, minIcons}), looseRectHints, logoPattern/iconPattern, font aliases/overrides.

Write tools (companion plugin bridge)

The companion plugin (plugin/) connects to the MCP server at ws://127.0.0.1:39220. Import once: Figma desktop → Plugins → Development → Import plugin from manifest… → select ~/.figmingo/plugin/manifest.json (or plugin/manifest.json in this repo), then keep it running. Works on free plans — writes never touch the REST quota.

Architecture note: Figma's plugin sandbox (code.js) cannot open WebSockets, so the socket lives in the plugin's UI iframe (ui.html) and command envelopes are relayed between the iframe and the sandbox via postMessage (same architecture as proven local plugins like figwright). The UI shows a small status panel (● connected / ○ connecting / ✕ failed + reason, server address, executed-command count) so you can tell at a glance the bridge is alive. In practice the plugin only talks to your local server; image bytes are pushed over the socket as base64.

Batch semantics (commands: [...]): the plugin executes commands sequentially and sends a progress heartbeat over the socket after every command (success or failure). On the server there is no fixed 30 s hard cap:

• Idle timeout (idleTimeoutMs, default 20 000): max silence between heartbeats/result. Every heartbeat resets it, so a healthy 50-command batch never trips it no matter how long it runs.

• Total cap (timeoutMs, default 300 000 = 5 min): the only hard limit, and it's yours to set per call.

• Partial results: a batch result always carries a per-command results array ({index, command, ok, result|error}) plus aborted/error when stopOnError (default true) cut it short — you see exactly what ran.

• Timeout errors are atomic-friendly: if a call still times out, the error message lists the command indexes confirmed applied via heartbeats (e.g. Confirmed completed command indexes: [0, 1, 2] (3/19)), so you know precisely what the canvas contains before retrying; the plugin may continue in the background, so inspect the page (get_page_children) first.

Single (non-batch) commands use the same idle/total model.

Replica Playbook

The closed loop, end to end:

flowchart LR
    F["Figma design<br/>(or any reference)"] -- "get_html_replica_spec" --> S["replica spec<br/>(absolute rects, computed<br/>typography, asset manifest)"]
    S --> H["HTML / CSS"]
    H -- "render_html_screenshot" --> R["Chromium render"]
    R -- "verify_html_parity · compare_html_to_image" --> G{"three gates<br/>content · structural ±4px · visual ≤ 1%"}
    G -- "per-band diff localization" --> H
    G -- "passed" --> I["import_html_replica"]
    I -- "plugin bridge · deterministic (MD5-verified)" --> C["native Figma frames"]

    style G fill:#b7791f,color:#fff
    style C fill:#0d9e6e,color:#fff

Doing an HTML replica of a Figma design (or any reference screenshot)? Read docs/REPLICA-PLAYBOOK.md first — the 6-step battle flow distilled from six scored replica rounds (measure-before-CSS, font lock-in, bandEdges-driven iteration, single-variable changes, convergence criteria), diff image reading, tool cheat sheet, and the copy-proofing checklist. It exists so your next replica converges in 3–4 rounds instead of 7.

Free-plan availability

Acceptance (验收)

Battle-tested on six scored replica challenges (independent judge agents, re-measured from scratch — no self-reported numbers):

npm install
npm run build
npm test            # 176 unit tests (vitest) with recorded fixtures

# live acceptance against the real API:
FIGMA_API_KEY=<pat> TEST_FILE_KEY=<file-key> [TEST_NODE_ID=1:2] npm run accept

npm run accept walks every tool and prints a ✅ / ⏭️ / ❌ checklist. It exits gracefully with guidance when the token/file key is missing; write tools report SKIP (not FAIL) when the companion plugin isn't connected.

Development

npm run build         # tsup (dist/) + tsc (plugin/code.js)
npm run typecheck     # strict tsc --noEmit
npm test              # vitest
npm run accept        # live acceptance checklist

Repo layout: see ARCHITECTURE.md — it is the authoritative spec for the tool list, REST facts, caching, bridge protocol, and the acceptance plan.

License

MIT

中文文档

本地优先的 Figma MCP 服务器：免费 Figma 套餐也能跑全部读取能力（Personal Access Token + 公开 REST API，无席位配额、无月度上限）；HTML 1:1 复刻工具链（内置三关验收）；通过伴侣插件桥把内容写回画布。

架构

flowchart LR
    subgraph clients["AI 客户端"]
        A["Cursor · Claude Code · Claude Desktop<br/>VS Code · Kimi CLI · Codex"]
    end
    A -- "stdio / Streamable HTTP" --> B["figmingo-mcp<br/>本地服务器"]
    B -- "REST + Personal Access Token" --> C[("Figma REST API<br/>（免费套餐可用）")]
    B <-- "WebSocket ws://127.0.0.1:39220" --> D["伴侣插件<br/>（Figma 桌面端）"]
    D -- "Plugin API 写入" --> E[("你的画布")]
    B --- F[("磁盘缓存<br/>文档 15 分钟 · 渲染图 30 天")]

    style B fill:#6e56cf,color:#fff
    style D fill:#0d9e6e,color:#fff

一切都在你自己的机器上运行：没有中转服务器，除了调用 api.figma.com，数据不出本机。

与其他方案对比

安装

一条命令（macOS / Linux）：

curl -fsSL https://raw.githubusercontent.com/wenym8/figmingo-mcp/main/scripts/install.sh | bash

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/wenym8/figmingo-mcp/main/scripts/install.ps1 | iex

安装器会：检测 Node ≥ 18 → 全局安装包 → 安装 Playwright Chromium（约 170MB，一次性，HTML 渲染/提取/对比工具需要）→ 写入 Cursor（~/.cursor/mcp.json）、Claude Code（~/.claude.json）、Claude Desktop、VS Code、Kimi CLI（~/.kimi/mcp.json）、Codex CLI（~/.codex/config.toml，TOML，只改 [mcp_servers.figmingo] 段，原文件备份为 config.toml.figmingo-bak）的 MCP 配置 → 把伴侣插件（manifest + code.js + ui.html）复制到 ~/.figmingo/plugin → 打印后续指引。重复运行幂等，不会清掉已配置的 Figma token。

装完运行 figmingo-mcp doctor 自检整个环境（Node、token 有效性、Chromium、插件文件与版本漂移、客户端配置项、桥端口）——每项打印 ✓/✗ 并附修复提示，全部通过时退出码才为 0。

手动配置（任意客户端）：

{
  "mcpServers": {
    "figmingo": {
      "command": "npx",
      "args": ["-y", "figmingo-mcp"],
      "env": { "FIGMA_API_KEY": "figd_..." }
    }
  }
}

获取 PAT：Figma → 设置 → 安全 → Personal access tokens → 生成新 token（读工具只需读权限）。

用法

figmingo-mcp                      # stdio 传输（默认，AI 客户端用这个）
figmingo-mcp --http --port 3845   # Streamable HTTP：http://127.0.0.1:3845/mcp
figmingo-mcp cache-clear          # 清空 ~/.figmingo/cache
figmingo-mcp doctor               # 环境自检
figmingo-mcp --help

15 个工具

读取工具（REST + PAT，免费套餐可用）：whoami（token 自检 + 限流/缓存状态）· get_design_context（精简节点树：绝对坐标、auto-layout、填充/描边/效果、文字样式）· get_metadata（轻量树，XML/JSON，深取前先定位）· get_screenshot（节点渲染图，scale 0.01–4，png/jpg/svg/pdf）· download_assets（批量导出节点 + 原始图片填充，带清单）· get_variable_defs（variables 接口 403 时降级 styles + 推导 tokens，标 source）· search_design_system（本地索引查组件/样式）· get_code_connect_map（组件→代码映射）。

所有读取工具都接受 fileKey 或完整 url（自动解析 node-id）。

复刻工具（差异化能力）：get_html_replica_spec（复刻专用文档：绝对矩形、计算后的字体排版、hex+alpha 颜色、渐变、资产清单）· render_html_screenshot（Playwright 截图 URL/本地 HTML/HTML 字符串）· verify_html_parity（验收闸门：内容关文案/字体/颜色、结构关 ±4px、视觉关像素 diff ≤ 1%，产出 report.json + diff 图）· compare_html_to_image（一键视觉 diff，bands 分带定位差异，AA 像素单独记账）。

容差（生产验证过的内部工具移植）：

POS_TOL = 4        FONT_SIZE_TOL = 1      LS_TOL = 0.5
LH_TOL  = 2        COLOR_TOL     = 2/255  VISUAL_MAX_RATIO = 0.01（裁切 ≤ 2px）

写入工具（伴侣插件桥）：bridge_status（桥连接状态）· execute_plugin_command（14 种命令 + commands: [...] 批次，顺序执行，$var 节点引用，心跳超时机制）· import_html_replica（HTML 文件/URL 一键直导为原生 Figma frames，Chromium 提取布局与计算样式，dryRun 预览，降级进 warnings）。

插件连接 ws://127.0.0.1:39220。导入一次：Figma 桌面端 → 插件 → 开发 → Import plugin from manifest… → 选 ~/.figmingo/plugin/manifest.json，保持运行即可。免费套餐可用——写入不占用 REST 配额。

架构说明：Figma 插件沙箱（code.js）无法开 WebSocket，所以连接由插件的 UI iframe（ui.html）持有，命令经 postMessage 在 iframe 与沙箱间转发。UI 有状态面板（● 已连接 / ○ 连接中 / ✕ 失败原因、服务器地址、已执行命令数）。

批次语义：插件顺序执行，每条命令（无论成败）后都发 progress 心跳。服务器没有 30s 硬顶：空闲超时（idleTimeoutMs，默认 20s，心跳即重置）+ 总上限（timeoutMs，默认 5 分钟，可每次调用自设）。批次结果带逐命令 results 数组；超时错误会列出已确认落画布的命令索引，重试前先用 get_page_children 看画布现状。

复刻闭环

flowchart LR
    F["Figma 设计稿<br/>（或任意参考图）"] -- "get_html_replica_spec" --> S["复刻 spec<br/>（绝对矩形、计算排版、<br/>资产清单）"]
    S --> H["HTML / CSS"]
    H -- "render_html_screenshot" --> R["Chromium 渲染"]
    R -- "verify_html_parity · compare_html_to_image" --> G{"三关验收<br/>内容 · 结构 ±4px · 视觉 ≤ 1%"}
    G -- "bands 分带定位差异" --> H
    G -- "通过" --> I["import_html_replica"]
    I -- "插件桥 · 确定性（MD5 验证）" --> C["原生 Figma frames"]

    style G fill:#b7791f,color:#fff
    style C fill:#0d9e6e,color:#fff

做 HTML 复刻先读 docs/REPLICA-PLAYBOOK.md——六轮带评分实战沉淀的 6 步流程（先量后写 CSS、字体锁定、bandEdges 驱动迭代、单变量改动、收敛判据）、diff 图读法、工具速查表、防抄漏清单。让你的下一次复刻 3–4 轮收敛，而不是 7 轮。

免费套餐可用性

验收

六轮带评分的复刻挑战实测（独立 judge agent 从零复测，非自报数据）：

npm install
npm run build
npm test            # 176 个单元测试（vitest，录制 fixtures）

# 真实 API 验收：
FIGMA_API_KEY=<pat> TEST_FILE_KEY=<file-key> [TEST_NODE_ID=1:2] npm run accept

npm run accept 逐个工具打 ✅ / ⏭️ / ❌；token/fileKey 缺失时优雅退出并给指引；插件未连接时写工具报 SKIP（不是 FAIL）。

开发

npm run build         # tsup（dist/）+ tsc（plugin/code.js）
npm run typecheck     # 严格 tsc --noEmit
npm test              # vitest
npm run accept        # 真实 API 验收清单

仓库结构见 ARCHITECTURE.md——工具清单、REST 事实、缓存、桥协议、验收方案的权威文档。

License

MIT