OpenPencil CLI 工具：.fig 设计文件命令行操作与 MCP 服务器 | 设计自动化

open-pencil by open-pencil/skills

250 周安装量

2 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/open-pencil/skills --skill open-pencil

自动化命令行工具设计

🇨🇳中文介绍

OpenPencil

用于 .fig 设计文件的 CLI 和 MCP 服务器。提供两种操作模式：

应用模式 — 连接到正在运行的 OpenPencil 编辑器（省略文件参数）
无头模式 — 直接处理 .fig 文件（传入文件路径）

# 应用模式 — 对编辑器中打开的文档进行操作
bun open-pencil tree

# 无头模式 — 对 .fig 文件进行操作
bun open-pencil tree design.fig

应用运行时会在 http://127.0.0.1:7600 上暴露一个自动化桥接器。当未提供文件路径时，CLI 会自动连接到它。

CLI 命令

检查

# 文档概览 — 页面、节点数量、字体
bun open-pencil info design.fig

# 节点树 — 显示包含类型和大小的层级结构
bun open-pencil tree design.fig
bun open-pencil tree --page "Components" --depth 3  # 应用模式，指定页面

# 列出页面
bun open-pencil pages design.fig

# 详细的节点属性 — 填充、描边、效果、布局、文本
bun open-pencil node design.fig --id 1:23
bun open-pencil node --id 1:23  # 应用模式

# 列出设计变量和集合
bun open-pencil variables design.fig
bun open-pencil variables --collection "Colors" --type COLOR

搜索

# 按名称查找（部分匹配，不区分大小写）
bun open-pencil find design.fig --name "Button"

# 按类型查找
bun open-pencil find --type FRAME                          # 应用模式
bun open-pencil find design.fig --type TEXT --page "Home"

# 组合过滤器
bun open-pencil find design.fig --name "Card" --type COMPONENT --limit 50

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

Eval（Figma 插件 API）

使用完整的 Figma 插件 API 对文档执行 JavaScript：

# 只读 — 查询文档
bun open-pencil eval design.fig -c 'figma.currentPage.findAll(n => n.type === "TEXT").length'

# 应用模式 — 修改编辑器中的实时文档
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 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 -o modified.fig -c '...'

# 从标准输入读取代码
echo 'figma.currentPage.children.map(n => n.name)' | bun open-pencil eval design.fig --stdin

eval 环境提供了带有 Figma 插件 API 的 figma 对象：figma.currentPage, figma.createFrame(), figma.createText(), figma.getNodeById() 等。

每个命令都支持 --json 以获取机器可读的输出：

bun open-pencil info design.fig --json
bun open-pencil find --name "Button" --json  # 应用模式
bun open-pencil analyze colors design.fig --json

Stdio（Claude Desktop, Cursor）

添加到你的 MCP 配置：

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

HTTP（多会话，远程）

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

打开文件 — open_file { path: "/path/to/design.fig" } 或 new_document {}
查询 — get_page_tree, find_nodes, query_nodes, get_node, list_pages 等。
检查 — get_jsx（JSX 视图）, diff_jsx（结构差异）, describe（语义分析）, export_image（视觉截图）
修改 — render（JSX）, set_fill, set_layout, create_shape 等。
保存 — save_file { path: "/path/to/output.fig" }

MCP 工具（总计 94 个）

读取（14）： get_selection, get_page_tree, get_node, find_nodes, query_nodes, get_components, list_pages, switch_page, get_current_page, page_bounds, select_nodes, list_fonts, get_jsx, diff_jsx

创建（7）： create_shape, render, create_component, create_instance, create_page, create_vector, create_slice

修改（20）： 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

结构（17）： 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

矢量与导出（14）： 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

分析与检查（8）： analyze_colors, analyze_typography, analyze_spacing, analyze_clusters, diff_create, diff_show, describe, eval

文件（3）： open_file, save_file, new_document

AI 代理的关键工具

