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, POLYGON, SLICE, BOOLEAN_OPERATION

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 [email protected]

# 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

1. Open a file — open_file { path: "/path/to/design.fig" } or new_document {}
2. Query — get_page_tree, find_nodes, query_nodes, get_node, list_pages, etc.
3. Inspect — get_jsx (JSX view), diff_jsx (structural diff), describe (semantic analysis), export_image (visual screenshot)
4. Modify — render (JSX), set_fill, set_layout, create_shape, etc.
5. Save — save_file { path: "/path/to/output.fig" }

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, get_jsx, diff_jsx

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, set_font_range, set_text_resize, set_visible, set_blend, set_locked, set_stroke_align, set_text_properties, set_layout_child

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

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
how to use open-pencil
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use open-pencil on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add open-pencil
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/open-pencil/skills --skill open-pencilcopy
The skills CLI fetches open-pencil from GitHub repository open-pencil/skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/open-pencil
Reload or restart Cursor to activate open-pencil. Access the skill through slash commands (e.g., /open-pencil) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?