Excaliwow

@excaliwow/mcp

Excaliwow の Model Context Protocol サーバーです。CLI と同じ公開 REST API（/api/v1）を通じて、AI エージェントが Excaliwow アカウント内の図を作成、読み取り、レンダリング、管理、編集できます。stdio 経由で動作するため、あらゆる MCP クライアント（Claude Desktop、Claude Code など）から npx で起動できます。

公開リポジトリの excaliwow/mcp には、このパッケージの配布メタデータとドキュメントが含まれています。ホストされているアプリケーションのソースコードは公開されていません。

インストール

まず、https://excaliwow.com/app/settings（設定 → 開発者／API トークン）で、read + write の権限を持つパーソナルアクセストークンを発行します。この権限で 18 個中 16 個のツールを利用できます。エージェントに図をゴミ箱へ移動させたり、復元させたりする場合に限り、delete も追加してください（セキュリティに関する注意事項を参照）。EXCALIWOW_TOKEN として渡します。

Claude Code（CLI）

コマンドは 1 つです。--scope local を指定すると、サーバーは自分の設定に保存されるため、コミットしてしまう可能性のあるファイルにトークンが書き込まれることはありません。まずトークンを環境変数に設定してください。これにより、トークンそのものがシェルの履歴に残るのを防げます。--env NAME="$NAME" を指定すると、コマンドラインで値をもう一度入力せずに渡せます。

export EXCALIWOW_TOKEN=excw_pat_…
claude mcp add excaliwow --scope local \
  --env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" \
  -- npx -y @excaliwow/mcp

Claude Desktop（およびその他の JSON 設定を使用するクライアント）

クライアントの設定ファイル（Claude Desktop の claude_desktop_config.json、またはクライアントの MCP 設定など。クライアントの MCP セットアップドキュメントを参照）に追加します。仕様にはバージョンがないため、npx -y を使うと常に最新リリースが起動します。更新のためのバージョン変更は不要で、新しいツールや修正が自動的に利用できるようになります。

