Search humanitarian datasets on HDX (data.humdata.org) via @pipeworx/mcp-hdx — displacement, conflict, food security, disasters

@pipeworx/mcp-hdx v0.1.0 — Humanitarian Data Exchange (HDX) MCP

Install: npm install @pipeworx/mcp-hdx Transport: Remote streamable-http gateway at https://gateway.pipeworx.io/hdx/mcp (POST JSON-RPC, SSE responses) Auth: None (keyless CKAN API at data.humdata.org) Rate limit: 100 req/day anonymous (shared across Pipeworx gateways per IP)

4 Tools

Workflow: search → details → download

1. Search by topic: search_datasets({query: "displacement"}) → 1,817 datasets from IDMC, UNHCR, IOM, etc.
2. Filter by country: search_datasets({query: "food security", fq: "groups:syr"}) → 38 Syria food security datasets
3. Filter by org: search_datasets({query: "conflict", fq: "organization:acled"}) → 246 ACLED conflict event datasets
4. Get download URLs: dataset_details({id: "dataset-slug"}) → resources array with download_url for each CSV/XLSX file
5. Browse locations: list_locations({}) → [{name: "afg", display_name: "Afghanistan"}, {name: "syr", display_name: "Syrian Arab Republic"}, ...]
6. Browse orgs: list_organizations({}) → [{name: "ocha-roap", display_name: "OCHA ROAP"}, {name: "unhcr", display_name: "UNHCR"}, ...]

Verified Search Results

• "displacement" → 1,817 datasets (IDMC, UNHCR, IOM, DTM)
• "food security" + groups:syr → 38 datasets (WFP, FAO, OCHA)
• "conflict" + organization:acled → 246 datasets (Armed Conflict Location & Event Data)
• "earthquake" + groups:tur → 16 datasets (Turkey/Syria 2023 earthquake response)
• "population" + groups:ukr + res_format:CSV → 40 datasets (Ukraine population data, CSV only)
• "crisis" + groups:sdn → 40 datasets (Sudan crisis)

Key Gotchas

1. ⚠️ CKAN "groups" = LOCATIONS on HDX — not topic groups. Use fq="groups:syr" for Syria, fq="groups:afg" for Afghanistan. Get codes from list_locations.
2. ⚠️ NO row-level query — HDX's CKAN datastore_search requires authentication (returns "Authorization Error"). You must download the CSV/XLSX via the download_url from dataset_details and parse locally.
3. ⚠️ `fq` filters are Solr syntax — combine with spaces: fq="groups:syr organization:wfp res_format:CSV". Use lowercase for org/group names.
4. ⚠️ `dataset_details` with invalid ID returns 404 — {success: false, error: {message: "Not found", __type: "Not Found Error"}}. The tool correctly throws an error.
5. Results are UNWRAPPED — the CKAN {success, result} envelope is stripped; you get result directly. A success: false body becomes an error.
6. `rows` default is 25, max 1000 — for comprehensive searches, set rows: 100 or page with start.
7. `sort` options — "score desc" (relevance, default), "metadata_modified desc" (newest first), "views_recent desc" (popular).
8. Resources include format metadata — each resource has format ("CSV", "XLSX", "JSON", "GeoJSON"), file_type, download_url, and url fields. Prefer download_url when available.
9. HXL tags — many HDX datasets use Humanitarian Exchange Language (HXL) tags in the second CSV row. Look for #affected, #population, #adm1, etc.
10. Gateway caching (5-min TTL) — consecutive identical searches return cached results. Less impactful than DST-DK since searches are read-only, but be aware for freshness-sensitive queries.

Latency Profile (via Pipeworx gateway)