network-diagram-mcp

@den.dance/network-diagram-mcp

Model Context Protocol 経由で AI エージェントと連携する、ビジュアルなネットワークトポロジーエディターです。 netViz（netViz Inc.、1990 年 → CA Technologies → 2012 年に提供終了）のオープンソースの後継です。

今すぐ試す → https://map.den.dance/

他とは異なる特長

• ワンクリックの運用ダッシュボード。 ノードカード上の Web ポート（80 / 443 / 8080 / …）をクリックすると、新しいタブでサービスが開きます。SSH / Postgres / Redis のポートをクリックすると、アプリ内の選択画面にインストール済みのクライアント（iTerm / Windows Terminal / psql / DBeaver / redis-cli / RDM / …）が表示され、選んだものが起動します。クリックするたびに選択肢が再検出されるため、新しくインストールしたクライアントもすぐに表示され、気づかないうちに既定のクライアントに固定されることはありません。
• AI エージェントがマップを編集。 44 個の MCP ツールを使って、Claude / Cursor / Claude Desktop のセッションから、図の作成、ノード / ポート / メモの検索、スマートな自動レイアウトの実行、PNG / PDF のエクスポートを行えます。すべて、開いているブラウザータブに話しかけるだけです。
• nmap -oX のインポート。 ネットワークスキャンを実行して XML をエージェントに渡すと、OS フィンガープリントとポートプロファイルからノードの種類（ルーター / スイッチ / ファイアウォール / サーバー / プリンター / …）が自動設定されたマップが作成されます。
• CSV インベントリーのインポート。 資産のスプレッドシートを取り込むと、列（name / ip / type / ports / notes）が自動検出されます（hostname / description などの別名にも対応しています）。
• 運用担当者向けのノードカード。 ノードごとに、サービス名付きの開放ポート、Docker サービス、DNS ドメイン、自由記述のメモを管理できます。エージェントからエンティティを横断して検索できます。
• スマートな自動レイアウト。 力指向（シードによる決定論的な配置）、種類別クラスタリング、接続別クラスタリングに対応しています。
• 複数シート、ローカル優先。 1 つのワークスペースで複数のマップを管理し、すべてのデータを localStorage に保存します。ログインもクラウドも不要です。JSON / PNG / PDF にエクスポートできます。

動作の仕組み

このパッケージはstdio → WebSocket ブリッジです。ローカルで MCP サーバーとして動作し、NetMap のライブブラウザータブが WebSocket 経由で接続します。エージェントは MCP 経由でブリッジにアクセスし、ブリッジが呼び出しをブラウザーに転送すると、ブラウザーが React の状態をリアルタイムで更新します。

LLM agent (Claude Code / Claude Desktop / Cursor)
   │  MCP protocol (stdio)
   ▼
@den.dance/network-diagram-mcp  ←  this package, runs locally
   │  WebSocket ws://localhost:47821
   ▼
NetMap in browser (https://map.den.dance/)  ←  React state updates live

⚠️ NetMap のブラウザータブを開いておく必要があります。 https://map.den.dance/ を開いてください。MCP ブリッジはデフォルトで有効（v1.2+）なので、タブを開くとすぐに接続されます。タブを開いていない場合、ブリッジに接続相手がいないため、すべてのツール呼び出しがタイムアウトします。（無効にするには、Settings → ⚙ → Integrations → AI Agent (MCP) → Enable WebSocket connection を選択します。）

インストール

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "netmap": {
      "command": "npx",
      "args": ["@den.dance/network-diagram-mcp"]
    }
  }
}

Claude Code

claude mcp add netmap -- npx @den.dance/network-diagram-mcp

カスタムポートを使用する場合：

claude mcp add netmap -e NETMAP_MCP_PORT=12345 -- npx @den.dance/network-diagram-mcp

次に https://map.den.dance/ を開きます。ブリッジはデフォルトで有効（v1.2+）です。接続を確認または切り替えるには、Settings → Integrations → AI Agent (MCP) を開いてください。 ブラウザーとサーバーが接続されると、ツールバーに 🟢 MCP online バッジが表示されます。

エージェント側の接続を確認します：

claude mcp list

リストに netmap が表示されます。

環境変数

