network-diagram-mcp

@den.dance/network-diagram-mcp

通过 Model Context Protocol 与 AI Agent 集成的可视化网络拓扑编辑器。 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 Agent 编辑地图。 提供 44 个 MCP 工具——你的 Claude / Cursor / Claude Desktop 会话可以为你构建图表、搜索节点 / 端口 / 备注、运行智能自动布局、导出 PNG / PDF——所有操作都通过与打开的浏览器标签页交互完成。
• 导入 nmap -oX。 运行网络扫描，将 XML 交给 Agent，即可获得根据 OS 指纹和端口配置自动确定节点类型的地图（路由器 / 交换机 / 防火墙 / 服务器 / 打印机 / …）。
• 导入 CSV 资产清单。 导入资产电子表格——自动检测列（名称 / IP / 类型 / 端口 / 备注；也接受 hostname / description 等别名）。
• 面向运维人员的节点卡片。 每个节点都可记录开放端口及服务名称、Docker 服务、DNS 域名和自由格式备注。Agent 可跨实体搜索所有内容。
• 智能自动布局。 支持力导向布局（通过种子实现确定性）、按类型聚类、按连接聚类。
• 多工作表、本地优先。 一个工作区中可包含多张地图，所有数据都存储在 localStorage 中。无需登录或云端服务。可导出 JSON / PNG / PDF。

工作原理

此软件包是一个 stdio → WebSocket 桥接程序。它在本地作为 MCP 服务运行；NetMap 浏览器标签页通过 WebSocket 连接到它。Agent 通过 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 在线徽标。

验证 Agent 端：

claude mcp list

你应该会在列表中看到 netmap。

环境变量

变量	默认值	描述
NETMAP_MCP_PORT	47821	桥接程序监听的本地 WebSocket 端口。必须与 NetMap 的 Settings → Integrations → AI Agent (MCP) 中配置的 URL 匹配。

URL 协议处理程序 + 应用内客户端选择器（v1.1+，选择器自 v1.2 起提供）

此软件包还附带一个操作系统级 Agent，可为 ssh://、 postgres:// 和 redis:// URL 注册处理程序。在浏览器或终端中点击此类链接， Agent 就会启动你已安装的客户端（psql / redis-cli / iTerm / Windows Terminal / kitty / DBeaver / TablePlus / RedisInsight / …）。

**在 NetMap 内（v1.2+）：**当 serve 守护进程正在运行时，点击节点卡片上的 SSH / Postgres / Redis 端口按钮，会打开一个应用内选择器，列出你机器上已安装的客户端， 并启动你选中的客户端——每次点击都会重新检测，因此新安装的客户端会立即显示。 如果守护进程未运行，点击端口会回退到操作系统默认的 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

点击处理无需守护进程——操作系统会将链接路由到一个短暂运行的 bin/handler.js 进程，由它解析 URL，选择第一个已安装的客户端（优先顺序：CLI → 常用 GUI → 跨平台高级工具），并启动该客户端。可选的 serve 守护进程会添加 HTTP 端点（/status、/detect、/exec），供浏览器端集成使用，其中 /exec 受 Bearer 令牌保护。

不带参数运行 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 修改，并在界面中禁用手动编辑。

备注与设置

工具	描述
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	跨实体全文搜索。搜索节点（名称 / IP / 备注）、便签（文本）、连接标签和端口（端口号 + 服务名称）。可选的 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[] 数组），并创建带有开放端口的节点。根据操作系统指纹和端口特征自动推断节点类型（路由器 / 交换机 / 防火墙 / 服务 器 / 打印机 / …）。节点会自动排列成平方根网格。
map_import_csv	从 CSV 导入节点。根据标题行自动检测列（name / ip / type / ports / notes — 接受 hostname / description 等别名）。端口字段可使用 22/tcp,80/tcp 或纯数字。节点按 6 列网格排列。

示例 — 一次调用即可将 2 台主机的 nmap 扫描结果转换为地图：

// → 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": ["…", "…"] }

如果已有解析好的主机数据，请提供 {"hosts": [...]} 而不是 xml — 两者同时提供时，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 s。map_export 为只读工具 — 可用于锁定的工作表。

连接状态指示器

工具栏中的 NetMap 版本旁会显示一个徽标（点击可打开设置）：

徽标	含义
🟢 MCP 在线	已连接 — Agent 可以编辑地图
🟡 MCP	正在连接到服务
🟠 MCP 重试 N/10	正在重试，最多尝试 10 次 × 30 sec
🔴 MCP 错误	已放弃 — 启动服务，然后关闭 / 开启开关以重试
(无徽标)	已在设置中禁用

详细状态（包含 URL 和提示）显示在 设置 → 集成 → 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。

在 Claude Code 中注册本地构建版本，而不是使用 npm：

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

许可证

MIT — 请参阅 LICENSE。