Back to Details

open-pencil

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenPencil

OpenPencil

CLI and MCP server for .fig design files. Two modes of operation:
  • App mode — connect to the running OpenPencil editor (omit the file argument)
  • Headless mode — work with .fig files directly (pass a file path)
bash
undefined
用于处理.fig设计文件的CLI和MCP服务器，支持两种运行模式：
  • 应用模式 —— 连接到运行中的OpenPencil编辑器（无需传入文件参数）
  • 无头模式 —— 直接处理本地.fig文件（传入文件路径即可）
bash
undefined

App mode — operates on the document open in the editor

应用模式 —— 对编辑器中打开的文档执行操作

bun open-pencil tree
bun open-pencil tree

Headless mode — operates on a .fig file

无头模式 —— 对本地.fig文件执行操作

bun open-pencil tree design.fig

The app exposes an automation bridge on `http://127.0.0.1:7600` when running. The CLI auto-connects to it when no file path is provided.
bun open-pencil tree design.fig

应用运行时会在`http://127.0.0.1:7600`暴露自动化桥接接口，未指定文件路径时CLI会自动连接到该接口。

CLI Commands

CLI 命令

Inspect

查看

bash
undefined
bash
undefined

Document overview — pages, node counts, fonts

文档概览 —— 包含页面、节点数量、字体信息

bun open-pencil info design.fig
bun open-pencil info design.fig

Node tree — shows hierarchy with types and sizes

节点树 —— 展示层级结构、节点类型和尺寸

bun open-pencil tree design.fig bun open-pencil tree --page "Components" --depth 3 # app mode, specific page
bun open-pencil tree design.fig bun open-pencil tree --page "Components" --depth 3 # 应用模式下查看指定页面，深度为3

List pages

列出所有页面

bun open-pencil pages design.fig
bun open-pencil pages design.fig

Detailed node properties — fills, strokes, effects, layout, text

节点详细属性 —— 填充、描边、效果、布局、文本信息

bun open-pencil node design.fig --id 1:23 bun open-pencil node --id 1:23 # app mode
bun open-pencil node design.fig --id 1:23 bun open-pencil node --id 1:23 # 应用模式

List design variables and collections

列出设计变量和变量集合

bun open-pencil variables design.fig bun open-pencil variables --collection "Colors" --type COLOR
undefined
bun open-pencil variables design.fig bun open-pencil variables --collection "Colors" --type COLOR
undefined

Search

搜索

bash
undefined
bash
undefined

Find by name (partial match, case-insensitive)

按名称搜索（部分匹配，不区分大小写）

bun open-pencil find design.fig --name "Button"
bun open-pencil find design.fig --name "Button"

Find by type

按类型搜索

bun open-pencil find --type FRAME # app mode bun open-pencil find design.fig --type TEXT --page "Home"
bun open-pencil find --type FRAME # 应用模式 bun open-pencil find design.fig --type TEXT --page "Home"

Combine filters

组合筛选条件

bun open-pencil find design.fig --name "Card" --type COMPONENT --limit 50

Node types: `FRAME`, `TEXT`, `RECTANGLE`, `ELLIPSE`, `VECTOR`, `GROUP`, `COMPONENT`, `COMPONENT_SET`, `INSTANCE`, `SECTION`, `LINE`, `STAR`, `POLYGON`, `SLICE`, `BOOLEAN_OPERATION`
bun open-pencil find design.fig --name "Card" --type COMPONENT --limit 50

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

Export

导出

bash
undefined
bash
undefined

PNG (default)

PNG格式（默认）

bun open-pencil export design.fig -o hero.png bun open-pencil export -o hero.png # app mode — exports from running editor
bun open-pencil export design.fig -o hero.png bun open-pencil export -o hero.png # 应用模式 —— 从运行中的编辑器导出

Specific node at 2x

导出指定节点，2倍分辨率

bun open-pencil export design.fig --node 1:23 -s 2 -o button@2x.png
bun open-pencil export design.fig --node 1:23 -s 2 -o button@2x.png

JPG with quality

指定质量导出JPG

bun open-pencil export design.fig -f jpg -q 85 -o preview.jpg
bun open-pencil export design.fig -f jpg -q 85 -o preview.jpg

SVG

SVG格式

bun open-pencil export design.fig -f svg --node 1:23 -o icon.svg
bun open-pencil export design.fig -f svg --node 1:23 -o icon.svg

