open-pencil

OpenPencil

OpenPencil 为 .fig 设计文件和运行中的 OpenPencil 编辑器提供 CLI 和 MCP 服务。

支持两种模式：

• 应用模式 — 省略文件参数，即可连接到运行中的 OpenPencil 编辑器。
• 无头模式 — 传入文件路径，直接处理 .fig 文件。

# App mode — operates on the document open in the editor
openpencil tree

# Headless mode — operates on a .fig file
openpencil tree design.fig

当前参考版本：OpenPencil 0.12.x。MCP 服务在 0.12.0 中提供 106 个工具。

要求

# CLI
bun add -g @open-pencil/cli

# MCP server used by the desktop app and external MCP clients
bun add -g @open-pencil/mcp

在生产环境的 Tauri 构建中，如果全局安装了 @open-pencil/mcp，桌面应用会自动启动 openpencil-mcp-http，并在以下地址开放自动化接口：

• HTTP/RPC：http://127.0.0.1:7600
• WebSocket 桥接：ws://127.0.0.1:7601
• MCP Streamable HTTP：http://127.0.0.1:7600/mcp

CLI 命令

openpencil --help

0.12.x 中的命令：

• info — 文档概览：页面、节点数量、字体
• tree — 按类型和大小打印层级结构
• pages — 列出页面
• node — 按 ID 查看节点详细属性
• selection — 获取运行中应用的当前选区
• find — 按名称/类型查找节点
• query — 使用 XPath 选择器搜索节点
• variables — 列出变量和集合
• export — 导出 PNG/JPG/WEBP/SVG/PDF/JSX/.fig
• convert — 在支持的文档格式之间转换
• analyze — 分析颜色、排版、间距和重复簇
• lint — 检查一致性、结构和无障碍性
• formats — 查看支持的文档/导出格式
• eval — 使用 Figma Plugin API 执行 JavaScript

检查

openpencil info design.fig
openpencil tree design.fig
openpencil tree --page "Components" --depth 3  # app mode
openpencil pages design.fig
openpencil node design.fig --id 1:23
openpencil node --id 1:23  # app mode
openpencil selection --json
openpencil variables design.fig
openpencil variables --collection "Colors" --type COLOR

搜索和 XPath 查询

openpencil find design.fig --name "Button"
openpencil find --type FRAME                          # app mode
openpencil find design.fig --type TEXT --page "Home"
openpencil find design.fig --name "Card" --type COMPONENT --limit 50

openpencil query design.fig "//FRAME"
openpencil query design.fig "//FRAME[@width < 300]"
openpencil query design.fig "//TEXT[contains(@name, 'Button')]"
openpencil query design.fig "//COMPONENT[@stackMode]"
openpencil query design.fig "//COMPONENT//FRAME//TEXT"
openpencil query "//FRAME[@width > 1000]"             # app mode

常见节点类型：FRAME、TEXT、RECTANGLE、ELLIPSE、VECTOR、GROUP、COMPONENT、COMPONENT_SET、INSTANCE、SECTION、LINE、STAR、POLYGON、SLICE、BOOLEAN_OPERATION。

导出和转换

openpencil export design.fig -o hero.png
openpencil export -o hero.png                         # app mode
openpencil export design.fig --node 1:23 -s 2 -o [email protected]
openpencil export design.fig -f jpg -q 85 -o preview.jpg
openpencil export design.fig -f svg --node 1:23 -o icon.svg
openpencil export design.fig -f pdf -o page.pdf
openpencil export design.fig -f fig -o roundtrip.fig
openpencil export design.fig -f jsx -o component.jsx
openpencil export design.fig -f jsx --style tailwind -o component.tsx
openpencil export design.fig --thumbnail --width 1920 --height 1080
openpencil export --page "Components" -o components.png

openpencil convert design.fig -o design.pen
openpencil formats

分析和 lint

openpencil analyze colors design.fig
openpencil analyze colors --similar --threshold 10     # app mode
openpencil analyze typography design.fig --group-by size
openpencil analyze spacing design.fig --grid 8
openpencil analyze clusters design.fig --min-count 3
openpencil lint design.fig
openpencil lint design.fig --json

