Network Diagram MCP

@den.dance/network-diagram-mcp

Visual network topology editor with AI agent integration via the Model Context Protocol.

Open-source successor to netViz (netViz Inc., 1990 → CA Technologies → discontinued 2012).

Try it live → https://map.den.dance/

What makes it different

• One-click ops dashboard. Click any web port (80 / 443 / 8080 / …) on a node card to open the service in a new tab. Click an SSH / Postgres / Redis port → in-app picker offers your installed clients (iTerm / Windows Terminal / psql / DBeaver / redis-cli / RDM / …) and launches the one you choose. The picker re-detects every click — newly installed clients show up immediately, never a silent locked-in default.
• AI agents edit the map. 44 MCP tools — your Claude / Cursor / Claude Desktop session can build a diagram for you, search across nodes / ports / notes, run smart auto-layouts, export PNG / PDF — all by talking to the open browser tab.
• `nmap -oX` import. Run a network scan, hand the XML to the agent, get a map with nodes auto-typed from OS fingerprint + port profile (router / switch / firewall / server / printer / …).
• CSV inventory import. Drop in your asset spreadsheet — auto-detects columns (name / ip / type / ports / notes; aliases like hostname / description accepted).
• Operator-grade node cards. Per-node: open ports with service names, Docker services, DNS domains, free-form notes. All searchable cross-entity via the agent.
• Smart auto-layout. Force-directed (deterministic via seed), cluster-by-type, cluster-by-connection.
• Multi-sheet, local-first. Multiple maps in one workspace, everything in localStorage. No login, no cloud. Export JSON / PNG / PDF.

How it works

This package is a stdio → WebSocket bridge. It runs locally as an MCP server; the live NetMap browser tab connects to it over WebSocket. The agent talks to the bridge over MCP; the bridge forwards calls to the browser, which updates React state in real time.

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

⚠️ Requires an open NetMap browser tab. Open https://map.den.dance/ — the MCP bridge is

enabled by default (v1.2+), so the connection comes up as soon as the tab is open. Without an

open tab the bridge has no peer and every tool call will time out. (To opt out:

Settings → ⚙ → Integrations → AI Agent (MCP) → Enable WebSocket connection.)

Install

Claude Desktop

Add to 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

With a custom port:

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

Then open https://map.den.dance/ — the bridge is enabled by default (v1.2+). Settings → Integrations → AI Agent (MCP) if you need to inspect or toggle the connection. The toolbar will show a 🟢 MCP online badge when the browser and server are connected.

Verify the agent side:

claude mcp list

You should see netmap in the list.

Environment variables

URL Protocol Handlers + in-app client picker (v1.1+, picker since v1.2)

This package also ships an OS-level agent that registers handlers for ssh://, postgres://, and redis:// URLs. Click any such link in a browser or terminal and the agent spawns your installed client (psql / redis-cli / iTerm / Windows Terminal / kitty / DBeaver / TablePlus / RedisInsight / …).

Inside NetMap (v1.2+): when the serve daemon is running, clicking an SSH / Postgres / Redis port button on a node card opens an in-app picker of installed clients on your machine and launches the one you pick — every click re-detects, so newly installed clients show up immediately. Without the daemon, port-clicks fall back to the OS default URL handler.

Install once per machine:

# Linux:   ~/.local/share/applications/netmap-<scheme>-handler.desktop + xdg-mime

macOS: ~/Library/Application Support/NetMap/handlers/NetMap Handler.app + lsregister

Windows: HKCU\Software\Classes\ (per-user, no admin)

npx @den.dance/network-diagram-mcp install --all

Other CLI subcommands:

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

Click handling is daemon-less — OS routes the link to a short-lived bin/handler.js process which parses the URL, picks the first installed client (priority order: CLI → popular GUI → cross-platform power), and spawns it. The optional serve daemon adds HTTP endpoints (/status, /detect, /exec) for browser-side integration with a Bearer-token-gated /exec.

npx @den.dance/network-diagram-mcp with no args still runs the original stdio MCP server (back-compat — Smithery / Claude Desktop probes are unaffected).

Top-5 clients per scheme (priority order, first-installed wins):

postgresql:// aliases to postgres; rediss:// is preserved and triggers redis-cli --tls.

Available tools

State & layout

Nodes

Connections

Sticky notes

Sheets (multi-sheet)

View / canvas

Lock / protection

Notes & settings

Search

Example — find everything matching postgres anywhere in the map:

// → 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 and map_get_nodes_by_type are read-only — they work on locked sheets.

Import

Example — turn a 2-host nmap scan into a map in one call:

// → call

{ "xml": "<?xml version=\"1.0\"?>\n \n \n \n \n \n \n \n \n \n \n \n \n \n " }

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

Provide {"hosts": [...]} instead of xml when you already have parsed host data — hosts takes priority when both are given.

Example — turn a CSV inventory snippet into a map: