Skip to main content
Glama

Figma-MCP

本机 Figma 插件 + 标准 MCP。不经过官方付费 MCP,让 Cursor、Claude Code、Codex、OpenCode 等 Agent 读写当前打开的 Figma 桌面端文件,并按精确数值和预览图做像素级还原。不绑定某一家客户端。

开源仓库名是 Figma-MCP。Figma 里导入后,开发插件仍显示为「Figma设计桥接」。Agent 配置里的服务名建议继续用 figma-bridge。本仓库使用 MIT 许可。

可实现

  • 读取当前文件、当前页、选区和节点结构。

  • 把节点切成本地 PNG / SVG 等文件。

  • 在当前画布创建和修改基础节点。

  • 用固定的 layout 数据合同支持像素级实现。

Related MCP server: Writable Figma MCP Bridge

安装教程

整套东西分三块,缺一块都连不上:

  1. 本仓库构建出 dist/server/index.js(MCP + 本机 WebSocket 桥,同一进程)。

  2. Figma 桌面端导入并运行开发插件「Figma设计桥接」,面板保持打开。

  3. Cursor / Claude Code 等客户端用 stdio 拉起上面的 Node 进程。

插件只连本机,不连 Figma 云端 MCP,也不支持网页版 Figma。同一时间只能有一个 MCP 进程占桥,默认 127.0.0.1:17653。

下面命令里的 /绝对路径/Figma-MCP 请换成你本机仓库目录。macOS / Linux 用正斜杠;Windows 建议同样写成正斜杠,例如 C:/Users/你/Figma-MCP。

1. 准备环境

项

要求

系统

macOS、Windows 或 Linux。插件必须在 Figma Desktop 里跑。

Node.js

20 或更高。终端执行 node -v 确认。

npm

随 Node 一起安装即可。本仓库用 npm,不用 pnpm / yarn。

Figma

安装 Figma 桌面端,用能打开目标文件的账号登录。网页版不要用来接本桥。

Agent

任意能配置「命令 + 参数」拉起 stdio MCP 的客户端。第一版不提供 HTTP / SSE MCP。

官方 Figma MCP / Dev Mode 会员不是前置条件。本项目就是为了不走那条付费通道。

2. 拿到代码并构建

git clone https://github.com/huaer9000/Figma-MCP.git
cd Figma-MCP
npm install
npm run build

如果你已经把代码放在别的目录,把下面出现的 /绝对路径/Figma-MCP 换成实际路径即可。

构建成功后必须能看到这两个产物,缺了后面一定连不上:

  • dist/server/index.js:给 Agent 启动的 MCP 入口

  • plugin/dist/code.js 与 plugin/dist/ui.html:给 Figma 加载的插件

可选自检:

npm test

改过 TypeScript 源码、写入原则或插件之后,都要重新 npm run build。只改源码、不构建,正在跑的进程和 Figma 里的插件都还是旧的。

3. 在 Figma 桌面端导入开发插件

必须先完成上一步构建。导入的是清单,不是某个 .js 单文件。

  1. 打开 Figma Desktop(不要用浏览器里的 Figma)。

  2. 打开你要操作的那份设计文件。

  3. 菜单按界面语言二选一:

    • 中文:插件 → 开发 → 从清单导入插件…

    • 英文:Plugins → Development → Import plugin from manifest…

  4. 选中本仓库里的 plugin/manifest.json(就是这一份,不要选 plugin/dist/ 下的文件)。

  5. 导入成功后,再运行一次插件:

    • 中文:插件 → 开发 → Figma设计桥接

    • 英文:Plugins → Development → Figma设计桥接

  6. 会弹出插件面板,里面有状态、文件名、页面名、端口、错误信息和「重连」按钮。面板关掉就断连,除 figma_status 外其它工具会立刻报未连接。

导入时报清单错误、提到 127.0.0.1 不合法时:不要改成 ws://127.0.0.1:17653。本仓库已经写成 localhost,请确认你导入的是当前这份 plugin/manifest.json。

第一次打开面板时,状态多半是红色「未连接」,提示先启动 Agent 里的 MCP。这是正常的,先去做第 4 步,再回到面板点「重连」,或等几秒让它自动重连。

4. 在 Agent 里接入 MCP

所有客户端都是同一条命令:用本机 node 跑构建好的入口。服务名建议固定为 figma-bridge。

command: node
args:    /绝对路径/Figma-MCP/dist/server/index.js

不要同时在「用户级配置」和「项目级配置」里各写一份同名服务,Cursor 会起两个进程抢端口。本机只保留一份。

Cursor

  1. 打开 Cursor 设置里的 MCP 配置,或直接编辑用户级文件:

    • macOS / Linux:~/.cursor/mcp.json

    • Windows:%USERPROFILE%\.cursor\mcp.json

  2. 写入(可与你已有的其它 mcpServers 合并,不要覆盖整份文件):

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/绝对路径/Figma-MCP/dist/server/index.js"]
    }
  }
}
  1. 保存后确认该服务处于已启用。Cursor 会自己拉起 Node 进程;一般不必再开一个终端跑服务。

  2. 若列表报错或一直灰色:看 Cursor 的 MCP 日志。常见原因是路径写错、还没 npm run build、或 17653 已被另一份桥占用。

