figma-mcp-go 阅读分析与使用笔记

这篇文章解决什么问题

figma-mcp-go 是 vkhanhqui 做的一个 Figma MCP server，仓库地址：

• vkhanhqui/figma-mcp-go

它不是常见的“用 Figma REST API 包一层 MCP”。它的核心做法是：

• Go 进程作为 MCP server，对外提供 stdio MCP。
• Figma plugin 运行在 Figma Desktop 内，直接调用 Figma Plugin API。
• 两者用本地 WebSocket 连接。
• MCP 工具调用先到 Go server，再转发给 Figma plugin 执行。

一句话：

figma-mcp-go 想绕开 Figma REST API 的额度限制，把 AI 工具直接接到一个打开中的 Figma 文件。

采集时间：2026-06-04。
阅读对象：GitHub main 分支、README、cmd/figma-mcp-go、internal、plugin、npm、server.json，并核对 GitHub release / npm 当前版本。
说明：本文未本地安装、未连接 Figma、未实际运行 MCP tools，只做源码和文档静态阅读。

先说结论

• 它的核心价值是“plugin bridge”，不是 Go 本身，也不是某个提示词。
• 它适合把 AI 变成 Figma 里的读写助手：读页面结构、导出截图、生成/修改节点、处理样式、变量、组件和 prototype。
• 它依赖 Figma Desktop 里持续运行的 plugin。plugin 没连上时，MCP server 只能报 plugin not connected。
• 它绕开的是 Figma REST API 配额，不是绕开 Figma 权限模型；实际操作仍发生在当前打开的 Figma 文件里。
• 它把写操作也开放给 AI，所以更适合可回滚、可复制、可局部选区的设计文件，不适合直接在唯一生产稿上无保护地批量改。
• 多 MCP client 同时启动时，它用 leader / follower 模型复用一个本地 WebSocket bridge，设计上比单进程脚本稳一些。
• 当前版本信息有轻微漂移：npm 当前是 0.1.3，GitHub latest release 是 v0.1.3，但仓库内 npm/package.json 仍写 0.0.1-alpha，server.json 写 0.1.0。实际落地前以 npm / release 为准。

我的判断：

figma-mcp-go 更像“本地 Figma 自动化通道”，不是“设计理解模型”。它给 AI 手脚，但设计判断仍要靠 prompt、上下文和人工验收。

它解决的真实问题

Figma MCP 常见路线是走 Figma REST API。这个方案有两个问题：

问题	影响
API 配额低	高频调试、反复读取设计稿时很快耗尽额度
能力受 REST API 边界限制	某些实时文档、选区、plugin-only 行为不好处理

figma-mcp-go 的选择是让 Figma plugin 成为执行端。这样 AI 不再直接问 Figma 云 API，而是问本地 plugin：

AI client
  -> stdio MCP
  -> Go server
  -> ws://127.0.0.1:1994/ws
  -> Figma plugin
  -> Figma Plugin API

这个设计带来的直接收益：

• 不需要 Figma API token。
• 不吃 REST API tool call 配额。
• 能读当前打开的文件、当前页面、当前选区。
• 能直接写入 Figma 节点、样式、变量、组件和 prototype。

代价也很明确：

• Figma Desktop 必须打开。
• plugin 必须安装并运行。
• 本地 WebSocket 必须连通。
• AI 修改是实时写入设计文件，需要人工控制范围。

核心架构

仓库分成几块：

目录	作用
cmd/figma-mcp-go	Go 二进制入口，启动 MCP server、选举、tool 注册
internal	bridge、leader/follower、tool 注册、schema、prompt
plugin	Figma plugin，包含核心脚本和 Svelte UI
npm	npm 包壳，按平台启动预编译 Go 二进制
server.json	MCP registry 元数据

1. Go 进程：MCP server + 本地桥

入口 cmd/figma-mcp-go/main.go 做几件事：

1. 读取 --ip 和 --port，默认 127.0.0.1:1994。
2. 如果绑定非 loopback 地址，会打印无鉴权网络暴露警告。
3. 创建 Node 和 Election。
4. 注册 MCP tools 和 prompts。
5. 用 stdio 对 MCP client 服务。

这里有一个重要边界：MCP transport 是 stdio，但 Go 进程内部还会开一个 HTTP server 给 Figma plugin 连。