Eval（Figma Plugin API）

使用兼容 Figma Plugin API 的运行时对文档执行 JavaScript：

openpencil eval design.fig -c 'figma.currentPage.findAll(n => n.type === "TEXT").length'

# App mode — modifies the live document in the editor
openpencil eval -c '
  const buttons = figma.currentPage.findAll(n => n.name === "Button");
  buttons.forEach(b => { b.cornerRadius = 8 });
  buttons.length + " buttons updated"
'

# Modify and save to the same file
openpencil eval design.fig -w -c '
  const texts = figma.currentPage.findAll(n => n.type === "TEXT");
  texts.forEach(t => { t.fontSize = 16 });
'

# Save to a different file
openpencil eval design.fig -o modified.fig -c '...'

# Read code from stdin
echo 'figma.currentPage.children.map(n => n.name)' | openpencil eval design.fig --stdin

适用时，每个可报告结构化数据的命令都支持 --json。

MCP 服务

Stdio MCP 客户端

默认使用 Bun：

{
  "mcpServers": {
    "open-pencil": {
      "command": "bunx",
      "args": ["openpencil-mcp"]
    }
  }
}

如果全局安装了 @open-pencil/mcp，也可以直接使用二进制文件：

{
  "mcpServers": {
    "open-pencil": {
      "command": "openpencil-mcp"
    }
  }
}

HTTP / Streamable HTTP

export PORT=7600
export OPENPENCIL_MCP_AUTH_TOKEN=secret       # optional auth for /mcp
export OPENPENCIL_MCP_CORS_ORIGIN="*"         # optional CORS
export OPENPENCIL_MCP_ROOT=/path/to/files     # enables/scopes open_file/save_file paths

openpencil-mcp-http
# or: bunx openpencil-mcp-http

MCP 工作流

1. 打开/创建文档 — 配置了 OPENPENCIL_MCP_ROOT 时使用 open_file { path }，否则使用 new_document {}。
2. 查询 — get_page_tree、find_nodes、query_nodes、get_node、list_pages、get_current_page。
3. 检查 — get_jsx、diff_jsx、describe、export_image、export_svg、export_pdf。
4. 修改 — render、batch_update、update_node、set_fill、set_layout、create_shape、import_svg 等。
5. 导航 — 创建或编辑画布上的可见内容后，调用 select_nodes 和 viewport_zoom_to_fit { id }（或 node_bounds + viewport_set），以便用户在运行中的编辑器中查看结果。
6. 保存/导出 — 使用 save_file、export_image、export_svg、export_pdf 或 CLI export。

0.12.0 中的 MCP 工具（共 106 个）

读取与选择（17 个）： get_selection、get_node、find_nodes、get_page_tree、get_current_page、list_pages、select_nodes、query_nodes、get_components、switch_page、page_bounds、list_fonts、list_available_fonts、get_jsx、diff_jsx、describe、node_tree

创建与导入（12 个）： render、create_shape、create_component、create_instance、create_page、create_vector、create_slice、import_svg、search_icons、insert_icon、fetch_icons、stock_photo

修改（24 个）： update_node、batch_update、set_layout、set_layout_child、set_radius、set_fill、set_stroke、set_text、set_text_properties、set_effects、set_opacity、set_font、set_visible、set_constraints、set_rotation、set_minmax、set_font_range、set_text_resize、set_blend、set_locked、set_stroke_align、set_image_fill、set_variable、bind_variable

结构（16 个）： delete_node、reparent_node、node_resize、clone_node、node_move、rename_node、group_nodes、ungroup_node、flatten_nodes、node_to_component、node_bounds、node_ancestors、node_children、node_bindings、node_replace_with、arrange

变量（9 个）： list_variables、list_collections、get_variable、find_variables、create_variable、delete_variable、get_collection、create_collection、delete_collection

矢量与视口（15 个）： boolean_union、boolean_subtract、boolean_intersect、boolean_exclude、path_get、path_set、path_scale、path_flip、path_move、viewport_get、viewport_set、viewport_zoom_to_fit、export_svg、export_pdf、export_image