{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/mcp"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

サーバーは呼び出しごとに環境変数から EXCALIWOW_TOKEN を読み取ります（@excaliwow/cli も使っていて、excaliwow auth login を実行済みの場合は、保存されたログイン情報を使用します）。トークンがディスクに書き込まれることはありません。

トラブルシューティング

「Not authenticated」／401／エージェントのツール呼び出しが失敗する。 サーバーはトークンがなくても起動します（ツール一覧を表示できるようにするため）。そのため、EXCALIWOW_TOKEN が未設定または無効であっても、エージェントが最初にツールを呼び出すまで問題は表面化しません。トークンなしで起動すると、stderr に EXCALIWOW_TOKEN is not set という警告が 1 行表示されます。トークンを直接確認するには、ヘルスチェックを実行してください。認証付きの読み取りを 1 回実行して、明確な結果（ok、401 — token is invalid or expired、または API に到達できない場合は could not reach <url>）を表示し、対応するコードで終了します（正常終了は 0、トークンの欠落または無効は 1、接続不可は 2）。

npx -y @excaliwow/mcp --health

CLI フラグ

フラグ	効果
--health	トークンと API への到達可能性を確認してから終了します（正常終了は 0、トークンの欠落または無効は 1、接続不可は 2）。
--version	インストールされているバージョンを表示して終了します。
--help	使い方（フラグと環境変数）を表示して終了します。

ツール

安全なエージェント利用を想定した 18 個のツールです。

ツール	機能	内容
generate_diagram	write	高レベルのノード／エッジ DSL から図を作成します（自動レイアウト）。エディターの URL を返します。手早くフローチャートを作成するのに最適です。
create_scene	write	Excalidraw の生のシーンから自由に作成した図を作成します。レイアウト、スタイル、タイポグラフィを完全に制御できます。
read_diagram	read	コンパクトな概要（タイトル＋タイプ別の件数）とレンダリング済み PNG を返します。境界リストを含めるには includeGeometry を指定します。
get_scene	read	編集用に、図の完全な生のシーン（{ elements, appState }）を返します。読み取り → 変更 → regenerate_diagram の順に実行します。
export_diagram	read	保存用に、完全な忠実度のバイトデータ（PNG の base64、または生テキストとしての SVG）をレンダリングします。保持するバイトデータであり、ビジョン画像ではありません。
list_diagrams	read	図をページ単位で取得します（filter: active | trash）。
move_diagram	write	図をフォルダー（またはルート）に移動します。
edit_diagram	write	DSL の断片を追加的にマージします（ノード／エッジの追加、ノードのスタイル／ラベルの更新）。
regenerate_diagram	write	新しい spec（再レイアウト）または生の scene から、同じ ID の図の内容をその場で置き換えます。
trash_diagram	delete	図をゴミ箱にソフト削除します。元に戻せます（restore_diagram を参照）。
restore_diagram	delete	ゴミ箱に移動した図を復元し、元の ID と URL で再び開けるようにします。
lint_diagram	read	図の重なり、ラベルのクリッピング、フレーム外の要素、コントラストの低いテキストをチェックします。
patch_elements	write	要素を指定した差分（追加／更新／移動／サイズ変更／スタイル変更／削除）をその場で適用します。最も低コストな編集方法です。
generate_from_template	write	名前付きレイアウトテンプレート（swimlane、layered-stack、matrix、container-with-children）から図を作成します。
list_icons	read	image 要素と icon-<name> の fileId で埋め込める、厳選されたアイコンを一覧表示します（ID＋ラベル＋カテゴリ）。
list_folders	read	呼び出し元のフォルダー（ID＋名前＋parentId）を一覧表示し、folderId を解決または確認できるようにします。
create_folder	write	図を整理するためのフォルダーを作成します（必要に応じて parentId の下に入れ子にできます）。
rename_diagram	write	図のタイトルのみを変更し、内容と ID／URL はそのままにします。
read_diagram はコンテキストを小さく保つため、概要と画像を返し、シーンの生の JSON は決して返しません。includeGeometry: true を渡すと、ラベルとボックスの衝突やノードの配置ミスを PNG を目視で確認する代わりに、エージェントがプログラムで検出できるよう、コンパクトで上限のある { id, type, label, x, y, w, h } のリスト（x/y は左上）も取得できます。これはシーンから生成されるため、レンダリングに失敗しても含まれます。また、生の要素データのダンプではなく、固定フィールドの小さな概要です。代わりに includeScene: 'compact' を渡すと、要素を指定できる、上限のある投影データが取得できます。これはジオメトリのフィールドをすべて含む上位互換の形式で、スタイル、テキスト、コンテナー／バインディングの参照も含みます（要素あたり ≤17 フィールド）。read_diagram → patch_elements のピンポイント編集ループにおける読み取り側です。
export_diagram はファイルに保存するためのレンダリング済みバイトデータを返します。PNG は base64、SVG は生テキストです。ビジョンモデルが参照する画像ブロックを返す read_diagram とは異なります。MCP サーバーは stdio 経由で動作し、リポジトリに書き込めないため、ファイルシステムにアクセスできるクライアント（例：Claude Code）がバイトデータをデコードして保存します。または、モデルを経由するやり取りを省いて、CLI でディスクに直接ストリーム出力できます。`excaliwow diagrams render -o
docs/architecture.png（または .svg`）を使用します。レンダリング結果が大きすぎてインラインで返せない場合の代替手段にもなります。

trash_diagram / restore_diagram は、delete 機能が必要な元に戻せるペアです。常に登録されていますが、トークンに delete が含まれていない場合は、変更を加えずに明確な insufficient_scope エラーを返すため、read + write トークンでは何もゴミ箱に移動できません。完全削除／消去と、ダイアグラムの一般公開は、意図的にエージェントのツールから除外されています。元に戻せない操作のため、誤った誘導を受けたエージェントがダイアグラムを破壊したり公開したりすることを防ぎます。消去または公開は、ダッシュボードか CLI から行ってください。

2 つの作成方法

generate_diagram は高レベルのノード／エッジ DSL を受け取り、自動でレイアウトします。手早くフローチャートを作成したい場合に使用してください。create_scene は手作業で作成した Excalidraw の生シーンを受け取るため、エージェントが各要素の位置、サイズ、色、線、塗りつぶし、タイポグラフィ、接続をすべて制御できます。凝った、洗練されたカスタムダイアグラムを作成する方法です。要素は簡潔に（id、type、geometry、text、colors）記述し、Excalidraw の定型部分は自動で補完されます。完全に指定された要素（または貼り付けた .excalidraw シーン）は、変更されずに渡されます。凝ったダイアグラムを反復して編集するには、get_scene → 要素を編集 → 編集した scene を指定して regenerate_diagram の順に実行します。

検出用リソース

DSL の文法と実例は generate_diagram ツールの説明に埋め込まれており、完全なリファレンスは MCP リソース excaliwow://dsl/reference として提供されます。凝ったシーンの作成入門と実例は create_scene の説明に含まれており、完全なガイド（すべての要素タイプ、すべてのスタイル設定プロパティ、バインディング、グループ、フレーム、パレット、レイアウト／見栄えのヒューリスティック）は excaliwow://scene/authoring にあります。

環境変数

変数	効果
EXCALIWOW_TOKEN	必須（スタンドアロン）。Bearer PAT。呼び出しごとに読み取られ、このサーバーによってディスクに書き込まれることはありません。
EXCALIWOW_API_URL	API のオリジン。デフォルトは https://excaliwow.com。通常は設定不要です。

要件

Node >= 22.11.0。これは技術上の要件ではなく、サポートポリシー上の最低バージョンです。ここで提供される機能は、Node 22 専用の API を使用していません（コードが使用する最新のランタイム依存機能はグローバルの fetch で、Node 18 から利用できます）。最低バージョンは「最新の LTS」に合わせており、npx -y @excaliwow/mcp が実際にテストした Node ビルドで実行されるようにし、@excaliwow/cli の最低バージョンとも一致させています。MCP クライアントが古い Node のままで、npx がこのサーバーの実行を拒否する場合、その拒否は意図された動作です。バグとして扱わず、Node をアップグレードしてください。

セキュリティに関する注意事項

• コミットするものにトークンを含めないでください。 リポジトリ内に置かれるプロジェクトスコープの設定（コミットされた .mcp.json、または claude mcp add --scope project）では、トークンが Git の履歴に残ります。ユーザースコープまたはローカルスコープの設定（--scope local）を使うか、トークンを直接貼り付ける代わりに環境変数を参照してください。
• コマンドラインでトークンを直接入力すると、シェルの履歴 （~/.zsh_history、~/.bash_history、…）に残り、プロセス一覧にも一時的に表示されます。 export EXCALIWOW_TOKEN=… を一度実行してから、PAT を claude mcp add コマンド自体に貼り付けるのではなく、--env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" で渡すか、シークレットマネージャーから取得してください。
• read + write のみでトークンを発行してください（ゴミ箱への移動／復元を行う場合のみ delete を追加してください）。 18 個のツールのうち 16 個は read + write だけで利用できます。read + write の PAT では、エージェントが誤った指示を受けたとしても、図を公開したり削除したりすることはできません（trash_diagram / restore_diagram は insufficient_scope を返すだけで、何も行いません）。エージェントによる論理削除と復元を可能にしたい場合に限り、delete 権限を追加してください。操作は元に戻せますが、権限の付与は慎重に行ってください。publish（および delete）も付与される、粒度の粗い read-write プリセットではなく、必要な権限を個別に選択してください。
• トークンはアカウントの認証情報です。トークンが保存されるのは MCP クライアントの設定または環境変数のみで、このサーバーには保存されません。これらの設定は、シークレットファイルと同様に取り扱ってください。

サポート

バグを見つけた場合や質問がある場合は、excaliwow.com/docs/mcp をご覧いただくか、excaliwow.com/contact までお問い合わせください。

ライセンス

Apache-2.0 — LICENSE と NOTICE をご覧ください。