query_nodes — 使用 XPath 选择器查找特定节点，无需获取整个树。对于大型文件至关重要。
get_jsx — 将任何节点视为 JSX（与 render 工具接受的格式相同）。在修改前理解结构非常有用。
diff_jsx — 两个节点之间的统一差异。比较修改前后，或查找相似组件之间的差异。
describe — 语义分析：节点扮演的角色、其视觉样式、布局属性以及潜在的设计问题。
export_image — 将节点渲染为 PNG 并返回。用于在更改后进行视觉验证。

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

在一次调用中创建整个组件树：

<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, Text, Rectangle, Ellipse, Line, Star, Polygon, Group, Section, Component

属性	含义
`w`, `h`	宽度，高度（数字或 `"hug"` / `"fill"`）
`flex`	`"row"` 或 `"col"`
`grid`, `columns`, `rows`	CSS 网格 — 例如 `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`	网格子元素定位

格式：session:local（例如，1:23）。从 find, tree, query, 或 node 命令获取 ID。

省略文件路径以处理正在运行的 OpenPencil 编辑器中打开的文档
从 info 开始以了解文档结构
使用 tree --depth 2 进行快速概览，避免输出过多
使用 query "//COMPONENT" 通过 XPath 发现可重用组件
在大型文件中使用 query_nodes（MCP）精确查找你需要的节点 — 避免获取整个树
在修改节点之前使用 get_jsx 查看其结构
修改设计后，使用 export_image 进行视觉验证
使用 analyze colors --similar 查找需要合并的近似重复颜色
使用 --node 导出特定节点而不是整个页面以获得更快的结果
eval 命令为你提供了完整的 Figma 插件 API，用于处理 CLI 未涵盖的任何操作
将输出传输到其他工具时使用 --json
在应用模式下，eval 修改会实时反映在编辑器中

🇺🇸English

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)

App mode — operates on the document open in the editor

bun open-pencil tree

Headless mode — operates on a .fig file

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.

CLI Commands

Inspect

# Document overview — pages, node counts, fonts
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

# List pages
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

# List design variables and collections
bun open-pencil variables design.fig
bun open-pencil variables --collection "Colors" --type COLOR

Search

# Find by name (partial match, case-insensitive)
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"

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

XPath Query

Find nodes using XPath selectors — filter by type, attributes, and tree structure:

# All frames
bun open-pencil query design.fig "//FRAME"

# Frames narrower than 300px
bun open-pencil query design.fig "//FRAME[@width < 300]"

# Text with "Button" in the name
bun open-pencil query design.fig "//TEXT[contains(@name, 'Button')]"

# Components with auto-layout
bun open-pencil query design.fig "//COMPONENT[@stackMode]"

# Deeply nested — text inside frames inside components
bun open-pencil query design.fig "//COMPONENT//FRAME//TEXT"

# App mode
bun open-pencil query "//FRAME[@width > 1000]"

Node types: FRAME, TEXT, RECTANGLE, ELLIPSE, VECTOR, GROUP, COMPONENT, COMPONENT_SET, INSTANCE, SECTION, LINE, STAR, , ,

Export

# PNG (default)
bun open-pencil export design.fig -o hero.png
bun open-pencil export -o hero.png  # app mode — exports from running editor

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

# JPG with quality
bun open-pencil export design.fig -f jpg -q 85 -o preview.jpg

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

# JSX (OpenPencil format — renderable back into .fig)
bun open-pencil export design.fig -f jsx -o component.jsx

# JSX (Tailwind — React component with Tailwind classes)
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

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

Analyze

# Color palette — usage frequency, similar colors
bun open-pencil analyze colors design.fig
bun open-pencil analyze colors --similar --threshold 10  # app mode

# Typography — font families, sizes, weights
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

# Clusters — repeated patterns that could be components
bun open-pencil analyze clusters design.fig --min-count 3

Eval (Figma Plugin API)

Execute JavaScript against the document using the full Figma Plugin API:

# Read-only — query the document
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"
'

# 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 });
'

# Save to a different file
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.

JSON Output

