figjam-mcp

figjam-context-mcp

FigJam ボードを、LLM 向けの出典付きコンテキストに変換するローカル MCP サーバーです。 Figma REST API を通じてボードを読み取り、付箋、テーブル、画像、矢印をクラスターにまとめ、元のノードへのリンク付きで質問に回答します。

公開されているデモボードを対象に実行した際の実際のツール呼び出しと出力から描画されています。使用したのは figjam-context-mcp 0.10.2 と openai/gpt-4.1-mini です。編集には Figma の MCP サーバー（use_figma）を使用しました。

導入理由

ワークショップのボードには調査メモ、決定事項、未解決の質問が記録されていますが、LLM はキャンバスを読み取れません。スクリーンショットや PDF エクスポートでは、テーブル、矢印の向き、出典へのリンクが失われます。このサーバーはボードの構造を保持し、回答の出典として元のノードをすべて示します。

Figma の MCP サーバーとの比較

Figma 公式の MCP サーバーは、画像を含む FigJam ボードまたはノードを読み取り（get_figjam）、ボードを編集します（use_figma）。このサーバーは、ワークショップのボードをアシスタントが出典を引用して追跡できるコンテキストに変換します。

• 大きなボードをセクションごとに読み取り、概要、サイズ制限付きのページ、検索機能を提供
• コンパクトな概要には出典 ID を含め、全体の抜粋や回答の引用には Figma リンクを含める
• テーブルを行ごとに読み取り
• ローカルスナップショットを保存し、diff_board で変更内容を確認
• 明示的に設定した認証情報は、キャッシュ、出力、モデルに渡る前に秘匿化
• 設定したビジョンモデルによる画像の説明

2つのサーバーは連携して動作します。上記のデモでは、Figma のサーバーがボードを編集し、こちらのサーバーが変更を報告します。

ツール

ツール	機能	LLM 呼び出し
ingest_board	ボードを読み取り、クラスターにまとめてローカルスナップショットを保存します。再取り込みでは変更のないクラスターを再利用し、focusNodeIds で画像を優先的に解釈するセクションを指定できます。	balanced（デフォルト）および max_quality モードで実行
get_board_context	保存済みのコンテキストを読み取ります。大きなセクションを読み取る際には、コンパクトな出典 ID 行を自動的に使用します。detail: "full" を指定すると、完全な抜粋と Figma リンクを返します。トピック検索とページネーションにも対応しています。	いいえ
answer_from_board	最も関連性の高い抜粋に基づいて、具体的な質問（数値、ステータス、決定事項）に1つ回答します。ノード単位の引用、または証拠不足の結果を返します。ボード全体の要約には適していません。	はい
diff_board	2つのスナップショットを比較し、新規、削除、変更されたクラスター、ノード、テーブルのセル、矢印を示します。	いいえ
diagnose_llm_config	小規模なテキストおよび画像の JSON チェックで、設定済みモデルをテストします。	はい

クイックスタート

Node.js 22.12 以降が必要です。

1. Settings → Security → Personal access tokens で、file_content:read スコープを指定した Figma 個人用アクセストークンを作成します。トークンのアカウントには、ボードへのアクセス権が必要です。
2. 任意：OpenRouter キーを openrouter.ai/keys で作成します。これにより、画像の解釈、answer_from_board、diagnose_llm_config が有効になります。キーを使わない場合は、ingestMode: "max_speed" と get_board_context、diff_board を使用してください。
3. 以下のクライアント別の例を使って、サーバーを追加します。--prefer-online を付けて @latest を指定すると、パッケージのメタデータがキャッシュされていても、起動のたびに npx がレジストリで最新リリースを確認します（npm configuration）。

Claude Code

claude mcp add figjam-context -e FIGMA_ACCESS_TOKEN=your-figma-token -e LLM_BASE_URL=https://openrouter.ai/api/v1 -e LLM_API_KEY=your-openrouter-key -- npx -y --prefer-online figjam-context-mcp@latest

時間のかかる取り込みでは、Claude Code を起動する環境に MCP_TOOL_TIMEOUT=300000 を、サーバー環境に INGEST_BOARD_VISION_BUDGET_MS=270000 を設定し、残りの取り込み処理に約30秒を確保してください（Claude Code environment variables）。