変数	デフォルト	説明
NETMAP_MCP_PORT	47821	ブリッジが待ち受けるローカル WebSocket ポートです。NetMap の Settings → Integrations → AI Agent (MCP) で設定した URL と一致させる必要があります。

URL プロトコルハンドラーとアプリ内クライアントピッカー（v1.1+、ピッカーは v1.2 以降）

このパッケージには、ssh://、postgres://、redis:// URL のハンドラーを登録する OS レベルのエージェントも含まれています。ブラウザーまたはターミナルでこれらのリンクをクリックすると、エージェントがインストール済みのクライアント（psql / redis-cli / iTerm / Windows Terminal / kitty / DBeaver / TablePlus / RedisInsight / …）を起動します。

NetMap 内（v1.2 以降）： serve デーモンの実行中にノードカード上の SSH / Postgres / Redis ポートボタンをクリックすると、マシンにインストールされているクライアントのアプリ内ピッカーが開き、選択したクライアントが起動します。クリックするたびに検出が再実行されるため、新たにインストールしたクライアントもすぐに表示されます。デーモンが実行されていない場合、ポートのクリックは OS のデフォルト URL ハンドラーにフォールバックします。

マシンごとに一度インストールします。

# Linux:   ~/.local/share/applications/netmap-<scheme>-handler.desktop + xdg-mime
# macOS:   ~/Library/Application Support/NetMap/handlers/NetMap<Scheme>Handler.app + lsregister
# Windows: HKCU\Software\Classes\<scheme>  (per-user, no admin)
npx @den.dance/network-diagram-mcp install --all

その他の CLI サブコマンド：

npx @den.dance/network-diagram-mcp install ssh        # single scheme
npx @den.dance/network-diagram-mcp uninstall postgres # remove registration
npx @den.dance/network-diagram-mcp list               # what's registered (JSON)
npx @den.dance/network-diagram-mcp detect ssh         # which clients are available
npx @den.dance/network-diagram-mcp serve              # daemon: WS + HTTP on :47821

クリック処理にデーモンは不要です。OS がリンクを短時間だけ実行される bin/handler.js プロセスにルーティングし、そのプロセスが URL を解析して、最初にインストール済みと判定されたクライアント（優先順位：CLI → 人気の GUI → クロスプラットフォーム対応の高機能クライアント）を選び、起動します。オプションの serve デーモンは、Bearer トークンで保護された /exec を含む HTTP エンドポイント（/status、/detect、/exec）を追加し、ブラウザー側との連携を可能にします。

引数なしの npx @den.dance/network-diagram-mcp は、引き続き従来の stdio MCP サーバーを実行します（後方互換性のため、Smithery / Claude Desktop のプローブに影響はありません）。

スキームごとの上位 5 クライアント（優先順位順、最初にインストール済みと判定されたものを使用）：

スキーム	クライアント
ssh	iTerm2 → Windows Terminal → GNOME Terminal → Terminal.app → kitty
postgres	psql → TablePlus → DBeaver → Beekeeper Studio → pgAdmin 4
redis	redis-cli → RedisInsight → Another Redis DM → Medis → RDM (legacy)

postgresql:// は postgres のエイリアスです。rediss:// はそのまま維持され、redis-cli --tls を実行します。

利用可能なツール

状態とレイアウト

ツール	説明
map_get_state	すべてのノード、接続、付箋、メモを返す
map_clear	マップ全体を消去する（confirm: true が必要）
map_arrange	シンプルな自動配置（grid または circle レイアウト。接続は無視します）
map_suggest_layout	スマートな自動レイアウト：force（力指向。seed によって決定論的に配置）、cluster-by-type（タイプごとにレーンを作成）、または cluster-by-connection（BFS でコンポーネントをゾーンに配置）

ノード

ツール	説明
map_add_node	ノードを追加する（type、name、ip、x、y）
map_update_node	ID を指定してノードのフィールドを更新する
map_delete_node	ノードとその接続を削除する
map_move_node	ノードを新しい座標に移動する

接続

ツール	説明
map_add_connection	接続を追加する（from_id、to_id、label?、color?）
map_update_connection	接続の label または color を更新する
map_delete_connection	ID を指定して接続を削除する

付箋

ツール	説明
map_add_sticky	付箋を追加する（text、x?、y?、color?）
map_update_sticky	text、color、x、y、w、h を更新する
map_delete_sticky	ID を指定して付箋を削除する
map_move_sticky	付箋を新しい座標に移動する