2. Bridge：WebSocket 请求/响应匹配

internal/bridge.go 是核心桥接层。

它维护一个 plugin WebSocket 连接，并用 requestId 匹配请求和响应：

• Go 发 BridgeRequest：type、requestId、nodeIds、params。
• plugin 回 BridgeResponse：type、requestId、data、error。
• 普通请求默认 30 秒超时。
• get_document 给 60 秒，因为大文件更慢。
• plugin 发送 progress 时，会把 pending 请求的超时续到 60 秒。
• WebSocket 读限制提高到 100 MB，避免大设计树直接被默认 32 KiB 限制断开。

这说明它不是简单 fire-and-forget，而是按 MCP tool call 做同步等待。

3. Leader / Follower：多个 MCP client 共享一个 bridge

这个仓库比较有意思的点是 leader / follower。

多个 AI 工具可能同时启动同一个 MCP server。如果每个进程都抢 127.0.0.1:1994，plugin 只能连其中一个。

它的解法：

角色	行为
Leader	成功绑定本地端口，提供 /ws、/ping、/rpc
Follower	端口已被占用时，通过 /rpc 把 tool call 代理给 Leader
Election	follower 定期 ping leader；leader 挂了就尝试 takeover

所以工具调用路径有两种：

Leader MCP process -> Bridge -> Figma plugin
Follower MCP process -> HTTP /rpc -> Leader -> Bridge -> Figma plugin

这让它适合 Cursor、Claude、Codex、Copilot 等多个 MCP client 共存的场景。

Figma plugin 端怎么工作

plugin/src/main.ts 是 plugin core：

• 打开一个 320 x 230 的 plugin UI。
• 把当前文件名、页面名、选区数量发给 UI。
• 处理 UI 消息：读取/保存 WebSocket 地址、转发 server request。
• 先走 read handler，再走 write handler。
• 未知请求会返回 Unknown request type。

plugin/src/ui/App.svelte 做连接管理：

• 默认连接 ws://127.0.0.1:1994/ws。
• 支持改 host / port，并用 figma.clientStorage 持久化。
• 断线后每 1500 ms 自动重连。
• 收到 Go server 的请求后，通过 parent.postMessage 交给 plugin core。
• plugin core 执行完后，再把结果通过 WebSocket 发回 Go server。

plugin/manifest.json 里 networkAccess.allowedDomains 是 ["*"]。原因是 host / port 可配置，但这也意味着如果你把 Go server 绑定到非本机地址，要把网络暴露风险当成真实问题处理。

工具能力范围

README 标称有 73 个 tools。源码注册按读写分层：

分类	代表能力
Read Document	get_document、get_metadata、get_pages、get_selection、get_node、get_design_context、search_nodes
Read Styles	get_styles、get_variable_defs、get_local_components、get_fonts、get_reactions
Export	get_screenshot、save_screenshots、export_frames_to_pdf、export_tokens
Write Create	create_frame、create_rectangle、create_text、import_image、create_component、create_section
Write Modify	set_text、set_fills、set_strokes、move_nodes、resize_nodes、set_auto_layout、find_replace_text
Write Styles / Variables	创建和更新 paint/text/effect/grid style，创建 collection / variable，绑定变量到节点
Write Components / Pages / Prototype	group / ungroup、swap component、detach instance、add / delete / rename page、set / remove reactions

最实用的几个场景：

1. 读设计：用 get_selection、get_design_context、get_styles 让 AI 理解当前选区和设计系统。
2. 设计转代码：先读结构和截图，再让 AI 生成页面代码。
3. 批量改稿：用 find_replace_text、batch_rename_nodes、set_fills 处理重复性编辑。
4. 资产导出：用 save_screenshots 或 export_frames_to_pdf 把选定 frame 落到本地项目。
5. 设计系统整理：导出 tokens、读取 variables/styles/components，检查命名和使用一致性。

内置 prompts 的价值

除了 tools，它还注册了一组 MCP prompts：

• read_design_strategy
• design_strategy
• text_replacement_strategy
• annotation_conversion_strategy
• swap_overrides_instances
• reaction_to_connector_strategy
• style_audit_strategy
• bulk_rename_strategy
• design_token_generation_strategy
• generate_color_palette
• generate_type_scale
• generate_component_variants

