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 --help、各コマンドのヘルプ、および接続済み MCP サーバーのツールスキーマを参照してください。最新のドキュメントについては、CLI リファレンスとMCP ガイドをご覧ください。

変数の数式

eval 内では、数値の数式には openpencil.setVariableFormula('Spacing', 'large', '{base} * 2') を、ブール値の数式には openpencil.setVariableFormula('State', 'visible', '{viewport} > 1024 and not {loading}') を使用します。ブール値の数式では、and、or、not と数値の比較を使用します。コレクションと変数は事前に作成しておく必要があります。省略可能な 4 番目の引数でモードを名前で指定できます。指定しない場合は、デフォルトのモードが編集されます。この呼び出しは変更前に検証を行い、解決後の値を返します。長さの数式では、保存されているピクセル値を使用します。CSS スタイルシートでは数値の数式が calc() として出力され、デザイントークンファイルでは数式が $extensions に格納され、結果が値として保持されます。

変数は Figma のプラグイン API に準拠しています。figma.variables.getLocalVariables()、createVariable(name, collection, type)、variable.setValueForMode(modeId, value)、および Figma のフィールド名（characters、width、paddingLeft）と型を使う node.setBoundVariable(field, variable) を利用できます。ペイントカラーは figma.variables.setBoundVariableForPaint でバインドします。レイヤーパネルと同じ方法でバインドするには、OpenPencil の名前（text、visible、opacity、fills/0/color）を使って openpencil.bindVariable(node, field, variable) と openpencil.unbindVariable(node, field) を使用します。テキストコンテンツにはテキスト変数または数値変数を指定でき、テキストとして表示されます。表示状態にはブール値変数またはテキスト変数を指定できます。openpencil では、レイアウトとテキスト方向の設定（setLayoutDirection、setTextDirection）、OkHCL ペイントカラーの設定（setFillOkHCL、setStrokeOkHCL）、インスタンススワップの公開（exposeInstanceSwap）、フォントの利用状況の確認（getFontStatus()）も行えます。ブール演算とフラット化には、Figma の figma.union、subtract、intersect、exclude、figma.flatten を使用します。

要件

# CLI
bun add -g @open-pencil/cli

# MCP server used by the desktop app and external MCP clients
bun add -g @open-pencil/mcp

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

よく使うコマンド：

• info — ページ、ノード数、フォントなどのドキュメント概要
• tree — 型とサイズを含む階層を表示
• pages — ページを一覧表示
• node — ID を指定してノードのプロパティを詳しく表示
• selection — 実行中のアプリで現在選択されている項目を表示
• find — 名前または型でノードを検索
• query — ノード検索用の XPath セレクター
• variables — 変数とコレクションを一覧表示
• tokens — 変数を CSS カスタムプロパティのスタイルシート、Tailwind v4 テーマ、または W3C デザイントークンファイル（--format dtcg --out <folder>）として出力
• export — PNG/JPG/WEBP/SVG/PDF/JSX/.fig にエクスポート
• convert — サポートされているドキュメント形式間で変換
• analyze — 色、タイポグラフィ、余白、繰り返しクラスターを分析
• lint — 一貫性、構造、アクセシビリティをチェック
• formats — サポートされているドキュメント形式とエクスポート形式を表示
• eval — Figma Plugin API を使って JavaScript を実行
• tool — アプリモードまたはヘッドレスモードで、シェルから任意の MCP ツールを一覧表示、説明、呼び出し
• documents — 実行中のアプリでドキュメントの一覧表示、オープン、作成、保存、クローズ、アクティブ化
• undo / redo — 実行中のアプリで自分が行った（自動化による）変更を元に戻す／やり直す
• settings — 実行中のアプリのエディター設定を読み取り、変更

検査

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
openpencil tokens design.fig --format tailwind > theme.css
openpencil tokens design.fig --format dtcg --out tokens  # W3C design tokens; import_design_tokens reads them back

検索と 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.pen -f storybook -o src/stories --watch  # stories + design images per component, re-exported on save
openpencil export 'src/**/*.pen' -f storybook --beside  # stories next to each design file
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
openpencil lint design.fig --fix -o fixed.fig     # bind matching color variables, round to whole pixels

MCP と AI チャットでは、lint は fix と suggestions を含む指摘事項を一覧表示します。lint_fix は安全な修正を適用し、各指摘事項の最初の提案を適用します（suggestions: true の場合）。

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

