NDS MapViewer CLI

Visualize NDS.Live, NDS.Classic, and GeoJSON map data on a deck.gl-based map with live style editing, feature inspection, and layer management — all from a single mapviewer command. No container-runtime knowledge required.

Beta — This Python package is in early development. The CLI interface may change between releases. Feedback and bug reports are welcome via the NDS developer portal.

Full documentation: https://developer.nds.live/tools/mapviewer

Features

• Map visualization powered by deck.gl via erdblick
• Multiple data formats — NDS.Live, GeoJSON, NDS.Classic (member edition)
• Live style editing — modify map styles in real time with YAML-based rules
• Feature inspection — click any map feature to explore its attributes and relations
• Local and remote data — view SmartLayer folders, FileStore files, or remote services, as tile or object maps
• Guided setup — interactive wizard for creating data source configs
• Config management — save, switch, and delete configs from the RunScreen (c)

Getting Started

The recommended way to set up your NDS.Live environment (credentials, container registry, pip index) is via ndslive-setup:

pip install ndslive-setup
ndslive-setup

This interactive wizard configures everything you need in one step, including installing nds-mapviewer.

Either Docker or Podman works as the container runtime — Podman is a free alternative if you cannot use Docker Desktop's commercial license.

Usage

mapviewer                         # HomeScreen (or auto-loads ~/.nds/config.yaml)

mapviewer /path/to/data.ndslive   # View a local FileStore (tile or object map)
mapviewer /path/to/folder         # View a local SmartLayer folder
mapviewer /path/to/geojson/       # View a GeoJSON folder
mapviewer https://host/openapi.json  # Connect to a remote service (unauthenticated)
mapviewer --demo                  # Try it with NDS Islands sample data

mapviewer mywork                  # Load a saved config by name
mapviewer /path/a.ndslive /path/b # Multiple sources at once

mapviewer --demo --debug          # Enable debug logging in the container
mapviewer --demo --env KEY=VALUE  # Set a custom container env var (repeatable)
mapviewer --demo --network host   # Run the container on the host network

All commands accept -e community|member and -i VERSION.

Tile and object maps

Local sources are detected as tile or object maps: a .ndslive filestore with an objectTable, or a SmartLayer folder with an objects/ directory, becomes a SmartLayerObjectService; everything else a SmartLayerTileService. Object maps need MapViewer image 2026.4.2 or newer.

Remote service URLs

A source can be an http(s) service URL (e.g. mapviewer https://my-host/openapi.json), which is turned into a SmartLayerTileService, or a SmartLayerObjectService when its OpenAPI spec offers getObjectByReference. If the spec cannot be fetched, the tile service is assumed. The bare-URL form configures no authentication — for protected services, proxy them through ndslive-server or declare the service in a config.yaml with an http-settings block (api-key, basic, bearer, OAuth2, proxy).

For a service running on your own machine, use localhost/127.0.0.1 (e.g. mapviewer http://127.0.0.1:8080/openapi.json) — it is automatically rewritten to host.docker.internal so the container can reach it. You do not need --network host for this.

Container environment variables

--debug turns on verbose logging in the MapViewer container (shorthand for --env HTTP_LOG_LEVEL=debug). Use --env KEY=VALUE (repeatable, short form -E) to pass arbitrary environment variables into the container; explicit --env entries override --debug on key collision. The resulting -e flags appear in the Docker screen's "Copy Command" output.

Container network

--network NAME attaches the container to a specific network (e.g. a custom bridge or host). With --network host the container binds the host's port directly, so --port is ignored and the MapViewer is reached on its internal port (8089). With --mcp-local, --bind selects the native listener in this mode; otherwise it is ignored. Host networking behaves differently across platforms and runtimes — it is intended as a connectivity workaround.

Local MCP

MCP requires Member Edition. Select --edition member and use --mcp-local with a supporting Member image. Community Edition does not provide MCP tools or browser-agent access. No peer addresses are needed; ordinary server networking applies:

mapviewer --edition member --demo --mcp-local --port 8099

Connect your MCP client to http://localhost:8099/mcp and open the viewer at http://localhost:8099 for browser-control tools. Without --port, the endpoint uses the free port selected by the launcher, shown in the run screen. The Docker screen shows the generated native options in its copyable command.

For LAN access, set the public URL explicitly so native MCP discovery and its default Host/Origin allowlists use the address seen by remote browsers. For example, replace 192.168.1.50 with your server's LAN address:

mapviewer --edition member --demo --mcp-local --bind 0.0.0.0 --port 8099 --no-browser \
  --mcp-endpoint http://192.168.1.50:8099/mcp

Open http://192.168.1.50:8099 and connect the MCP client to that URL plus /mcp. The override describes the public URL; it does not change the listener, enable TLS or change the launcher's ordinary localhost browser URL/readiness probe. --mcp-endpoint requires --mcp-local; the native server validates URL syntax.

Local MCP is unauthenticated. Everyone who can reach the server shares access to its enabled MCP tools. The name local does not enforce loopback access. The ordinary --bind and --network settings control reachability: the default bind is 127.0.0.1; --bind 0.0.0.0 or the TUI's Allow network access checkbox exposes the published port on all host interfaces. Use firewall, container or proxy policy to limit access, or OAuth when authentication is required. See the container setup and native MCP documentation.

On hosts supporting host networking, mapviewer --edition member --demo --network host --mcp-local instead uses port 8089 directly and honors --bind for the native listener. The Python API accepts edition="member", mcp_local=True and optional mcp_endpoint="http://host:port/mcp" arguments to MapViewer.

Local configuration

If ~/.nds/config.yaml exists, mapviewer (with no arguments) loads it automatically and goes straight to the RunScreen.

If you edit ~/.nds/config.yaml manually, use host paths there, not container paths. The CLI translates them into the correct container mounts when it starts the container runtime.

The run screen shows, below the info banner, the source you passed (a config file or a directly-given data-source path such as a *.ndslive filestore) and the mapped config that was generated and mounted into the container.

That mapped YAML is a disposable, one-way transformed copy. Map-preset catalogs configured under erdblick.mapPresets are passed through, but the browser marks their management surface read-only in CLI-launched sessions; edits are not written back to the original host config. Edit the host YAML and let the normal config sync reload it instead. Enabling allow-post-config does not make this generated copy a durable map-preset write target.

Editions

MCP server access, browser-agent tools and MCP tunnels are available only in Member Edition. Selecting Community with --mcp-local is rejected before launch.

Open-Source Building Blocks

• mapget — tile-based map data server with caching
• erdblick — deck.gl-based web frontend with live style editing and inspection tools

License

The MapViewer is a proprietary product of the NDS Association. License terms and conditions are governed by the account type used to access the Docker image — registering for a community or member account includes accepting the applicable licensing terms for the MapViewer and its components.