JSX (OpenPencil format — renderable back into .fig)

JSX格式（OpenPencil格式 —— 可重新渲染回.fig文件）

bun open-pencil export design.fig -f jsx -o component.jsx
bun open-pencil export design.fig -f jsx -o component.jsx

JSX (Tailwind — React component with Tailwind classes)

JSX格式（Tailwind风格 —— 带Tailwind类的React组件）

bun open-pencil export design.fig -f jsx --style tailwind -o component.tsx
bun open-pencil export design.fig -f jsx --style tailwind -o component.tsx

Page thumbnail

页面缩略图

bun open-pencil export design.fig --thumbnail --width 1920 --height 1080
bun open-pencil export design.fig --thumbnail --width 1920 --height 1080

Specific page

导出指定页面

bun open-pencil export --page "Components" -o components.png
undefined
bun open-pencil export --page "Components" -o components.png
undefined

Analyze

分析

bash
undefined
bash
undefined

Color palette — usage frequency, similar colors

调色板分析 —— 包含使用频率、相似色信息

bun open-pencil analyze colors design.fig bun open-pencil analyze colors --similar --threshold 10 # app mode
bun open-pencil analyze colors design.fig bun open-pencil analyze colors --similar --threshold 10 # 应用模式

Typography — font families, sizes, weights

排版分析 —— 包含字体族、字号、字重信息

bun open-pencil analyze typography design.fig --group-by size
bun open-pencil analyze typography design.fig --group-by size

Spacing — gap and padding values, grid compliance

间距分析 —— 包含间距、内边距值、栅格合规性

bun open-pencil analyze spacing design.fig --grid 8
bun open-pencil analyze spacing design.fig --grid 8

Clusters — repeated patterns that could be components

组件簇分析 —— 可识别可转化为组件的重复模式

bun open-pencil analyze clusters design.fig --min-count 3
undefined
bun open-pencil analyze clusters design.fig --min-count 3
undefined

Eval (Figma Plugin API)

执行（Figma Plugin API）

Execute JavaScript against the document using the full Figma Plugin API:
bash
undefined
可通过完整的Figma Plugin API对文档执行JavaScript代码：
bash
undefined

Read-only — query the document

只读模式 —— 查询文档信息

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

App mode — modifies the live document in the editor

应用模式 —— 实时修改编辑器中的文档

bun open-pencil eval -c ' const buttons = figma.currentPage.findAll(n => n.name === "Button"); buttons.forEach(b => { b.cornerRadius = 8 }); buttons.length + " buttons updated" '
bun open-pencil 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 file

修改后保存到原文件

bun open-pencil eval design.fig -w -c ' const texts = figma.currentPage.findAll(n => n.type === "TEXT"); texts.forEach(t => { t.fontSize = 16 }); '
bun open-pencil 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

保存为新文件

bun open-pencil eval design.fig -o modified.fig -c '...'
bun open-pencil eval design.fig -o modified.fig -c '...'

Read code from stdin

从标准输入读取代码

echo 'figma.currentPage.children.map(n => n.name)' | bun open-pencil eval design.fig --stdin

The eval environment provides `figma` with the Figma Plugin API: `figma.currentPage`, `figma.createFrame()`, `figma.createText()`, `figma.getNodeById()`, etc.
echo 'figma.currentPage.children.map(n => n.name)' | bun open-pencil eval design.fig --stdin

执行环境提供了完整Figma Plugin API的`figma`对象：支持`figma.currentPage`、`figma.createFrame()`、`figma.createText()`、`figma.getNodeById()`等方法。

JSON Output

JSON输出

Every command supports 
--json
for machine-readable output:
bash
bun open-pencil info design.fig --json
bun open-pencil find --name "Button" --json  # app mode
bun open-pencil analyze colors design.fig --json
所有命令都支持
--json
参数输出机器可读的格式：
bash
bun open-pencil info design.fig --json
bun open-pencil find --name "Button" --json  # 应用模式
bun open-pencil analyze colors design.fig --json

MCP Server

MCP服务器

Stdio (Claude Desktop, Cursor)

标准输入输出（适配Claude Desktop、Cursor）

Add to your MCP config:
json
{
  "mcpServers": {
    "open-pencil": {
      "command": "npx",
      "args": ["openpencil-mcp"]
    }
  }
}
添加到你的MCP配置中：
json
{
  "mcpServers": {
    "open-pencil": {
      "command": "npx",
      "args": ["openpencil-mcp"]
    }
  }
}

