Figma Vector MCP

Figma Vector MCP

一款 Figma 插件 + MCP 服务，可通过本地 WebSocket 中继，让 Claude（或任何 MCP 客户端）在 Figma 画布上创建和操控完全可编辑的矢量节点，包括路径、形状、渐变、文本、效果、图像填充等。

由 Working Model Inc 开发

版本 0.3.3 — 涵盖创建、样式、布局、组件、效果、页面和导出的 58 个工具。

为何开发此项目

cursor-talk-to-figma-mcp 非常适合读取 Figma 状态和创建基本图元，但它不具备矢量路径创建、渐变、效果或合成工具。此插件填补了这一空白：

功能	cursor-talk-to-figma-mcp	figma-vector-mcp
创建矩形 / 椭圆 / 画框 / 文本	✅	✅
根据 SVG 字符串创建	❌	✅
根据路径 d 字符串创建	❌	✅
创建折线 / 多边形	❌	✅
渐变填充（线性、径向、角度、菱形）	❌	✅
图像填充（base64 → 画布）	❌	✅
效果（阴影、模糊）	❌	✅
混合模式	❌	✅
布尔运算（联合、减去等）	❌	✅
自动布局	❌	✅
组件 + 实例	❌	✅
字体发现	❌	✅
节点搜索	❌	✅
多页面管理	❌	✅
命名节点注册表	❌	✅
批量命令（单次往返）	❌	✅
自动重连 + 命令队列	❌	✅
导出 SVG + PNG	❌	✅

---

架构

Claude (MCP client)
  ↕ stdio (MCP protocol)
server.ts (MCP server)
  ↕ WebSocket (ws://localhost:3055)
socket.ts (relay — channel-based routing)
  ↕ WebSocket
Figma plugin (ui.html ↔ code.js)
  ↕ postMessage
Figma Plugin API → canvas

套接字中继在本地运行。Figma 插件连接并加入一个命名频道。MCP 服务加入同一频道并发送命令。结果沿相同路径返回。

---

AI Agent 快速入门

适用于 AI Agent（Claude Code、Cursor 等）——启动任何会话的推荐调用顺序：

1. health_check                    → confirm plugin is connected
2. get_document_info               → get page IDs, current page, top-level nodes
3. get_available_fonts             → discover loadable fonts before create_text
4. get_styles                      → load brand colours/text styles if available

颜色约定： 全程所有 RGB 值均为 0–1（与 Figma 的内部格式一致）。r: 1, g: 0, b: 0 = 红色。切勿使用 0–255。

渐变工作流：

1. create_frame({ width, height })          → get frameId
2. set_gradient_fill({ nodeId: frameId, type: "LINEAR", angle: 135,
     stops: [{ color: { r:0.2, g:0.1, b:0.9 }, position: 0 },
             { color: { r:0.9, g:0.2, b:0.4 }, position: 1 }] })

图像填充工作流（使用生成式 AI）：

1. Generate image via Replicate/fal.ai → get base64 PNG
2. create_frame({ width: 512, height: 512 })
3. set_image_fill({ nodeId, base64, scaleMode: "FILL" })

批量合成——使用 $prev.id 串联命令，无需额外往返：

{ "commands": [
    { "command": "create_frame", "params": { "width": 400, "height": 300, "name": "Card" } },
    { "command": "set_gradient_fill", "params": { "nodeId": "$prev.id", "type": "LINEAR",
        "stops": [{"color":{"r":0.1,"g":0.1,"b":0.9},"position":0},
                  {"color":{"r":0.8,"g":0.2,"b":0.5},"position":1}] } },
    { "command": "create_text", "params": { "parentId": "$results.0.id",
        "text": "Hello", "fontSize": 32, "x": 24, "y": 24 } }
]}

已知 SVG 限制： figma.createNodeFromSvg() 会剥离 <defs>、渐变、滤镜、蒙版和动画。需要渐变时，请使用 set_gradient_fill，不要使用 SVG <linearGradient>。

重连： 如果插件断开连接，它会通过指数退避自动重连（1 秒→最长 30 秒），并重放排队的命令（最多保留 30 秒）。短暂中断无需手动干预。

---

设置

1 — 安装插件

1. 克隆此仓库或下载源代码
2. 在 Figma 桌面应用中：Plugins → Development → Import plugin from manifest
3. 选择 src/figma-plugin/manifest.json

2 — 安装 MCP 服务

npm install -g figma-vector-mcp
# or use without installing via npx / bunx (see MCP config below)

3 — 启动套接字中继

bun run socket

监听地址为 ws://localhost:3055。登录时自动启动（macOS）：

./scripts/setup.sh --launchd

4 — 配置 MCP 服务

# Auto-detect Claude Code / Cursor and write config:
./scripts/setup.sh

# Local build:
./scripts/setup.sh --local

# Install git pre-commit sandbox lint hook:
./scripts/setup.sh --hooks

手动配置（~/.claude/settings.json 或 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "FigmaVectorMCP": {
      "command": "bunx",
      "args": ["figma-vector-mcp@latest"],
      "env": { "FVMCP_CHANNEL": "figma-vector-mcp" }
    }
  }
}