Codex CLI と ChatGPT デスクトップアプリ

~/.codex/config.toml に以下を追加します。アプリ、CLI、IDE 拡張機能では、この設定を共有します（OpenAI MCP の設定）：

[mcp_servers.figjam-context-mcp]
enabled = true
command = "npx"
args = ["-y", "--prefer-online", "figjam-context-mcp@latest"]
startup_timeout_sec = 30
default_tools_approval_mode = "approve"

[mcp_servers.figjam-context-mcp.env]
FIGMA_ACCESS_TOKEN = "your-figma-token"
LLM_BASE_URL = "https://openrouter.ai/api/v1"
LLM_API_KEY = "your-openrouter-key"

default_tools_approval_mode = "approve" を設定しないと、ChatGPT は承認を求めたり、外部に影響を及ぼすツールを中止したりする場合があります。この設定を行うと、ボードの内容がモデルプロバイダーに送信される前にクライアントが確認を求めることはなくなるため、機密性の高いボードでは max_speed を使用し、answer_from_board は避けてください。

取り込みに時間がかかる場合は、[mcp_servers.figjam-context-mcp] の下に tool_timeout_sec = 300 を設定し、その env テーブルに INGEST_BOARD_VISION_BUDGET_MS = "270000" を設定してください。これにより、残りの取り込み処理に約 30 秒を確保できます（OpenAI のタイムアウトオプション）。

GitHub Copilot CLI

~/.copilot/mcp-config.json に以下を追加します （Copilot CLI の MCP 設定）：

{
  "mcpServers": {
    "figjam-context": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      },
      "tools": ["*"]
    }
  }
}

取り込みに時間がかかる場合は、~/.copilot/mcp-config.json のサーバーに "timeout": 300000 を設定し、その env に "INGEST_BOARD_VISION_BUDGET_MS": "270000" を設定してください。これにより、残りの取り込み処理に約 30 秒を確保できます（600000 ms のタイムアウトでテスト済み）。

VS Code

ワークスペースの .vscode/mcp.json に追加するか、プロファイルの MCP: Open User Configuration を開きます。VS Code では servers と type: "stdio" を使用します （VS Code の MCP 設定）：

{
  "servers": {
    "figjam-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      }
    }
  }
}

取り込みに時間がかかる場合は、Local ハーネスを使用し、mcp.json のサーバーごとに "timeout": 300000 を設定し、その env に "INGEST_BOARD_VISION_BUDGET_MS": "270000" を設定してください（タイムアウトより約 30 秒短くなります）。#343135 によると、1.142 でデフォルトとなった Copilot ハーネスのリモート HTTP ツール呼び出しでは、このタイムアウトが無視されて約 180 秒で停止しますが、Local ハーネスではタイムアウトが適用されます。

その他の MCP クライアント

mcpServers を受け付けるクライアントでは、その MCP 設定に以下を追加します：

{
  "mcpServers": {
    "figjam-context": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "figjam-context-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_API_KEY": "your-openrouter-key"
      }
    }
  }
}

クライアントでツールのタイムアウトを設定できる場合は、ドキュメントに記載された設定を使って約 300 秒に延長し、サーバー環境に INGEST_BOARD_VISION_BUDGET_MS=270000 を設定してください。タイムアウトより約 30 秒短い値です。 Cursor ではタイムアウトを設定できません。IDE では約 60 分まで待機しますが、ACP／CLI の呼び出しは進捗があっても 60 秒で停止するため、その経路ではデフォルトの画像予算を維持してください（Cursor のサポート情報）。