シート（複数シート）

ツール	説明
map_list_sheets	メタデータとアクティブなシート ID を含む、すべてのシートの一覧を取得する
map_get_sheet_data	シートのノード／接続／付箋を取得する（デフォルト：アクティブなシート）
map_create_sheet	新しい空のシートを作成して切り替える
map_switch_sheet	ID を指定してアクティブなシートを切り替える
map_rename_sheet	シート名を変更する
map_delete_sheet	シートを削除する（confirm: true が必要。最後のシートは削除できません）

ビュー／キャンバス

ツール	説明
map_set_zoom	ズームレベルを設定する（0.1–3.0）
map_set_canvas_offset	キャンバスを絶対ピクセル位置までパンする
map_zoom_to_fit	すべてのノードがビューポートに収まるよう自動調整する

ロック／保護

ツール	説明
map_lock_sheet	シートをロック（locked: true）またはロック解除（locked: false）します。ロックされたシートでは、すべての MCP による変更が拒否され、UI での手動編集も無効になります。

メモと設定

ツール	説明
map_get_notes	シートレベルのメモテキストを取得します
map_set_notes	シートレベルのメモテキストを設定します
map_get_settings	アプリの設定（sshMode、showGrid など）を取得します
map_update_settings	アプリの設定を更新します

検索

ツール	説明
map_find_node	name／ip／type／text でノードのみを対象に構造化フィルターを実行します。簡略化された {id, name, type, ip, x, y} を返します。
map_search	エンティティを横断して全文検索します。ノード（name／ip／notes）、付箋（text）、接続ラベル、ポート（ポート番号＋サービス名）を検索します。任意の types: ["nodes","stickies","connections","ports"] を指定すると、検索範囲を絞り込めます。
map_get_nodes_by_type	単一のタイプに該当するすべてのノードを、すべてのフィールドデータ（ports、dockerServices、domains、ips、notes、parentServer、…）とともに返します。簡略化された map_find_node の結果ではなく、完全なオブジェクトが必要な場合に使用してください。

例 — マップ内のどこにある postgres にも一致する項目を検索します。

// → call
{ "q": "postgres" }

// → result
{
  "nodes":       [{ "id": "n1", "name": "db-primary", "type": "server", "ip": "10.0.0.5" }],
  "stickies":    [{ "id": "s2", "text": "TODO: upgrade postgres 15 → 16" }],
  "connections": [{ "id": "c4", "label": "postgres replication", "from": "n1", "to": "n2" }],
  "ports":       [{ "nodeId": "n1", "nodeName": "db-primary", "port": 5432, "protocol": "tcp", "service": "postgresql" }],
  "total": 4
}

map_search と map_get_nodes_by_type は読み取り専用で、ロックされたシートでも使用できます。

インポート

ツール	説明
map_import_sheet	指定した {nodes, connections, stickies?, notes?} JSON で、アクティブなシートの内容を置き換えます。
map_import_nmap	nmap -oX の出力（または解析済みの hosts[] 配列）を解析し、開いているポートとともにノードを作成します。OS フィンガープリントとポートプロファイルに基づいて、ノードタイプ（ルーター／スイッチ／ファイアウォール／サーバー／プリンター／…）を自動推定します。ノードは平方根グリッド状に自動配置されます。
map_import_csv	CSV からノードをインポートします。ヘッダー行から列（name／ip／type／ports／notes）を自動検出します（hostname／description などの別名も使用できます）。ports フィールドには 22/tcp,80/tcp または数値のみを指定できます。ノードは 6 列のグリッドに配置されます。

例 — nmap による 2 ホストのスキャン結果を、1 回の呼び出しでマップに変換します。

// → call
{
  "xml": "<?xml version=\"1.0\"?>\n<nmaprun>\n  <host>\n    <address addr=\"10.0.0.1\" addrtype=\"ipv4\"/>\n    <hostnames><hostname name=\"web.local\" type=\"user\"/></hostnames>\n    <ports>\n      <port protocol=\"tcp\" portid=\"22\"><state state=\"open\"/><service name=\"ssh\"/></port>\n      <port protocol=\"tcp\" portid=\"80\"><state state=\"open\"/><service name=\"http\"/></port>\n    </ports>\n  </host>\n  <host>\n    <address addr=\"10.0.0.2\" addrtype=\"ipv4\"/>\n    <os><osmatch name=\"Cisco IOS router\" accuracy=\"98\"/></os>\n  </host>\n</nmaprun>"
}