这些 prompt 的意义不是“自动变强”，而是把高风险操作拆成更稳的工作流。例如批量替换文本、交换组件实例、审计样式、生成 tokens，都需要先读上下文，再小范围执行，再检查结果。

实际使用时，不应该直接说：

把整个 Figma 文件改成新风格。

更好的做法是：

读取当前选区，列出 frame / text / component / style 概况。
先不要修改。

确认后再让它修改具体节点。

安装和日常使用

MCP client 侧可以用 npm 包：

npx -y @vkhanhqui/figma-mcp-go@latest

Codex CLI 示例：

codex mcp add figma-mcp-go -- npx -y @vkhanhqui/figma-mcp-go@latest

Claude Code CLI 示例：

claude mcp add -s project figma-mcp-go -- npx -y @vkhanhqui/figma-mcp-go@latest

Figma 侧还要安装 plugin：

1. 到 GitHub release 下载 plugin.zip。
2. Figma Desktop 里打开 Plugins -> Development -> Import plugin from manifest。
3. 选择 plugin 的 manifest.json。
4. 在目标 Figma 文件里运行 plugin。
5. 确认 plugin UI 显示 Connected。

推荐顺序：

1. 先启动 MCP client。
2. 再打开 Figma Desktop 和目标文件。
3. 运行 plugin。
4. 先调用只读工具确认连接和选区。
5. 写操作前复制 frame 或限定 nodeId。

使用边界和风险

1. 写操作是真写入

delete_nodes、set_text、find_replace_text、batch_rename_nodes 都会改当前 Figma 文件。MCP tool 本身不会替你做版本分支或 undo 保护。

建议：

• 先复制目标 frame。
• 先只读。
• 先小范围 nodeId。
• 批量操作前让 AI 输出计划。
• 操作后用 get_selection / screenshot 校验。

2. 本地 server 默认安全，改地址后要小心

默认监听 127.0.0.1:1994，只对本机开放。

如果改成 0.0.0.0 或局域网 IP，源码会提示：

server will be reachable from the network with no authentication

这不是形式提醒。因为 /rpc 能转发写操作，一旦暴露给不可信网络，风险很直接。

3. 版本信息要以发布侧为准

这次阅读时看到：

来源	版本
npm registry	0.1.3
GitHub latest release	v0.1.3
server.json	0.1.0
npm/package.json	0.0.1-alpha

如果要写团队文档，不要直接复制仓库内 npm/package.json 的版本号。用 npm view @vkhanhqui/figma-mcp-go version 或 GitHub release 核对。

4. 它不替代设计评审

这个项目解决的是“AI 能不能读写 Figma”。它不保证：

• 自动做出好设计。
• 自动理解品牌规范。
• 自动知道哪些 frame 不能改。
• 自动避免视觉回归。

所以更适合把它当成设计自动化工具，而不是设计负责人。

适合什么任务

适合：

• 从 Figma 选区读结构，辅助前端还原。
• 导出页面截图或 frame PDF。
• 批量替换文案、重命名图层、统一颜色。
• 抽取 styles / variables / tokens。
• 生成组件变体草稿。
• 给设计稿做结构化审计。

不适合：

• 不打开 Figma Desktop 的后台批处理。
• 无人值守地修改生产设计文件。
• 需要严格权限隔离的企业设计仓库。
• 把“审美判断”完全交给 agent。

我的使用建议

如果我在真实项目里用它，会按这个节奏：

1. 只读连接测试：get_metadata、get_pages、get_selection。
2. 限定范围：只处理当前选区或明确 nodeId。
3. 先审计：让 AI 列结构、样式、变量、风险，不改文件。
4. 再执行：一次只做一种修改，例如只替换文案或只统一颜色。
5. 导出校验：用 get_screenshot / save_screenshots 对比前后。
6. 人工确认：复杂布局和组件替换必须回 Figma 看结果。

一句话原则：

先让 AI 看，再让 AI 说计划，最后才让 AI 写。

参考链接

• vkhanhqui/figma-mcp-go
• README.md
• cmd/figma-mcp-go/main.go
• internal/bridge.go
• internal/leader.go
• internal/follower.go
• plugin/src/main.ts
• plugin/src/ui/App.svelte
• npm package
• v0.1.3 release