5 — 连接插件

1. 打开你的 Figma 文件
2. Plugins → Development → Figma Vector MCP
3. 输入服务 URL（ws://localhost:3055）→ Connect
4. 输入频道名称（figma-vector-mcp）→ Join

插件会保存上次使用的 URL 和频道，下次打开时自动预填。会话期间请保持插件面板打开——关闭面板会终止 WebSocket 连接。

6 — 验证

health_check → { "status": "ok", "version": "0.3.3", "currentPage": { ... } }

---

环境变量

变量	默认值	描述
FVMCP_PORT	3055	Socket 中继端口
FVMCP_CHANNEL	figma-vector-mcp	通道名称 — 必须与插件一致
FVMCP_TIMEOUT_MS	10000	默认命令超时时间（ms）

各工具的超时设置：health_check → 3s，export_node_as_png → 30s，export_node_as_svg → 15s，create_batch → 60s。

---

工具参考

连接与健康状况

工具	描述	关键参数
health_check	Ping 插件；确认连接状态	—
join_channel	加入指定通道	channel

矢量创建

工具	描述	关键参数
create_vector_from_svg	根据 SVG 字符串放置可编辑矢量	svg、x、y、name、parentId
create_path	根据 SVG d 路径字符串创建矢量	d、x、y、fillColor、strokeColor、strokeWeight
create_polyline	根据 [x,y][] 点对创建矢量	points、closed、strokeColor、strokeWeight

基本图形

工具	描述	关键参数
create_frame	容器框架	width、height、x、y、fillColor
create_rectangle	矩形	width、height、x、y、fillColor
create_ellipse	椭圆 / 圆形	width、height、x、y、fillColor
create_text	文本节点，可选固定宽度列	text、fontSize、fontFamily、fontStyle、fillColor、width、height、textAutoResize

填充与颜色

工具	描述	关键参数
set_fill_color	纯色 RGBA 填充（0–1）	nodeId、r、g、b、a
set_gradient_fill	渐变填充 — LINEAR、RADIAL、ANGULAR、DIAMOND	nodeId、type、stops、angle、center、gradientTransform
set_image_fill	将 Base64 图像用作填充	nodeId、base64、scaleMode、opacity

描边

工具	描述	关键参数
set_stroke	完整描边控制	nodeId、color、weight、position、dashPattern、lineCap、lineJoin
set_stroke_color	快速设置描边颜色和粗细	nodeId、r、g、b、a、weight

效果与合成

工具	描述	关键参数
set_effect	投影、内阴影、模糊、背景模糊	nodeId、effects[]（type、color、offset、blur、spread）、mode（REPLACE | APPEND）
set_blend_mode	图层混合模式	nodeId、mode（NORMAL、MULTIPLY、SCREEN、OVERLAY…）

节点操作

工具	描述	关键参数
set_corner_radius	圆角半径 — 统一设置或逐角设置	nodeId、radius 或 topLeft、topRight、bottomLeft、bottomRight
set_opacity	不透明度 0–1	nodeId、opacity
set_text_style	修改文本属性和文本框尺寸	nodeId、fontSize、fontFamily、fontStyle、letterSpacing、lineHeight、textAlign、fillColor、width、height、textAutoResize
rename_node	重命名节点	nodeId、name
set_visibility	显示或隐藏节点	nodeId、visible
reorder_node	更改父节点内的 Z 顺序	nodeId、action（BRING_TO_FRONT / SEND_TO_BACK / BRING_FORWARD / SEND_BACKWARD）或 index
move_node	重新定位	nodeId、x、y
resize_node	调整大小	nodeId、width、height
delete_node	从画布中移除	nodeId
clone_node	复制，可选重新定位	nodeId、x、y、parentId
group_nodes	将节点编组	nodeIds[]、name、parentId
ungroup_nodes	取消编组	nodeId
boolean_operation	联合、相减、相交、排除	nodeIds[]、operation、name
create_mask	剪切蒙版 — maskNode 剪切 targetNode	maskNodeId、targetNodeId、name

布局

工具	描述	关键参数
set_auto_layout	启用／配置自动布局	nodeId、direction、spacing、padding、primaryAxisAlign、counterAxisAlign、primaryAxisSizingMode、counterAxisSizingMode、wrap
set_layout_grid	在画框上设置列／行／网格参考线	nodeId、grids[]（pattern、count、gutterSize、sectionSize、alignment、color）
batch_set_properties	批量更新填充／描边／不透明度／位置／尺寸	operations[]（nodeId + 任意属性子集）