次に、たとえば 「https://www.figma.com/board/FILE_KEY/Name を取り込んで、未解決の質問を一覧にしてください。」 のように、ボードの URL を取り込むようアシスタントに依頼します。以降のすべての呼び出しで使う boardId は、その URL に含まれるファイルキーです。ボードを要約するには、アシスタントが ingest_board を呼び出し、続いてパラメーターなしで get_board_context を呼び出します。その最初のページには、最大のセクションの名前と、ページのサイズ制限内に収まる ID 付きのセクション概要が含まれます。その後、nodeIds に ID を指定して、最大のセクションを読み取ります。 大きな nodeIds の読み取りでは、最初の全ページを読み込むと未読の抜粋が残る場合、セクションごとにまとめた短いソース ID の行が自動的に使われます。limit が適用されるのは全体表示の場合のみです。概要では、指定されていても無視されます。テキスト全体とその Figma リンクを読むには、同じ boardId と snapshotId を使い、該当する行の ID を nodeIds に指定して、detail: "full" を設定します。表の行の場合は、表の ID を使います。 セクションに属さない付箋や表などの要素には、outsideSections: true が付きます。

すべての設定：設定。 問題が発生した場合：トラブルシューティング。

仕組み

1. 読み取り。 ingest_board は呼び出しのたびに Figma REST API 経由でボードをダウンロードします。get_board_context と answer_from_board は、新たなリクエストを行わずに保存済みのスナップショットを読み取ります。
2. 正規化。 ノードは、ページやセクションの情報を含むテキスト、テーブルセル、画像、コネクタになります。テーブルは行ごとに読み取られます。行と列はセル ID から取得され、各行が 1 つの抜粋になります。
3. クラスタリング。 近くにあるノードは、回転を考慮した距離に基づいてグループ化されます。グループ間の矢印は、有向関係になります。モデルによるラベルがないクラスタには、そのセクション名が付けられます。また、矢印の端のいずれか、またはその周囲にあるセクション、フレーム、グループのいずれかがページ上にあると、その矢印がコンテキストに表示されます。
4. 解釈。 balanced モードでは、画像を含むクラスタ、またはテキストがまったくない図形に対して、40 秒の予算内でビジョンモデルによる要約を生成します。ただし、短くてもテキストクラスタでは抽出したテキストが保持されます。残り時間が処理に足りる場合にのみクラスタの処理を開始し、未完了のクラスタは次回の取り込み時に続行されます。focusNodeIds を指定すると、指定したセクション、フレーム、ノードの画像が優先されます。max_quality では、1 回の取り込みで 40 秒の画像処理時間内に解釈できるクラスタは数十個程度に限られます（並列リクエスト 3 件で約 300 クラスタのボードを測定した場合、20～35 個）。次回の取り込み時に続きが処理されます。毎回 Tier 1 のファイルダウンロードが発生し、処理順は focusNodeIds で指定します。
5. 提供。 スナップショットはプライベートなローカルキャッシュに保存されます。検索では、質問の単語をより多く含む抜粋が優先されます。get_board_context はキャッシュを検索し（元のテキスト、テーブルの行、名前を対象とする BM25）、answer_from_board は引用付きで回答し、diff_board はスナップショットを比較します。get_board_context の最初のページには、ID 付きのサイズ制限されたセクション概要が含まれます。ページ、セクション、フレーム、グループの ID を nodeIds として渡すと、その中のすべてを読み取れます。1 回の呼び出しで複数の ID を指定すると、リクエスト順に処理されます。既定の detail: "auto" では、複数の異なる ID、または 1 つのコンテナを読み取る際、最初のページをすべて表示すると未読の抜粋が残る場合、コンパクトな概要を使用します。テキストは共通の 50～120 文字のプレフィックスに短縮され、その後に … が付きます。要約はホストが作成します。トピック検索、outsideSections、単一のリーフ／テーブル／セル ID、小さなコンテナでは、全文が表示されます。テキストの content は読みやすいページで、structuredContent は各抜粋を 1 回だけ格納します。概要表示では overview.text（evidence と clusters は空）、全文表示では evidence に格納されます。全文の抜粋で応答から引き継がれるのは snapshotId のみです。chunkIndex がない場合は 0、truncated または modelDerived がない場合は false とし、クラスタからこれらのフラグを引き継ぐことはありません。

モデルとコスト