更新本仓库代码后,只保存 mcp.json 有时不会换新进程。可在该服务下加一个无害环境变量再保存,逼它重新 spawn,例如:

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/绝对路径/Figma-MCP/dist/server/index.js"],
      "env": {
        "FIGMA_BRIDGE_BOOT": "1"
      }
    }
  }
}

以后每更新一次桥,把这个数字加 1 即可。不要在外面 kill 掉 Cursor 拉起的进程后又自己 npm run bridge,端口会被抢走,Cursor 也不会自动再拉起来。

Claude Code

claude mcp add --transport stdio figma-bridge -- node "/绝对路径/Figma-MCP/dist/server/index.js"

用 claude mcp list 确认服务名是 figma-bridge,且指向构建后的 dist/server/index.js。

Codex、OpenCode、Cline 及其它 stdio 客户端

按该客户端自己的 MCP 配置格式,填同样的 command + args。不要改工具名,也不要改成本项目没有的 HTTP 地址。

若某个客户端只支持远程 HTTP MCP、不支持本地 stdio,第一版接不上,不要为此改插件协议。

5. 确认已经连上

建议按这个顺序:

  1. Agent 里的 figma-bridge 已启用(Node 进程在跑)。

  2. Figma 桌面端打开目标文件,运行「Figma设计桥接」,面板开着。

  3. 面板状态变成绿色「已连接」,并显示当前文件名和页名,端口为 17653。

  4. 在 Agent 里让它调用 figma_status。应返回 connected: true,以及文件名、页名。

插件已连接后,在 Figma 里选中一个 Frame,再对 Agent 说「按当前选区做像素级还原」。握手时客户端会收到写入原则;完整条文在资源 figma://write-guidelines。

未开插件时:figma_status.connected 为 false,其它工具应立刻失败,而不是空等超时。

6. 日常使用注意

  • 同一时间只开一个本服务进程。换一个 Agent 用可以,两个一起开会抢 17653。

  • 默认端口可用环境变量 FIGMA_BRIDGE_PORT 覆盖。改端口后,必须同步改 plugin/manifest.json 的 devAllowedDomains,重新构建插件并重新导入。不要占用官方桌面 MCP 的 3845。

  • 改完原则、工具或桥之后必须三步都做:npm run build → 重启该客户端的 figma-bridge → 在 Figma 里重新运行插件。旧 MCP 进程看不到新说明和新工具。

  • 第一版无鉴权。桥只绑本机回环地址,但同机其它进程也能连上并操作当前打开的文件。

没有 MCP 客户端时

只想让插件先显示「已连接」,可以在仓库根目录执行:

cd "/绝对路径/Figma-MCP"
npm run bridge

它只听 WebSocket,不要和 Cursor(或其它客户端)里已经启用的 figma-bridge 同时开,会抢端口。

npx tsx scripts/probe.ts 是探测脚本,跑完会关掉桥,插件会立刻变回未连接。这是预期行为,不要靠它保活。

安装排错

现象

处理

插件一直「未连接」

先确认 MCP 进程已拉起;再在面板点「重连」。不要只开插件、不启 MCP。

导入插件失败

确认选的是 plugin/manifest.json,且已经 npm run build。清单里必须是 localhost,不能是 127.0.0.1。

MCP 报端口已被占用

关掉另一份 figma-bridge 或终端里的 npm run bridge。不要换端口偷偷再起一份。

改完代码 Agent 仍是旧工具

先 npm run build,再重启 MCP(Cursor 可改 FIGMA_BRIDGE_BOOT),并重新运行插件。

网页版 Figma 连不上

换桌面端。第一版不支持浏览器。

node 命令找不到或版本过低

安装 Node.js 20+,用 which node / where node 核对 MCP 配置里用的就是这个可执行文件。

更多已验证的环境问题见 已知陷阱。

文档导航

相关 Skill 与工具

  • 项目初始化:project-initializer

  • 运行时:Figma Desktop Plugin API、标准 MCP stdio、本机 WebSocket

当前里程碑

  1. 技术规格

  2. 协议、桥、23 个工具与插件(已完成代码)

  3. Figma Desktop 手工验收(未完成)

Available Tools

23 tools
figma_create_ellipseD

创建椭圆。

Inputs: x (required), y (required), width (required), height (required), +3 more.

figma_create_frameB

在当前页或指定父节点创建 Frame。复刻时优先嵌套 Auto Layout;按钮用 Frame 包文案并居中。

Inputs: x (required), y (required), width (required), height (required), +2 more.

figma_create_imageB

从本机图片文件创建矩形或 SVG 节点。不支持远程 URL。色块不能当成已经插图。