组件

工具	描述	关键参数
create_component	将画框／组转换为组件	nodeId、name
create_instance	放置组件实例	componentId、x、y、parentId
get_components	列出所有本地组件	—
get_library_components	按名称搜索本地组件	query

文档与页面

工具	描述	关键参数
get_document_info	文档名称、页面及当前页面的子节点	—
get_selection	当前选中的节点	—
get_node_info	节点完整详情：填充、描边、布局、文本、约束	nodeId
set_focus	将视口滚动至节点并选中该节点	nodeId
find_nodes	按名称和／或类型搜索	query、type、pageId、recursive
get_page_list	所有页面	—
switch_page	激活某个页面	pageId 或 pageName
create_page	创建新页面	name
duplicate_frame_to_page	将节点复制到另一个页面	nodeId、targetPageId、x、y

节点注册表

工具	描述	关键参数
register_node	为节点 ID 保存命名别名（保存在文档中）	alias、nodeId
resolve_node	按别名查找节点 ID	alias

颜色注册表

工具	描述	关键参数
register_color	将命名颜色保存到文档调色板（0–1）	alias、r、g、b、a
resolve_color	按别名查找颜色	alias
list_colors	列出文档中注册的所有颜色	—

样式与字体

工具	描述	关键参数
get_styles	所有本地绘制样式和文本样式	—
apply_style	将文档样式应用到节点	nodeId、styleId、styleType
get_available_fonts	列出可加载字体；按名称筛选	query

导出

工具	描述	关键参数
export_node_as_svg	将节点导出为 SVG 字符串	nodeId
export_node_as_png	导出为 base64 PNG	nodeId、scale（默认值为 2）
screenshot_current_page	将整页导出为 base64 PNG	scale

批处理

工具	描述	关键参数
create_batch	在一次往返中运行多个命令。支持用于链式调用的 $prev.id 和 $results.N.field 令牌。	commands[]（command、params）

---

沙箱兼容性

插件主线程（code.js）在 Figma 受限的 QuickJS 沙箱中运行。UI（ui.html）是普通浏览器环境，不受影响。

构建前运行 bun run lint:plugin，检查 code.src.js 是否存在违规。可通过 ./scripts/install-hooks.sh 安装 pre-commit 钩子。

code.js 中禁止使用的内容

API / 语法	安全替代方案
import / export	将所有依赖内联
x ?? y	(x != null) ? x : y
obj?.prop	obj && obj.prop
{ ...obj } / [ ...arr ]	Object.assign({}, obj) / Array.from(arr)
localStorage	figma.clientStorage
TextDecoder	分块使用 String.fromCharCode
fetch()	主线程中不可用
figma.getNodeById()（同步）	await figma.getNodeByIdAsync()
figma.currentPage = x（同步赋值）	await figma.setCurrentPageAsync(x)
figma.getLocalPaintStyles()（同步）	await figma.getLocalPaintStylesAsync()
figma.getLocalTextStyles()（同步）	await figma.getLocalTextStylesAsync()
未加载页面就调用 figma.root.findAllWithCriteria()	先调用 await figma.loadAllPagesAsync()

SVG 兼容性（create_vector_from_svg）

功能	状态
<rect>、<polygon>、<polyline>、<path>、<circle>、<ellipse>	✅
fill、stroke、stroke-width、stroke-linecap、stroke-linejoin	✅
viewBox、width、height	✅
<defs> 中的 <linearGradient> / <radialGradient>	❌ 已剥离 — 请使用 set_gradient_fill
<filter>、<mask>、<pattern>	❌ 已剥离
<animate>、<animateTransform>	❌ 已剥离
<script>、<foreignObject>	❌ 已剥离
fill="url(#...)" 引用	❌ 已替换为 fill="none"

---

开发

bun install              # install deps
bun run socket           # start relay on :3055
bun run build            # build MCP server → dist/server.js
bun run build:plugin     # build plugin: code.src.js → code.js
bun run lint:plugin      # check code.src.js for sandbox violations
./scripts/install-hooks.sh  # install pre-commit lint hook

插件工作流

1. 编辑 src/figma-plugin/code.src.js
2. bun run lint:plugin — 在构建前检查沙箱违规
3. bun run build:plugin — esbuild 输出 code.js（ES2017）
4. 在 Figma 中关闭并重新打开插件面板，以加载新的 code.js

---

致谢

• Socket 中继（src/socket.ts）改编自 cursor-talk-to-figma-mcp — Copyright (c) 2025 sonnylazuardi，MIT License
• code.src.js 中的 setCharacters 辅助函数改编自同一项目 — Copyright (c) 2025 sonnylazuardi，MIT License

---

许可证

MIT © Working Model — 详见 LICENSE 和 THIRD_PARTY_NOTICES.md。

---

由 Working Model Inc 开发