HTTP (multi-session, remote)

HTTP模式（多会话、远程访问）

bash
export PORT=3100
export OPENPENCIL_MCP_AUTH_TOKEN=secret       # optional auth
export OPENPENCIL_MCP_CORS_ORIGIN="*"         # optional CORS
export OPENPENCIL_MCP_ROOT=/path/to/files     # restrict file access

npx openpencil-mcp-http
bash
export PORT=3100
export OPENPENCIL_MCP_AUTH_TOKEN=secret       # 可选身份验证
export OPENPENCIL_MCP_CORS_ORIGIN="*"         # 可选CORS配置
export OPENPENCIL_MCP_ROOT=/path/to/files     # 限制文件访问路径

npx openpencil-mcp-http

MCP Workflow

MCP工作流

  1. Open a file — 
    open_file { path: "/path/to/design.fig" }
    or 
    new_document {}
  2. Query — 
    get_page_tree
    , 
    find_nodes
    , 
    get_node
    , 
    list_pages
    , etc.
  3. Modify — 
    render
    (JSX), 
    set_fill
    , 
    set_layout
    , 
    create_shape
    , etc.
  4. Save — 
    save_file { path: "/path/to/output.fig" }
  1. 打开文件 —— 
    open_file { path: "/path/to/design.fig" }
    或 
    new_document {}
  2. 查询 —— 
    get_page_tree
    、
    find_nodes
    、
    get_node
    、
    list_pages
    等
  3. 修改 —— 
    render
    （JSX）、
    set_fill
    、
    set_layout
    、
    create_shape
    等
  4. 保存 —— 
    save_file { path: "/path/to/output.fig" }

MCP Tools (86 total)

MCP工具（共86个）

Read (11): 
get_selection
, 
get_page_tree
, 
get_node
, 
find_nodes
, 
get_components
, 
list_pages
, 
switch_page
, 
get_current_page
, 
page_bounds
, 
select_nodes
, 
list_fonts
Create (7): 
create_shape
, 
render
, 
create_component
, 
create_instance
, 
create_page
, 
create_vector
, 
create_slice
Modify (19): 
set_fill
, 
set_stroke
, 
set_effects
, 
update_node
, 
set_layout
, 
set_constraints
, 
set_rotation
, 
set_opacity
, 
set_radius
, 
set_min_max
, 
set_text
, 
set_font
, 
set_font_range
, 
set_text_resize
, 
set_visible
, 
set_blend
, 
set_locked
, 
set_stroke_align
, 
set_text_properties
, 
set_layout_child
Structure (16): 
delete_node
, 
clone_node
, 
rename_node
, 
reparent_node
, 
group_nodes
, 
ungroup_node
, 
flatten_nodes
, 
node_to_component
, 
node_bounds
, 
node_move
, 
node_resize
, 
node_ancestors
, 
node_children
, 
node_tree
, 
node_bindings
, 
node_replace_with
, 
arrange_nodes
Variables (11): 
list_variables
, 
list_collections
, 
get_variable
, 
find_variables
, 
create_variable
, 
set_variable
, 
delete_variable
, 
bind_variable
, 
get_collection
, 
create_collection
, 
delete_collection
Vector & Export (13): 
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_image
Analyze (7): 
analyze_colors
, 
analyze_typography
, 
analyze_spacing
, 
analyze_clusters
, 
diff_create
, 
diff_show
, 
eval
File (3): 
open_file
, 
save_file
, 
new_document
读取类（11个）： 
get_selection
、
get_page_tree
、
get_node
、
find_nodes
、
get_components
、
list_pages
、
switch_page
、
get_current_page
、
page_bounds
、
select_nodes
、
list_fonts
创建类（7个）： 
create_shape
、
render
、
create_component
、
create_instance
、
create_page
、
create_vector
、
create_slice
修改类（19个）： 
set_fill
、
set_stroke
、
set_effects
、
update_node
、
set_layout
、
set_constraints
、
set_rotation
、
set_opacity
、
set_radius
、
set_min_max
、
set_text
、
set_font
、
set_font_range
、
set_text_resize
、
set_visible
、
set_blend
、
set_locked
、
set_stroke_align
、
set_text_properties
、
set_layout_child
结构类（16个）： 
delete_node
、
clone_node
、
rename_node
、
reparent_node
、
group_nodes
、
ungroup_node
、
flatten_nodes
、
node_to_component
、
node_bounds
、
node_move
、
node_resize
、
node_ancestors
、
node_children
、
node_tree
、
node_bindings
、
node_replace_with
、
arrange_nodes
变量类（11个）： 
list_variables
、
list_collections
、
get_variable
、
find_variables
、
create_variable
、
set_variable
、
delete_variable
、
bind_variable
、
get_collection
、
create_collection
、
delete_collection
矢量与导出类（13个）： 
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_image
分析类（7个）： 
analyze_colors
、
analyze_typography
、
analyze_spacing
、
analyze_clusters
、
diff_create
、
diff_show
、
eval
文件类（3个）： 
open_file
、
save_file
、
new_document