Inputs: x (required), y (required), width (required), height (required), +5 more.

figma_create_rectangleD

创建矩形。

Inputs: x (required), y (required), width (required), height (required), +4 more.

figma_create_textC

创建文本。指定字体失败不会改用其它字体。

Inputs: x (required), y (required), characters (required), fill, +3 more.

figma_delete_nodeB

删除节点。不能删除 PAGE 或 DOCUMENT。

Inputs: nodeId (required).

figma_export_nodeB

导出节点到本地文件。必须提供绝对路径 outputPath。不要把图片以 base64 传回。

Inputs: nodeId (required), outputPath (required), scale, format.

figma_get_current_pageB

获取当前页摘要、顶层子节点和选区。

Inputs: no named parameters.

figma_get_document_infoB

获取当前文件名、页面列表和当前页 id。

Inputs: no named parameters.

figma_get_nodeC

读取单个节点。detail=summary|layout|rest_json,默认 layout。

Inputs: nodeId (required), detail, maxDepth.

figma_get_node_treeC

读取 layout 级节点树,供浏览结构。

Inputs: nodeId (required), maxDepth.

figma_get_selectionA

获取当前选区摘要。空选区返回空数组,不是错误。

Inputs: no named parameters.

figma_move_nodeC

移动节点,可选换父级。

Inputs: x (required), y (required), nodeId (required), index, +1 more.

figma_read_for_implementA

像素级还原打包:结构、预览图、位图资源落到 outputDir。省略 nodeId 时要求恰好选中 1 个节点。

Inputs: outputDir (required), nodeId.

figma_set_auto_layoutB

设置 Auto Layout。打开后要把横排全宽设 FIXED 或子项 FILL,否则会 HUG 变窄。

Inputs: nodeId (required), layoutMode (required), padding, itemSpacing, +4 more.

figma_set_corner_radiusC

设置圆角。四角独立优先。

Inputs: nodeId (required), radius, topLeft, topRight, +2 more.

figma_set_current_pageC

切换到指定页面。会先 loadAsync。

Inputs: pageId (required).

figma_set_effectsC

设置效果。第一版可写 BACKGROUND_BLUR / LAYER_BLUR / DROP_SHADOW / INNER_SHADOW。毛玻璃用半透明填充加 BACKGROUND_BLUR。

Inputs: nodeId (required), clear, effects.

figma_set_fillB

设置单层纯色填充,或用 clear 去掉填充(透明 Frame,不要用 a:0 冒充去底)。

Inputs: nodeId (required), fill, clear.

figma_set_strokeC

设置单层实线描边。

Inputs: color (required), nodeId (required), weight (required).

figma_set_text_styleD

设置文本节点级样式。

Inputs: nodeId (required), fontName, fontSize, characters, +3 more.

figma_statusA

查询插件是否已连接,以及当前文件与页面。未连接也成功返回。

Inputs: no named parameters.

figma_update_nodeC

更新节点名称、位置、尺寸、可见性、透明度、旋转,以及 Auto Layout 子项的 FILL/HUG/绝对定位。

Inputs: nodeId (required), x, y, name, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 23 tools

    Disambiguation4/5

    The create_*/set_*/update_* families each target a distinct node property, and the read tools are mostly separable. There is mild overlap between figma_status, figma_get_document_info and figma_get_current_page (all report file/page context), and between figma_read_for_implement and figma_export_node (both dump node assets), but the descriptions clarify the boundaries.

    Naming Consistency4/5

    Every tool uses a predictable figma_<verb>_<noun> snake_case pattern (get_node, create_frame, set_fill, delete_node). The only deviation is figma_status, which omits the verb, but it remains readable and clearly scoped as a status probe.

    Tool Count3/5

    23 tools is on the heavy edge for a single-plugin bridge and could be consolidated (e.g. one generic style setter, or merging the three document/page reads). Most tools do earn a place as distinct Figma node primitives, so it is borderline rather than bloated.

    Completeness4/5

    The surface covers the full node lifecycle: read/inspect, create primitives, update geometry, style (fill, stroke, effects, radius, text style, auto layout), move/reparent, export and delete. Gaps remain around editing existing text content, grouping/boolean ops, and component/instance creation, but agents can work around these by recreating nodes.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP clients to read design structure, take screenshots, create nodes, and edit UI directly on Figma canvas via a bridge between MCP and Figma Desktop.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible AI clients to read and modify the user's currently open Figma file by executing JavaScript in Figma's sandbox, all through a local bridge with status monitoring, node jumping, and automatic rollback on errors.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to read and modify the currently open Figma design file through a paired local Figma plugin, supporting operations like creating nodes, editing properties, and exporting PNG/SVG.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to read and edit the file currently open in Figma Desktop through a local development plugin, supporting node inspection, JSON/image exports, and arbitrary Plugin API scripts without REST API rate limits.
      7
      11 npm
      MIT