SKILL.md

OpenPencil

Name: open-pencil
Author: open-pencil

OpenPencil provides a CLI and MCP server for .fig design files and the running OpenPencil editor.

Use two modes:

App mode — connect to the running OpenPencil editor by omitting the file argument.

Headless mode — work with .fig files directly by passing 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

Current reference version: OpenPencil 0.12.x. The MCP server exposes 106 tools in 0.12.0.

Requirements

# CLI

bun add -g @open-pencil/cli

# MCP server used by the desktop app and external MCP clients

bun add -g @open-pencil/mcp

The desktop app starts openpencil-mcp-http automatically in production Tauri builds when @open-pencil/mcp is installed globally and exposes automation on:

HTTP/RPC: http://127.0.0.1:7600

WebSocket bridge: ws://127.0.0.1:7601

MCP Streamable HTTP: http://127.0.0.1:7600/mcp

CLI Commands

bun open-pencil --help

Commands in 0.12.x:

info — document overview: pages, node counts, fonts

tree — print hierarchy with types and sizes

pages — list pages

node — detailed node properties by ID

selection — current selection from the running app

find — find nodes by name/type

query — XPath selectors for node search

variables — list variables and collections

export — export PNG/JPG/WEBP/SVG/PDF/JSX/.fig

convert — convert between supported document formats

analyze — colors, typography, spacing, repeated clusters

lint — consistency, structure, and accessibility checks

formats — supported document/export formats

eval — execute JavaScript with the Figma Plugin API

Inspect

bun open-pencil info design.fig

bun open-pencil tree design.fig

bun open-pencil tree --page "Components" --depth 3  # app mode

bun open-pencil pages design.fig

bun open-pencil node design.fig --id 1:23

bun open-pencil node --id 1:23  # app mode

bun open-pencil selection --json

bun open-pencil variables design.fig

bun open-pencil variables --collection "Colors" --type COLOR

Search and XPath query

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

bun open-pencil find --type FRAME                          # app mode

bun open-pencil find design.fig --type TEXT --page "Home"

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

bun open-pencil query design.fig "//FRAME"

bun open-pencil query design.fig "//FRAME[@width < 300]"

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

bun open-pencil query design.fig "//COMPONENT[@stackMode]"

bun open-pencil query design.fig "//COMPONENT//FRAME//TEXT"

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

Common node types: FRAME, TEXT, RECTANGLE, ELLIPSE, VECTOR, GROUP, COMPONENT, COMPONENT_SET, INSTANCE, SECTION, LINE, STAR, POLYGON, SLICE, BOOLEAN_OPERATION.

Export and convert

bun open-pencil export design.fig -o hero.png

bun open-pencil export -o hero.png                         # app mode

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

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

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

bun open-pencil export design.fig -f pdf -o page.pdf

bun open-pencil export design.fig -f fig -o roundtrip.fig

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

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

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

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

bun open-pencil convert design.fig -o design.pen

bun open-pencil formats

Analyze and lint

bun open-pencil analyze colors design.fig

bun open-pencil analyze colors --similar --threshold 10     # app mode

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

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

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

bun open-pencil lint design.fig

bun open-pencil lint design.fig --json

Eval (Figma Plugin API)

Execute JavaScript against the document using a Figma Plugin API-compatible runtime:

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 the same 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

Every command that reports structured data supports --json when appropriate.

MCP Server

Stdio MCP clients

Use Bun by default:

{

  "mcpServers": {

    "open-pencil": {

      "command": "bunx",

      "args": ["openpencil-mcp"]

    }

  }

}

If @open-pencil/mcp is installed globally, direct binaries also work:

{

  "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 workflow

Open/create a document — open_file { path } when OPENPENCIL_MCP_ROOT is configured, or new_document {}.

Query — get_page_tree, find_nodes, query_nodes, get_node, list_pages, get_current_page.

Inspect — get_jsx, diff_jsx, describe, export_image, export_svg, export_pdf.

Modify — render, batch_update, update_node, set_fill, set_layout, create_shape, import_svg, etc.

Save/export — save_file, export_image, export_svg, export_pdf, or CLI export.

MCP Tools in 0.12.0 (106 total)

Read and selection (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

Create and import (12): render, create_shape, create_component, create_instance, create_page, create_vector, create_slice, import_svg, search_icons, insert_icon, fetch_icons, stock_photo

Modify (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

Structure (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

Variables (9): list_variables, list_collections, get_variable, find_variables, create_variable, delete_variable, get_collection, create_collection, delete_collection

Vector and viewport (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

Analyze and generation (9): analyze_colors, analyze_typography, analyze_spacing, analyze_clusters, diff_create, diff_show, design_to_tokens, design_to_component_map, calc

File and prompts (4): save_file, open_file, new_document, get_codegen_prompt

Tool availability can depend on server mode. open_file, save_file, and disk-writing export paths require OPENPENCIL_MCP_ROOT for path scoping.

Key tools for agents

**query_nodes** — XPath selectors to find specific nodes without fetching the full tree.

**get_jsx** — inspect any node as JSX in the same format accepted by render.

**diff_jsx** — compare two nodes structurally before editing.

**describe** — semantic analysis of role, visual style, layout, and design issues.

**batch_update** — apply multiple node updates efficiently.

**export_image / export_svg / export_pdf** — visual verification and deliverables.

**get_codegen_prompt** — retrieve OpenPencil's current JSX/codegen guidance.

JSX Rendering

Use the render tool or eval to create component trees:

<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, Instance.

Common props:

Prop

Meaning

w, h

Width, height (number or "hug" / "fill")

flex

"row" or "col"

grid, columns, rows

CSS Grid, e.g. columns="1fr 200px 1fr"

gap, rowGap, columnGap

Item spacing

p, px, py, pt, pr, pb, pl

Padding

justify

"start", "center", "end", "between"

items

"start", "center", "end", "stretch"

grow

Flex grow factor

bg

Fill color (hex)

rounded, roundedTL/TR/BL/BR

Corner radius

stroke, strokeWidth

Stroke color and weight

opacity

0–1

rotate

Degrees

overflow

"hidden" to clip children

shadow

"offsetX offsetY blur #color"

blur

Layer blur

size, weight, font, color, textAlign

Text properties

colStart, rowStart, colSpan, rowSpan

Grid child positioning

Tips

Omit the file path to work with the document open in the running OpenPencil editor.

Start with info or get_page_tree to understand the document.

Use tree --depth 2 or query_nodes to avoid overwhelming output on large files.

Export specific nodes with --node for faster visual checks.

Use export_image after changes to verify visual quality.

Use analyze colors --similar to find near-duplicate colors.

Use eval for Figma Plugin API operations not covered by a dedicated CLI/MCP tool.

Use --json when piping CLI output to scripts.

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

open-pencil