JSX Rendering (via 
render
tool or 
eval
)

JSX渲染（通过
render
工具或
eval
）

Create entire component trees in one call:
jsx
<Frame name="Card" w={320} h="hug" flex="col" gap={16} p={24} bg="#FFF" rounded={16}>
  <Text size={18} weight="bold">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>
Elements: 
Frame
, 
Rectangle
, 
Ellipse
, 
Text
, 
Line
, 
Star
, 
Polygon
, 
Vector
, 
Group
, 
Instance
Layout shorthands:
PropMeaning
w
, 
h
Width, height (number or 
"hug"
/ 
"fill"
)
flex
"row"
or 
"col"
gap
Item spacing
p
, 
px
, 
py
, 
pt
, 
pr
, 
pb
, 
pl
Padding
justify
"start"
, 
"center"
, 
"end"
, 
"between"
items
"start"
, 
"center"
, 
"end"
bg
Fill color (hex)
rounded
Corner radius
stroke
, 
strokeWidth
Stroke color and weight
opacity
0–1
size
, 
weight
, 
font
, 
color
Text properties
单次调用即可创建完整的组件树：
jsx
<Frame name="Card" w={320} h="hug" flex="col" gap={16} p={24} bg="#FFF" rounded={16}>
  <Text size={18} weight="bold">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
、
Rectangle
、
Ellipse
、
Text
、
Line
、
Star
、
Polygon
、
Vector
、
Group
、
Instance
布局简写属性：
属性含义
w
, 
h
宽度、高度（数值或
"hug"
/
"fill"
）
flex
"row"
（行布局）或
"col"
（列布局）
gap
元素间距
p
, 
px
, 
py
, 
pt
, 
pr
, 
pb
, 
pl
内边距
justify
"start"
、
"center"
、
"end"
、
"between"
items
"start"
、
"center"
、
"end"
bg
填充颜色（十六进制）
rounded
圆角半径
stroke
, 
strokeWidth
描边颜色和宽度
opacity
透明度（0–1）
size
, 
weight
, 
font
, 
color
文本属性

Node IDs

节点ID

Format: 
session:local
(e.g., 
1:23
). Get IDs from 
find
, 
tree
, or 
node
commands.
格式为
会话ID:本地ID
（例如
1:23
），可通过
find
、
tree
或
node
命令获取ID。

Tips

使用提示

  • Omit the file path to work with the document open in the running OpenPencil editor
  • Start with 
    info
    to understand the document structure
  • Use 
    tree --depth 2
    for a quick overview without overwhelming output
  • Use 
    find --type COMPONENT
    to discover reusable components
  • Use 
    analyze colors --similar
    to find near-duplicate colors to merge
  • Export specific nodes with 
    --node
    instead of full pages for faster results
  • The 
    eval
    command gives you the full Figma Plugin API for anything the CLI doesn't cover
  • Use 
    --json
    when piping output to other tools
  • In app mode, 
    eval
    modifications are reflected live in the editor
  • 省略文件路径即可对运行中的OpenPencil编辑器内打开的文档执行操作
  • 推荐先使用
    info
    命令了解文档结构
  • 使用
    tree --depth 2
    可以快速获取概览，避免输出内容过多
  • 使用
    find --type COMPONENT
    可以查找可复用的组件
  • 使用
    analyze colors --similar
    可以查找近似重复的颜色，方便合并统一
  • 导出时使用
    --node
    指定特定节点而非整页导出，速度更快
  • eval
    命令提供了完整的Figma Plugin API，可实现CLI未覆盖的所有功能
  • 当需要将输出管道到其他工具时使用
    --json
    参数
  • 应用模式下，
    eval
    的修改会实时同步到编辑器中