Every command supports --json for machine-readable output:

bun open-pencil info design.fig --json
bun open-pencil find --name "Button" --json  # app mode
bun open-pencil analyze colors design.fig --json

MCP Server

Stdio (Claude Desktop, Cursor)

Add to your MCP config:

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

HTTP (multi-session, remote)

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

MCP Workflow

Open a file — open_file { path: "/path/to/design.fig" } or new_document {}
Query — get_page_tree, find_nodes, query_nodes, get_node, list_pages, etc.
Inspect — get_jsx (JSX view), diff_jsx (structural diff), describe (semantic analysis), (visual screenshot)

MCP Tools (94 total)

Read (14): get_selection, get_page_tree, get_node, find_nodes, query_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 (20): 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, , , , , , , ,

Structure (17): 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, , , , ,

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 (14): 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, ,

Analyze & Inspect (8): analyze_colors, analyze_typography, analyze_spacing, analyze_clusters, diff_create, diff_show, describe, eval

File (3): open_file, save_file, new_document

Key tools for AI agents

query_nodes — XPath selectors to find specific nodes without fetching the full tree. Essential for large files.
get_jsx — see any node as JSX (same format the render tool accepts). Useful for understanding structure before modifying.
diff_jsx — unified diff between two nodes. Compare before/after, or find differences between similar components.
describe — semantic analysis: what role a node plays, its visual style, layout properties, and potential design issues.
export_image — render a node to PNG and return it. Use for visual verification after making changes.

JSX Rendering (via `render` tool or `eval`)

Create entire component trees in one call:

<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, Text, Rectangle, Ellipse, Line, Star, Polygon, Group, Section, Component

Layout shorthands:

Prop	Meaning
`w`, `h`	Width, height (number or `"hug"` / `"fill"`)
`flex`	`"row"` or `"col"`
`grid`, `columns`,

Node IDs

Format: session:local (e.g., 1:23). Get IDs from find, tree, query, or node commands.

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 query "//COMPONENT" to discover reusable components with XPath
Use query_nodes (MCP) to find exactly the nodes you need in large files — avoids fetching the whole tree
Use get_jsx to see how a node is structured before modifying it
After modifying designs, use export_image to visually verify the result
Use analyze colors --similar to find near-duplicate colors to merge
Export specific nodes with --node instead of full pages for faster results
The command gives you the full Figma Plugin API for anything the CLI doesn't cover

Weekly Installs

250

Repository

open-pencil/skills

GitHub Stars

First Seen

Mar 7, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

codex246

cursor244

cline243

gemini-cli243

kimi-cli243

opencode243

shadcn/ui 框架：React 组件库与 UI 设计系统，Tailwind CSS 最佳实践

51,500 周安装

Modify — render (JSX), set_fill, set_layout, create_shape, etc.

Save — save_file { path: "/path/to/output.fig" }

set_text_properties

Use --json when piping output to other tools

In app mode, eval modifications are reflected live in the editor

OpenPencil CLI 工具：.fig 设计文件命令行操作与 MCP 服务器 | 设计自动化

🇨🇳中文介绍

OpenPencil

CLI 命令

检查

搜索

相关 Skills

XPath 查询

导出

分析

Eval（Figma 插件 API）

JSON 输出

MCP 服务器

Stdio（Claude Desktop, Cursor）

HTTP（多会话，远程）

MCP 工作流

MCP 工具（总计 94 个）

AI 代理的关键工具

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

节点 ID

提示

🇺🇸English

OpenPencil

App mode — operates on the document open in the editor

Headless mode — operates on a .fig file

CLI Commands

Inspect

Search

XPath Query

Export

Analyze

Eval (Figma Plugin API)

JSON Output

MCP Server

Stdio (Claude Desktop, Cursor)

HTTP (multi-session, remote)

MCP Workflow

MCP Tools (94 total)

Key tools for AI agents

JSX Rendering (via render tool or eval)

Node IDs

Tips

最新 Skills

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

JSX Rendering (via `render` tool or `eval`)