# Style part of a text, and read how it is styled
openpencil eval design.fig -w -c '
  const title = figma.currentPage.findOne(n => n.type === "TEXT" && n.name === "Title");
  title.setRangeFontName(0, 5, { family: "Inter", style: "Bold" });
  title.setRangeFills(0, 5, [{ type: "SOLID", color: { r: 0.9, g: 0.1, b: 0.1 } }]);
  title.getStyledTextSegments(["fontName", "fills"]).map(s => [s.characters, s.fontName.style])
'

テキストスタイルは、Figma の文字単位のモデルに従います。getStyledTextSegments(fields) は実行単位を読み取り、getRange…／setRange… は [start, end) の範囲に対して、フォント、サイズ、塗り、文字間隔、行の高さ、装飾、テキストケース、ハイパーリンク、テキストと塗りのスタイル ID、およびバインドされた変数を読み書きします。また、テキストの fontSize、fontName、fills などは、文字ごとに異なる場合に figma.mixed を返します。値を使用する前に、この状態かどうかを確認してください。すべての場所で、ペイントには Figma の形式を使用します。単色の color はアルファ値を opacity に指定した { r, g, b } で、画像は省略可能な rotation と scalingFactor を含む { type: "IMAGE", imageHash, scaleMode: "FILL" | "FIT" | "CROP" | "TILE" } です。

figma に加えて、スクリプトからは openpencil も利用できます。これは OpenPencil が Figma API に独自のスタイルで追加する機能です。メインコンポーネントは、独自のプロパティ名とスロット名を使って Reka UI コントロールとして動作できます。

openpencil eval design.fig -w -c '
  const set = figma.currentPage.findOne(n => n.type === "COMPONENT_SET" && n.name === "Switch");
  const thumb = set.findOne(n => n.name === "Thumb");
  const behaviour = openpencil.setBehaviour(set, "switch")
    .bindValue("value", "State")      // On/Off guessed from the variant values
    .bindPart("thumb", thumb);        // the frame becomes a slot
  behaviour.states = "Interaction";
  behaviour.missing                    // [] when the control is complete
'

openpencil.behaviourKinds はすべての種類とその値およびパーツを一覧表示します。openpencil.getBehaviour(node) は動作を読み取ります（バリアントの場合は、そのセットの動作を読み取ります）。openpencil.createSlot(frame) はフレームをスロットにします。MCP の set_behaviour、get_behaviour、create_slot ツールも同じ操作を行い、デザイン JSX では Reka の要素名（Switch.Root、Switch.Thumb）を使ってコントロールを記述します。

キャンバスに残されたコメントは、対応可能なレビューのフィードバックです。未解決のコメントを読み、デザインを変更したら、それぞれに返信して解決し、投稿者として自分の名前を指定します。

openpencil eval design.fig -w -c '
  openpencil.getComments({ resolved: false }).map(c => ({ id: c.id, text: c.text, layer: c.node?.name }))
'
# after the change:
openpencil eval design.fig -w -c 'openpencil.getComment("c_…").reply("Title is 24px now", { author: "Claude" }).resolve()'

openpencil.addComment(text, { node, page, x, y, author }) は新しいコメントを残します。MCP では、同じ操作を get_comments、add_comment、reply_to_comment、resolve_comment で行えます。コメントのテキストは Markdown です。

ステータスは、ドキュメント独自のリストに基づいて、セクション、フレーム、コンポーネント、またはインスタンスの状態を示します。リストを読み、準備ができているものを確認して、作業が完了したレイヤーを次の段階に進めます。

openpencil eval design.fig -c 'openpencil.statuses.map(s => s.name)'
openpencil eval design.fig -w -c 'openpencil.setStatus(figma.currentPage.findOne(n => n.name === "Checkout"), "In review")'

openpencil.getStatus(node) はステータスを読み取ります。MCP では、同じ操作を get_statuses と set_status で行えます。

差分

ノードとドキュメントを比較し、パッチを適用します。

openpencil diff create design.fig --from 1:23 --to 1:87       # JSX attribute patch
openpencil diff jsx design.fig --from 1:23 --to 1:87          # JSX structure
openpencil diff show 1:24 design.fig --attributes 'rounded={8}' > fix.diff
openpencil diff apply fix.diff design.fig --dry-run           # fails on stale values
openpencil diff apply fix.diff design.fig --write
openpencil diff visual design.fig --from 1:23 --to 1:87 -o diff.png
openpencil diff files before.fig after.fig                    # exit 1 when different

実行中のアプリを操作

