Skip to main content
Glama
Sign In
UNdata

UNdata

by JOSETRA44
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: ESCAP Data Explorer MCP Server

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

Available Tools

7 tools
undata_compare_countriesA

Compare World Development Indicators across several countries at once. Use ISO-3 codes (e.g., ['PER', 'COL', 'BRA']). Optionally restrict to specific WDI series codes and a year range. Returns a comparison organized by series → country → year, ideal for comparative analysis across countries.

Inputs: countries (required), series, end_year, start_year.

undata_get_country_profileB

Get a comprehensive economic and social snapshot for a country using WDI. Returns the latest available value for each indicator in the requested period. Useful for a quick overview of a country's development status. Use ISO-3 country codes (e.g., 'PER', 'USA', 'BRA').

Inputs: country (required), year.

undata_get_mdg_dataB

Get Millennium Development Goals (MDG) data for a country. Contains poverty, education, health, gender, and environmental indicators from 2000-2020. Data covers 200+ countries. Use ISO-3 country codes (e.g., 'PER', 'USA', 'BRA', 'COL'). Returns data organized by series code showing values over time.

Inputs: country (required), end_year, start_year.

undata_get_wdi_dataA

Get World Development Indicators (WDI) data from UNdata. Returns economic and social indicators for a country across years. Use ISO-3 country codes (e.g., 'PER' for Peru, 'USA', 'BRA', 'COL', 'CHN'). Optionally filter by specific series codes or year range. Returns data organized by series → year → value.

Inputs: country (required), end_year, start_year, series_filter.

undata_list_dataflowsA

List all available UNdata SDMX dataflows (datasets). Returns dataset IDs, names, agencies, and descriptions. Use this first to discover what data is available, then use the 'id' in other tools like undata_get_wdi_data or undata_query.

Inputs: no named parameters.

undata_queryA

Generic SDMX query for any UNdata dataflow. Use when the specific WDI or MDG tools don't cover your dataflow. The key is an SDMX dimension key: dimensions separated by dots, blank means 'all values'. Examples: WDI all Peru annual: flow_ref='DF_UNDATA_WDI', key='A..PER'. MDG all Peru: flow_ref='DF_UNDATA_MDG', key='......PER..'. WDI all countries one year: flow_ref='DF_UNDATA_WDI', key='A..', start_year='2022', end_year='2022'. Returns raw parsed rows (limit to avoid huge responses).

Inputs: key (required), flow_ref (required), limit, end_year, +1 more.

undata_search_wdi_seriesA

Search for WDI series codes by keyword to find what indicators are available. Use keywords like 'gdp', 'poverty', 'education', 'health', 'population', 'inflation'. Returns matching series codes and sample values. Use the series_code output in undata_get_wdi_data's series_filter parameter.

Inputs: keyword (required), year, country.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools are clearly distinct (list_dataflows, search_series, get_country_profile, compare_countries). However, undata_get_wdi_data and undata_get_mdg_data overlap somewhat in that both return time-series indicator data for countries, and undata_get_mdg_data could arguably be handled by a parameter on get_wdi_data. The generic undata_query also overlaps with all of them, but its descriptions frame it as a fallback, which reduces confusion.

    Naming Consistency4/5

    The tools consistently use the undata_ prefix followed by verb_object patterns like list_dataflows, get_wdi_data, get_country_profile, search_wdi_series, compare_countries. Minor inconsistency: get_mdg_data lacks a qualifier matching the pattern of get_wdi_data (could be 'get_undata_mdg_data') and the prefix styles are otherwise uniform.

    Tool Count5/5

    Seven tools is a well-scoped set for a data access server. Each tool serves a distinct purpose: discovery, search, specific datasets (WDI, MDG), profiles, comparison, and generic querying. This feels well-balanced without redundancy.

    Completeness4/5

    The tool surface covers the full discovery-to-retrieval workflow well: list dataflows to discover, search series, retrieve specific datasets, get country profiles, and compare. A minor gap is that the server appears read-only (no export or metadata endpoint explicitly), and undata_get_mdg_data could have been folded into the generic query with a parameter, but the overall coverage is strong.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • wbgapi360

      MaykolMedrano
      A
      license
      A
      quality
      C
      maintenance
      MCP server for accessing World Bank data, enabling indicator search, data retrieval, country comparisons, trend analysis, rankings, and chart generation.
      6
      2
      MIT

    • ESCAP Data Explorer MCP Server

      un-shayani
      A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides official statistical data for development indicators in Asia-Pacific. It wraps the ESCAP Data Explorer API, letting any MCP-compatible host query SDG and thematic data through natural language.
      5
      MIT

    • nycdata

      HT224
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables to discover, inspect, query, and profile live NYC Open Data through a CLI and MCP server, providing a developer-first interface to Socrata APIs.
      34 npm
      MIT