分析与生成（9 个）： analyze_colors、analyze_typography、analyze_spacing、analyze_clusters、diff_create、diff_show、design_to_tokens、design_to_component_map、calc

文件与提示词（4 个）： save_file、open_file、new_document、get_codegen_prompt

工具的可用性可能因服务模式而异。open_file、save_file 以及写入磁盘的导出路径需要设置 OPENPENCIL_MCP_ROOT 来限定路径范围。

面向 Agent 的关键工具

• query_nodes — 使用 XPath 选择器查找特定节点，无需获取完整树。
• get_jsx — 以 render 接受的相同格式检查任意节点的 JSX。
• diff_jsx — 在编辑前对两个节点进行结构比较。
• describe — 对角色、视觉风格、布局和设计问题进行语义分析。
• batch_update — 高效地应用多项节点更新。
• export_image / export_svg / export_pdf — 用于视觉验证和交付成果。
• viewport_zoom_to_fit / viewport_set / viewport_get — 让实时编辑器聚焦于创建或编辑的设计。
• get_codegen_prompt — 获取 OpenPencil 当前的 JSX／代码生成指导。

JSX 渲染

使用 render 工具或 eval 创建组件树。如果不确定 JSX 语法，请先调用 get_codegen_prompt。

<Frame name="Card" w={320} h="hug" flex="col" gap={16} p={24} bg="#FFF" rounded={16}>
  <Text size={18} weight="bold" color="#111">Title</Text>
  <Text size={14} color="#666">Description text</Text>
  <Frame flex="row" gap={8}>
    <Frame w={80} h={36} bg="#3B82F6" rounded={8} justify="center" items="center">
      <Text size={14} color="#FFF" weight="600">Action</Text>
    </Frame>
  </Frame>
</Frame>

元素：Frame、Text、Rectangle、Ellipse、Line、Star、Polygon、Group、Section、Component、Instance。

文本内容是 <Text> 的子内容。请使用 design-JSX 属性，而不是 Figma API 字段名称：

<Text size={48} weight="bold" font="Inter" color="#111">Design faster with AI</Text>

常用属性：

属性	含义
w、h	宽度、高度（数字或 "hug" / "fill"）
flex	"row" 或 "col"
grid、columns、rows	CSS Grid，例如 columns="1fr 200px 1fr"
gap、rowGap、columnGap	项目间距
p、px、py、pt、pr、pb、pl	内边距
justify	"start"、"center"、"end"、"between"
items	"start"、"center"、"end"、"stretch"
grow	Flex 增长因子
bg	填充颜色（十六进制）
rounded、roundedTL/TR/BL/BR	圆角半径
stroke、strokeWidth	描边颜色和粗细
opacity	0–1
rotate	角度
overflow	"hidden"，用于裁剪子项
shadow	"offsetX offsetY blur #color"
blur	图层模糊
size、weight、font、color、textAlign	文本属性
colStart、rowStart、colSpan、rowSpan	网格子项定位

提示

• 省略文件路径，即可操作当前运行中的 OpenPencil 编辑器所打开的文档。
• 使用 info 或 get_page_tree 开始了解文档。
• 对于较大的文件，使用 tree --depth 2 或 query_nodes，避免输出过多内容。
• 使用 --node 导出指定节点，以便更快地检查视觉效果。
• 更改后使用 export_image 验证视觉质量。
• 创建可见设计后，选中它并将编辑器缩放至该设计：先运行 select_nodes { ids: [id] }，再运行 viewport_zoom_to_fit { id }。
• 如果客户端不支持缩放至适合大小，请使用 node_bounds 计算中心点，然后调用 viewport_set { x, y, zoom }。
• 使用 analyze colors --similar 查找近似重复的颜色。
• 对于专用 CLI/MCP 工具未涵盖的 Figma Plugin API 操作，请使用 eval。
• 将 CLI 输出传递给脚本时使用 --json。
• 在应用模式下，eval 和 MCP 修改会实时反映在编辑器中。