openpencil documents list --json                       # tab IDs, paths, pages
openpencil documents open designs/landing.fig          # new tab; --json returns target.documentId
openpencil documents new --path designs/draft.fig
openpencil documents activate tab-123 --page-id 0:4    # bring a tab to the front
openpencil documents save --document-id tab-123
openpencil documents close --document-id tab-123 --save   # or --discard; fails on unsaved changes otherwise
openpencil undo --document-id tab-123                  # also: redo
openpencil settings get --json
openpencil settings set editing.snapping.pixelGrid false

tool はすべての MCP ツールを公開するため、CLI で専用コマンドだけに制限されることはありません。

openpencil tool list
openpencil tool describe set_fill                      # JSON Schema for the arguments
openpencil tool call set_fill --document-id tab-123 --args '{"id":"0:5","color":"#2563eb"}'
openpencil tool call create_page design.fig --args '{"name":"Icons"}' --write   # headless

構造化データを出力するコマンドは、適切な場合に --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_ROOT=/path/to/files     # explicitly limit filesystem access

openpencil-mcp-http
# or: bunx openpencil-mcp-http

認証はデフォルトで有効になっており、トークンは自動生成されます。明示的に空でないトークンを指定するには OPENPENCIL_MCP_AUTH_TOKEN を設定します。空の値を設定すると認証が無効になります。ブラウザーからのアクセスに CORS が必要な場合は、信頼できるオリジンを OPENPENCIL_MCP_CORS_ORIGIN に設定してください。ワイルドカード CORS（*）と認証の無効化を決して併用しないでください。

CLI は、Windows ではホームディレクトリ、それ以外では現在の作業ディレクトリをファイルシステムのルートとしてデフォルトで使用します。このデフォルトに頼らず、明示的な範囲の狭いディレクトリを OPENPENCIL_MCP_ROOT に設定してください。

MCP ワークフロー

1. ドキュメントを検索または開く — 開いているタブとその ID には list_documents を使用します。有効なファイルシステムルート内で open_file { path } を実行します（list_recent_files には、そこで最近開いたファイルが表示されます）。または new_document {} を使用します。アクティブなタブに依存せず、document_id と page_id を明示的に渡します。ユーザーに表示する必要があるタブは、activate_document { document_id } で前面に表示します。
2. クエリ — get_page_tree、find_nodes、query_nodes、get_node、list_pages、get_current_page。
3. 確認 — get_jsx、diff_jsx、diff_create、diff_visual、describe、export_image、export_svg、export_pdf。
4. 変更 — render、batch_update、update_node、set_fill、set_layout、create_shape、import_svg など。フローチャートを作成するには、Mermaid で記述して import_mermaid { mermaid } を呼び出します。図形とコネクタを手動で配置する代わりに、重なりのない FigJam の図形、セクション、コネクタをレイアウトし、各ノードのレイヤー ID を返します。作成したレイヤーが重なっている場合は、arrange { ids } を呼び出します。レイヤーを互いに離し、それぞれを元の位置の近くに保ちます。arrange は画面をまとめて配置（mode: "pack"）し、図形をそれらをつなぐコネクタに沿ってレイアウトすることもできます（フローは "flow"、階層は "tree"、マインドマップは "radial"、関係マップは "network"）。
5. 保存／エクスポート — save_file、export_image、export_svg、export_pdf、または CLI の export。
6. 閉じる — ワークフローの後、close_file { document_id, unsaved } でドキュメントのタブを閉じます。未保存の変更がある場合、unsaved が "save" または "discard" でなければ失敗します。自動化によってアプリ内で確認が求められることはありません。

自分が加えた変更を元に戻すには undo、やり直すには redo { document_id } を使用します。エディターでユーザーが最後の操作を行った場合、これらのコマンドは拒否されます。その制限を回避しないでください。get_settings と update_settings { settings } では、テーマ、言語、スナップなどのエディター設定を読み取って変更できます。認証情報、モデル、ツールへのアクセスは公開されません。

ブラウザー内蔵 WebMCP（実験的）

WebMCP はデフォルトでオフになっています。Settings → MCP → WebMCP で、読み取り専用ツールには Inspect、範囲を限定した変更には Edit を選択します。これらの設定はローカル MCP の設定とは独立しています。対応ブラウザーでは、MCP サーバーへの接続なしに、OpenPencil ワークスペースから document.modelContext を通じて、既存のレイヤーやプロパティ、変数の確認と、取り消し可能な編集を直接実行できます。このブラウザー向け機能は個別に確認してください。構造の作成／削除、任意の JS／JSX の実行、外部アセット、ファイルシステム操作、認証情報は対象外です。