// → result
{ "count": 2, "ids": ["…", "…"] }

ホストデータをすでに解析済みの場合は、xml の代わりに {"hosts": [...]} を指定してください。両方が指定された場合は hosts が優先されます。

例 — CSV のインベントリデータをマップに変換します。

// → call
{
  "csv": "name,ip,type,ports,notes\ndb-primary,10.0.0.5,server,\"22/tcp,5432/tcp\",Postgres 15\nrouter-main,10.0.0.1,router,22/tcp,Edge router"
}

// → result
{ "count": 2, "ids": ["…", "…"] }

標準外のヘッダーの場合は、明示的な columns マッピングを渡してください（-1 は「なし」を意味します）。

{
  "csv":     "Host,Address\nfoo,10.0.0.99",
  "columns": { "name": 0, "ip": 1, "type": -1, "ports": -1, "notes": -1 }
}

map_import_nmap と map_import_csv は変更操作であり、ロックされたシートではブロックされます。

レイアウト

map_suggest_layout は選択したアルゴリズムに従ってすべてのノードを再配置します。結果の形式は次のとおりです。 { ok: true, algorithm, changed: <node count> }。

// Force-directed (organic; reproducible with seed)
{ "algorithm": "force", "iterations": 200, "seed": 42 }

// Group nodes into horizontal lanes by type
{ "algorithm": "cluster-by-type" }

// Place each connected component in its own x-zone
{ "algorithm": "cluster-by-connection" }

力指向アルゴリズムの計算量は反復ごとに O(n²) です。数百個までのノードであれば問題ありませんが、大規模なシーンでは iterations を減らしてください。map_suggest_layout は変更操作であり、ロックされたシートではブロックされます。

エクスポート（JSON／PNG／PDF）

ツール	説明
map_export_sheet	単一のシートを JSON オブジェクトとしてエクスポートします（自動接続も含まれます）。従来のエントリーポイントですが、引き続き使用できます。
map_export	複数形式でエクスポートします。json（オブジェクト）、png、pdf（base64 エンコードされたデータと mimeType）に対応しています。

// JSON
{ "format": "json" }
// → { format: "json", data: { nodes, connections, stickies, notes, auto_connections } }

// PNG (max 30 s; agent must persist the base64 to a file)
{ "format": "png" }
// → { format: "png", filename: "netmap-<sheetId>.png",
//      base64: "iVBORw0KGgoAAAANSUhEUg…",
//      mimeType: "image/png" }

// PDF
{ "format": "pdf" }
// → { format: "pdf", filename: "netmap-<sheetId>.pdf",
//      base64: "JVBERi0xLjQK…",
//      mimeType: "application/pdf" }

PNG／PDF のキャプチャでは、html-to-image と jsPDF を使ってライブワークスペースをレンダリングするため、このツールでは MCP サーバーのコマンドごとのタイムアウトが 30 秒に延長されます。map_export は読み取り専用で、ロックされたシートでも使用できます。

接続ステータスインジケーター

ツールバーの NetMap バージョンの横にバッジが表示されます（クリックすると設定が開きます）。

バッジ	意味
🟢 MCP オンライン	接続済み — エージェントはマップを編集できます
🟡 MCP	サーバーに接続中
🟠 MCP 再試行 N/10	最大 10 回、30 秒間隔で再試行中
🔴 MCP エラー	諦めました — サーバーを起動してから、オフ／オンを切り替えて再試行してください
(バッジなし)	設定で無効になっています

詳細なステータス（URL とヒントを含む）は、Settings → Integrations → AI Agent (MCP) に表示されます。

ソースから実行する（コントリビューター向け）

git clone https://github.com/den-indance/network-diagram-mcp.git
cd network-diagram-mcp
npm install
node index.js

ポートを上書きするには、NETMAP_MCP_PORT=12345 node index.js を実行します。

npm の代わりにローカルビルドを Claude Code に登録します。

claude mcp add netmap-dev -- node /absolute/path/to/network-diagram-mcp/index.js

ライセンス

MIT — LICENSE を参照してください。