デフォルトのプリセット student-free は、OpenRouter の無料モデルを使用します。テキストと画像は openrouter/free に送られ、構造化出力に対応した無料モデル（画像の場合は画像にも対応したモデル）が選択されます。無料モデルを使うデフォルト設定はベストエフォートです。無料モデルは変更され、レート制限に達したり、タイムアウトしたりすることがあります。openrouter/free または openrouter/auto へのリクエストがプロバイダーエラーで失敗した場合、ルーターが別のモデルを選択する可能性があるため、もう一度送信されます。画像は、最長辺が最大 1,024 px のモデルに送信されます。それより大きい画像はローカルで縮小されます。

• OpenRouter の無料モデルは、1 分あたり 20 リクエスト、1 日あたり 50 リクエストまで利用できます。10 クレジット以上購入すると、1 日あたり 1,000 リクエストまで利用できます （制限）。
• Figma のリクエスト制限は、シートとプランによって異なります （レート制限）。ファイルのダウンロードと画像のレンダリングは Tier 1 です。有料プランの Dev シートと Full シートでは 1 分あたり 10〜20 リクエスト、View シートと Collab シート、および Starter プランのファイルでは 1 か月あたり最大 20 リクエストです。ingest_board の呼び出しごとにファイルを 1 つダウンロードするため、View シートまたは Collab シートでは、1 か月あたり約 20 回の取り込みが可能です。画像は代わりに画像の塗りから取得されます。これは Tier 2 で、1 分あたり最低 5 リクエスト、取り込み 1 回につき 1 リクエストです。画像のない図面や、単一画像のフォールバックとしてレンダリングが使用されます。レンダリングリクエスト 1 回で最大 18 個のノードを処理できます。max_speed ではどちらも必要ありません。
• LLM_BASE_URL には、OpenAI 互換のエンドポイントを指定できます。有料モデルを使うには、LLM_TEXT_MODELS、LLM_FAST_TEXT_MODELS、LLM_VISION_MODELS を設定します。たとえば、3 つすべてに openai/gpt-4.1-mini を指定できます（プロバイダー料金が適用されます）。
• モデルを変更するたびに diagnose_llm_config を実行してください。合成入力を使って、JSON の応答と画像の理解を確認します。

プライバシー

• サーバーは Figma から読み取りますが、ボードを変更することはありません。
• balanced と max_quality の取り込みでは、ボードのテキストと画像（元画像またはレンダリング画像）が設定済みの LLM プロバイダーに送信されます。answer_from_board では、質問と選択された抜粋が送信されます。get_board_context と diff_board を使う max_speed では、LLM プロバイダーに何も送信されません。
• スナップショットは、お使いのマシン上のユーザーごとのプライベートキャッシュに保存されます。削除するには、キャッシュディレクトリを削除してください。
• Passwort: … や API キーなどの明示的な認証情報は、キャッシュ、ツール出力、LLM プロバイダーに渡される前に編集されます （FIGJAM_MCP_REDACT_CREDENTIALS）。これは安全対策であり、完全な保証ではありません。画像は編集されないため、認証情報をボードに載せないでください。
• トークンはクライアントの環境変数に保存してください。ツールの引数として渡したトークンは、クライアントのログに記録される場合があります。

制限事項

• 画像の解釈に割り当てられる時間は、取り込み 1 回あたりデフォルトで 40 秒です。大きなボードですべての画像クラスターを解釈するには、複数回の取り込みが必要です。
• 取り込みをキャンセルしたクライアントには、たとえば 60 秒のタイムアウト後でも、部分的な結果は返されません。
• 無料モデルの動作はベストエフォートです。引用は回答の出典を示すものであり、結論が正しいことを示すものではありません。
• 検索は語句ベースです。共通する語句のない類義語は一致しません。
• ローカルの stdio のみ対応しています。ホスト型やマルチユーザー型のモードはありません。

測定結果：評価。

開発

git clone https://github.com/ecestnrkl/figjam-mcp.git
cd figjam-mcp
npm ci
cp .env.example .env    # add your tokens
npm run check           # typecheck, tests, build, package validation
npm run package:smoke   # install the packed package and exercise all tools
npm run eval:retrieval  # offline retrieval and diff evaluation
npx --prefer-online @modelcontextprotocol/inspector --config inspector.config.json

CONTRIBUTING.mdと変更履歴を参照してください。

ライセンス

MIT © 2026 ecestnrkl