呼び出しではアクティブなドキュメント／ページが対象になります。キャンセルすると編集の開始は防げますが、すでに確定した編集は元に戻りません。元に戻すにはエディターの取り消し機能を使用してください。アトミックな編集では、これらの同じツールをアプリの AI／MCP 経由で実行する場合も含め、ノードと変数の合計が 10,000 個以下である必要があります。対象範囲とブラウザー要件については、WebMCP ガイドをご覧ください。

ツールの検出

ユーザーは、Built-in AI のツール設定とは独立して、Settings → Tool access → Local MCP でローカルサーバーのツールを設定します。ローカル MCP の変更を反映するには、サーバーの再起動と stdio クライアントの再接続が必要です。内蔵 AI の変更は次のメッセージから適用されます。ACP エージェントと Pi エージェントは、直接モデルを使う AI ツールの選択ではなく、MCP の機能を使用します。ツールの切り替えはサンドボックスではありません。有効にしたスクリプトツールは、専用ツールが無効になっていても、そのツールで実行できる操作を引き続き実行できます。

利用可能なツールとその引数は、接続されたサーバーまたはブラウザーから確認してください。利用可否はバージョンやモードによって異なります。各ツールのスキーマと実行／公開に関するメタデータが正式な情報です。数値入力は数値または数値文字列を一貫して受け付けますが、有限でない値は拒否されます。固定のツール数や、コピーした一覧を前提にしないでください。

ツールの利用可否はサーバーモードによって異なる場合があります。open_file、save_file、ディスクに書き込むエクスポート先のパスは、有効なファイルシステムルートの範囲内に限定されます。OPENPENCIL_MCP_ROOT で明示的に設定してください。

エージェント向けの主なツール

• query_nodes — XPath セレクターを使って、ツリー全体を取得せずに特定のノードを検索します。
• get_jsx — 任意のノードを、render が受け付ける形式の JSX として調べます。
• diff_jsx / diff_create — 2 つのノードを JSX の行差分、または適用可能な JSX 属性のパッチとして比較します。diff_show は属性設定をプレビューし、diff_apply はノードが引き続きパッチと一致する場合にのみパッチを適用します。
• diff_visual — レンダリングされた 2 つのノード間のピクセル差分を表示します。編集によって意図した領域だけが変更されたことを確認するために使います。
• describe — 役割、視覚スタイル、レイアウト、デザイン上の問題を意味的に分析します。
• batch_update — 複数のノードを効率的に更新します。
• export_image / export_svg / export_pdf — 視覚的な確認や成果物の作成に使います。
• viewport_zoom_to_fit / viewport_set / viewport_get — ユーザーから表示を求められた場合にのみ、ユーザーの表示領域を移動します。
• get_codegen_prompt — OpenPencil の現在の JSX／コード生成ガイダンスを取得します。
• undo / redo — 最新の変更を取り消す、またはやり直します。ユーザーの編集には手を加えません。
• list_documents / activate_document — 開いているタブを確認し、作業対象のタブを表示します。

JSX のレンダリング

JSX デザインを作成または変更する前に、デザイン作成ガイドをお読みください。この同梱リファレンスは、Core の作成ガイダンス、テスト済みの例、レンダラーのメタデータをもとに生成されています。チャットやコード生成プロンプトで使われるものと同じリファレンスです。

JSX 文字列には render ツールを使います。インストール済みの eval 環境で公開されている API だけを使ってください。ネイティブライブラリのエクスポートは、スクリプトのグローバルとして自動的に使えるわけではありません。接続先サーバーの get_codegen_prompt で、そのバージョンのコード生成および作成ガイダンスを確認できます。

ヒント

• 実行中の OpenPencil エディターで開いているドキュメントを操作する場合は、ファイルパスを省略してください。
• ドキュメントを把握するには、まず info または get_page_tree を使います。
• 大きなファイルで出力が多くなりすぎないように、tree --depth 2 または query_nodes を使います。
• 視覚的な確認をすばやく行うには、--node を指定して特定のノードをエクスポートします。
• 変更後は export_image を使って、視覚的な品質を確認します。
• 実行中のエディターでは、各 MCP セッションが、ツールが操作したレイヤー上のエージェントとして表示されます。ユーザーが「エージェントを追跡」を有効にしている場合は、作業中のエージェントに合わせて表示が追従します。ユーザーから表示を求められない限り、ユーザーの選択範囲や表示位置はそのままにしてください。
• 似た色を見つけるには analyze colors --similar を使います。
• 専用の CLI コマンドがない MCP ツールには openpencil tool call を使い、ツールでカバーされていない Figma Plugin API の操作には eval を使います。
• CLI の出力をスクリプトに渡す場合は、--json を使います。
• アプリモードでは、eval と MCP による変更がエディターにリアルタイムで反映されます。