UNdata

CLI and MCP server for the UNdata SDMX REST API — UN Statistics Division open data. Query World Development Indicators, Millennium Development Goals and other UN datasets from your terminal, from analysis pipelines, or from any MCP client (Claude, Antigravity). No API key required.

Features

• undata CLI — terminal access with table / json / csv / parquet output, runnable from anywhere
• Full CLI ↔ MCP parity: the 7 tools, 3 prompts, and 3 reference docs are all reachable from both interfaces
• 7 MCP tools: list dataflows, WDI data, country profile, series search, MDG data, generic query, multi-country compare
• 3 prompts: economic analysis, development goals progress, country comparison — also via undata prompt
• 3 resources: API guide, country codes, WDI series catalog — also via undata guide|countries|catalog
• Disk cache so repeated research queries are instant across runs
• Declarative dataflow registry — add a dataset with one entry, no new code
• Built for humans and AIs: pretty tables + Markdown for people; clean JSON/CSV and --raw for agents and pipelines

Install (one command)

Requires uv. Installs both undata (CLI) and undata-mcp (server) onto your PATH.

# Windows (PowerShell)
./install.ps1                 # add -Export for Parquet support

# macOS / Linux
./install.sh                  # add --export for Parquet support

Or directly:

uv tool install .             # or:  uv tool install '.[export]'

After uv tool install, both commands live in uv's tool bin (e.g. ~/.local/bin), which uv puts on your PATH — so undata and undata-mcp run from any directory. If your shell can't find them yet, run uv tool update-shell and reopen the terminal.

Run without installing:

uvx --from . undata wdi PER

PyPI (future): the package is metadata-complete and ready to publish. Once published, install anywhere with pipx install undata-mcp / uvx undata-mcp. Publishing is a deliberate, public step (uv build && uv publish) and is intentionally left for you to trigger.

CLI usage

undata dataflows                                   # list available datasets (live)
undata datasets                                    # registered datasets + aliases (offline)

undata wdi PER --years 2015:2023                   # WDI for one country
undata wdi PER --series NY_GDP_PCAP_CD --format table
undata profile PER --year 2022                     # latest snapshot, all indicators
undata search education --country BRA              # find WDI series codes
undata mdg PER --years 2000:2020                   # Millennium Development Goals

undata compare PER COL BRA --series NY_GDP_PCAP_CD # multi-country comparison
undata compare PER COL --format csv -o out.csv     # export to CSV for analysis
undata compare PER COL --format parquet -o out.parquet

undata query wdi A..PER --years 2020:2023          # generic SDMX query (alias or id)

# Reference docs (same content the MCP serves as resources)
undata guide                                       # API guide (Markdown in a terminal, raw when piped)
undata countries --raw                             # ISO-3 country codes
undata catalog                                     # common WDI series codes by topic

# Guided analysis prompts (same templates the MCP exposes)
undata prompt                                      # list prompts
undata prompt country_economic_analysis -c PER --year 2022
undata prompt compare_countries -c PER,COL,BRA

undata mcp-config                                  # print an MCP client config snippet
undata --version
undata serve                                       # start the MCP server (= undata-mcp)

Global flags on every data command: --format table|json|csv|parquet (default table) and --output/-o FILE. Reference commands take --raw for plain-text (AI/pipeline) output.

MCP usage

Point your MCP client at the undata-mcp command. Example (.antigravity.json, already included):

{
  "mcpServers": {
    "undata": {
      "command": "uv",
      "args": ["--directory", "C:\\Users\\USER\\source\\MCPs\\UNdata-mcp", "run", "undata-mcp"]
    }
  }
}

undata-mcp and undata serve are equivalent.

Tool	Description
undata_list_dataflows	List available datasets
undata_get_wdi_data	World Development Indicators for a country
undata_get_country_profile	Latest snapshot across all WDI indicators
undata_search_wdi_series	Find series codes by keyword
undata_get_mdg_data	Millennium Development Goals data
undata_compare_countries	Compare WDI indicators across countries
undata_query	Generic SDMX query for any dataflow

Architecture

The logic lives in a shared service layer; the CLI and the MCP tools are thin adapters over it, so there is zero duplication between the two interfaces.

services/   core async logic (get_wdi_data, compare_countries, …)  ← single source of truth
  ↑     ↑
tools/    cli/     thin adapters (MCP tools / Typer commands)
registry.py   declarative DataflowSpec + build_key() — add datasets by config
cache.py      pluggable CacheBackend: MemoryCache (server) / DiskCache (CLI)
client.py     async httpx client, cache injected
formatters.py pure CSV → dict shaping

Adding a new dataset = one DataflowSpec entry in registry.py (and, if its output shape differs, one small service function). New interfaces (REST API, notebooks) can reuse services/ unchanged.

Configuration

Copy .env.example to .env (all optional):

UNDATA_CACHE_TTL=600           # response cache seconds (0 = disabled)
UNDATA_TIMEOUT=60              # HTTP timeout seconds (SDMX can be slow)
UNDATA_CACHE_BACKEND=memory   # memory | disk (CLI forces disk automatically)
UNDATA_CACHE_DIR=...          # override the disk cache location

Tests

uv run pytest tests/ -v