open-pencil

OpenPencil

OpenPencil は、.fig デザインファイルと実行中の OpenPencil エディターに対応する CLI と MCP サーバーを提供します。

次の 2 つのモードを使用できます。

• アプリモード — ファイル引数を省略して、実行中の 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

デスクトップアプリは、@open-pencil/mcp がグローバルにインストールされている場合、本番用の Tauri ビルドで 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 が必要です。

エージェント向け主要ツール

• query_nodes — XPath セレクターを使って、ツリー全体を取得せずに特定のノードを検索します。
• get_jsx — render が受け付ける形式で、任意のノードを JSX として確認します。
• diff_jsx — 編集前に、2 つのノードの構造を比較します。
• 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> の子コンテンツです。Figma API のフィールド名ではなく、design-JSX の props を使用してください。

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

一般的な props：

Prop	意味
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	塗りつぶし色（16 進数）
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 による変更がエディターにリアルタイムで反映されます。