Dekart MCP wrapper for your AI agent to create maps from SQL query results.
Works best with the geosql skill — it writes the SQL, this CLI renders the map.
Works with any Dekart instance:
- Dekart Cloud (SaaS, default)
- Local (Docker) (on your machine with persistent local data)
- Self-hosted (your own URL)
pip install dekart
dekart initdekart init walks you through:
- Picking the instance (Cloud / self-hosted / localhost).
- Optionally enabling BigQuery passthrough with an authenticated local
gclouduser. - Installing Playwright and Chromium for local snapshots unless you pass
--local-snapshot skip. - Authorizing the CLI in your browser.
The browser opens automatically as the final setup step. Pass --no-browser to
print the authorization URL without opening it.
To switch instance later:
dekart config --url <your-url>
dekart initConfig and token: ~/.config/dekart/.
BigQuery passthrough requires the Google Cloud CLI. The CLI prefers the active
authenticated non-service-account gcloud user, uses the only available user,
or asks you to choose when several are available. The gcloud and Dekart emails
may differ. The CLI stores only that account and the selected Dekart URL; it mints short-lived tokens
when needed and keeps them in process memory.
Run dekart init --bigquery-passthrough enable to enable it later, or use
--bigquery-passthrough disable to remove the local binding.
The CLI sends a best-effort version check with its package version and an opaque random installation ID. GeoSQL and Dekart CLI share the ID at ${XDG_CONFIG_HOME:-~/.config}/dekart/installation_id; deleting that file resets it. Set DO_NOT_TRACK=1 (or DNT=1) to disable the version check before an ID is created. CI sends a reserved non-persisted test ID.
Choose Local during dekart init, or manage it directly:
dekart local up
dekart local status
dekart local status --json
dekart local down
dekart local removeThe CLI uses a labeled container named dekart-local and a labeled persistent Docker volume named dekart-local-data. down stops the container without deleting the container or volume. The next up recreates the container from the latest image while preserving the data volume. remove asks for confirmation, then removes both the container and its data volume; use remove --force to skip confirmation. If port 8080 is occupied by another service, the CLI selects the first free port through 8099 and saves that URL before authorization begins.
When the CLI starts or stops Docker, it prints Executing: <docker command> before running it. You can also choose “I will start or connect to Dekart myself” during dekart init; the CLI prints a simple standalone docker run command without CLI labels, container names, or volumes, then asks for the Dekart URL.
The initial Docker commands are:
docker pull dekartxyz/dekart:latest
docker run -d \
--name dekart-local \
--label xyz.dekart.cli.managed=true \
--restart unless-stopped \
-p 127.0.0.1:8080:8080 \
-v dekart-local-data:/dekart/data \
dekartxyz/dekart:latestThe CLI never starts, stops, removes, or replaces a same-name container without its management label. Docker is not installed or started automatically; dekart init gives platform-specific instructions when it is unavailable.
Local headless renderer for fast PNG snapshots without a round-trip to the server:
dekart snapshot-local installManage:
dekart snapshot-local status
dekart snapshot-local uninstall # remove renderer
dekart snapshot-local uninstall --purge # also remove its browser cacheWhen local snapshot is enabled, dekart snapshot --report-id <id> --out ./snap.png uses it automatically. Pass --remote-only to force server-side rendering.
Agents can request a specific snapshot viewport without editing the saved map:
dekart snapshot --report-id <id> --zoom 12 --lat 52.52 --lon 13.405 --out ./snap.png--zoom accepts 0 through 24. Use --lat and --lon together.
Include the charts pane when the report has widgets. A wider viewport leaves more room for the map:
dekart snapshot --report-id <id> --include-widgets --width 1920 --out ./snap-with-charts.pngWhen the server provides a verified render-URL lifetime and an established local
page or browser target closes unexpectedly, the CLI retries once with a fresh
browser and the same per-operation timeout. Browser launch failures and normal
timeouts are not retried; increase a normal timeout explicitly, for example with
--timeout 180.
Remote capture is never selected automatically. Use --remote-only when the
configured Dekart instance provides a remote snapshot endpoint.
Run an already-prepared Dekart query, wait for the job, and save result rows:
dekart run-query --query-id <query-id> --out-dir ./results --wait --jsonPass saved report parameter values as JSON when needed:
dekart run-query --query-id <query-id> --params-json '{"row_limit":"10"}' --out-dir ./results --jsonQueries wait by default. Connection queries run and download their warehouse result as before. On a compatible Dekart server, DuckDB queries download their pinned file or warehouse inputs, install the server-required signed core or community extensions, execute the prepared program locally, and save <query-job-id>.parquet. --no-wait returns pending metadata without downloads when a DuckDB warehouse input is still running. Use --json for machine-readable metadata or --print for rows. A DuckDB version mismatch emits a warning to stderr and continues best effort. The first local DuckDB run may need internet access for required extensions such as H3; later runs reuse DuckDB's standard cache.
Resolve a report URL explicitly from a report id:
dekart report-url --report-id <report-id>
dekart report-url --report-id <report-id> --jsonPreview a CSV or parquet file produced by dekart run-query:
dekart preview ./results/<result-file>.parquet --limit 20
dekart preview ./results/<result-file>.parquet --schemaPreview output is tab-separated. Parquet and CSV previewing use the bundled DuckDB Python dependency.
- Dekart: dekart.xyz
- geosql skill: github.com/dekart-xyz/geosql