Humanitarian

Trusted humanitarian data — refugees, conflict, hunger, funding — as one clean, citable interface for AI assistants and research code.

CI Release Docker npm Research: citable MCP License: MIT

What is Humanitarian MCP?

Humanitarian MCP is an open-source server that gives AI assistants and analysis scripts reliable, normalized, read-only access to trusted humanitarian datasets: 75 years of UNHCR displacement statistics, World Bank context indicators, HDX crisis data (conflict events, food security, humanitarian funding, internal displacement), and ReliefWeb situation reports.

MCP in one paragraph: the Model Context Protocol is an open standard — think "USB for AI tools" — that lets any AI application (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, custom agents) plug into external systems through one protocol. A server like this one exposes tools the model can call, resources it can read, and prompts it can reuse. Connect it once, and every question your assistant answers about displacement is grounded in the real numbers instead of its training data. New to MCP? Read docs/how-mcp-works.md.

Humanitarian data is public but hostile to programmatic use — different country-code schemes, different schemas, silent failure modes (details below). This project normalizes multiple humanitarian datasets into one consistent record shape, one country-code scheme (ISO3), one interface, with the citation attached to every payload.

Why this project exists

Every trap below is real, encoded in this codebase, and covered by tests:

Without a trusted middleware, an LLM pointed at raw humanitarian APIs re-discovers these traps every session — and the failure mode is not a crash, it is a plausible-looking wrong number. This server exists so that never happens.

Architecture

flowchart TD
    U["You"] --> C["Claude Desktop · Claude Code · Cursor · VS Code · Windsurf<br/>or your own MCP agent"]
    C -->|"MCP (stdio or Streamable HTTP)"| S["Humanitarian MCP<br/>21 tools · 11+ resources · 8 prompts"]
    S --> R["Provider registry<br/>(tools never see provider internals)"]
    R --> P1["UNHCR provider<br/>displacement · demographics · asylum"]
    R --> P2["World Bank provider<br/>population · GDP · poverty"]
    R --> P3["HDX/HAPI provider<br/>conflict · food security · funding · IDPs"]
    R --> P4["ReliefWeb provider<br/>situation reports · narrative context"]
    P1 & P2 & P3 & P4 --> H["Shared HTTP layer<br/>retry · backoff · rate limit · ETag · cache · offline mode"]
    H --> A1[("api.unhcr.org")]
    H --> A2[("api.worldbank.org")]
    H --> A3[("hapi.humdata.org")]
    H --> A4[("api.reliefweb.int")]

Three invariants hold everywhere: (1) nothing provider-specific leaks outside src/providers/<id>/; (2) every tool is read-only and annotated as such; (3) errors reach the model as actionable text, never stack traces. Deep dive: docs/architecture.md.

Two ways to use it

TL;DR — researchers and organizations who care about control: self-host. Everyone who just wants answers: use the hosted endpoint.

Mode 1 — Self-hosted

You install and run the server yourself. You own everything: the process, the cache, the configuration. Your MCP client talks to it over stdio (desktop) or HTTP (remote/containers). Full instructions in Installation below.

// Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "humanitarian": {
      "command": "node",
      "args": ["/absolute/path/to/humanitarian-mcp/dist/index.js"],
    },
  },
}

Mode 2 — Hosted endpoint

No infrastructure. Connect any Streamable-HTTP-capable MCP client to:

https://humanitarian-mcp.zad.tools/mcp

• claude.ai / Claude Desktop (remote connector): add a custom connector with that URL.
• Claude Code: claude mcp add --transport http humanitarian https://humanitarian-mcp.zad.tools/mcp
• Anything that speaks HTTP: see examples/http-client.md — the endpoint is stateless JSON-RPC, no session juggling.

No API key is required today. The service is operated on a best-effort basis by the maintainer; free and paid tiers may be introduced in the future — nothing beyond what you see here is promised. If you need guarantees, self-host: it is the same code.

Features

Data access

• 21 semantic, read-only tools — full reference: country profiles, comparisons, yearly series, demographics, asylum applications/decisions with recognition rates, conflict events, food security (IPC), humanitarian funding, situation reports, rankings, trend analysis with anomaly detection, (loudly caveated) naive forecasts
• 11+ MCP resources (country://EGY, report://SDN, chart://UGA, metadata://providers…) with URI autocompletion
• 8 built-in prompts (situation summary, donor briefing, crisis overview, anomaly hunt…)

Country intelligence

• Fuzzy name resolution in English and Arabic — «مصر», "egypt", EGY, "DRC", "ivory coast" all land correctly; Arabic matching folds hamza/alef forms, taa marbuta and the definite article («الأردن» = «الاردن» = «اردن»)
• The UNHCR↔ISO3 code mismatch (99/232 countries) handled invisibly

Analytics

• normalize_by: per-capita (per 1,000 residents) and per-GDP (per US$1bn) comparisons, rankings and charts, with per-year denominator matching
• Regression, year-over-year, CAGR, z-score anomaly detection
• Charts as Chart.js / Vega-Lite / Mermaid / SVG; maps as GeoJSON

Research reproducibility

• Extraction manifest on every export: exact arguments, timestamp, server version, citation — a repeatable recipe for a paper's appendix
• Optional variable-level codebook matching exactly the exported columns
• CSV / JSON / Markdown / GeoJSON export; CSV manifests ride in # comment lines (pd.read_csv(..., comment="#"))
• Runnable Python & R notebooks reproducing four research workflows
• CITATION.cff + JOSS paper draft in paper/

Operations

• Two transports: stdio (desktop) and stateless Streamable HTTP (remote) + a built-in dashboard with a query playground
• Serious caching: memory or SQLite (zero native deps), TTL + ETag revalidation, stale-while-revalidate, full offline mode for fieldwork
• Polite by design: token-bucket rate limiting, retries with backoff, identified User-Agent, strictly read-only
• Docker image + compose for organizational self-hosting

Live data sources

Example questions

Real prompts, real production numbers (extracted 2026-07-10 — figures are revised upstream over time):

• "What are the top refugee-hosting countries per capita?" → Lebanon 130.7 per 1,000 residents, Chad 63.0, Moldova 56.6, Jordan 55.7 — a very different list than the absolute ranking.
• "Was there anything unusual in Sudan's displacement data?" → 2023 flagged as an anomaly (z ≈ +2.6, +78.8% YoY), coinciding with the April 2023 war.
• "Relate Sudan's conflict to its displacement since 2022." → conflict fatalities 2,770 → 21,020 → 22,987 (2022–2024, ACLED) alongside IDPs 3.78M → 9.05M → 11.56M (IOM DTM).
• "How well is Sudan's humanitarian response funded?" → 58.5% of requirements in 2023, 76.4% in 2024 (OCHA FTS).
• "«قارن بين عدد اللاجئين في مصر والأردن»" → works — country resolution is bilingual.
• "Export Jordan's series as citation-ready CSV with a codebook." → export_data({..., include_codebook: true}).

More worked conversations with tool traces: examples/conversations.md.

Why researchers like it

• Citable: GitHub's Cite this repository button (CITATION.cff); a JOSS paper is drafted in paper/.
• Reproducible: every export carries a manifest (exact call, timestamp, server version, source citation) — paste it in your appendix and anyone can re-run the extraction.
• Documented data: include_codebook: true generates variable-level documentation (meaning, unit, derivation — including how recognition rates and funding coverage are computed) for exactly the columns you exported.
• Join-ready: every row carries ISO3, so merges against World Bank / V-Dem / UCDP panels need no country-name crosswalk.
• Honest methods: end-year stock semantics, denominator years, truncation and forecast naivety are stated in the output, not hidden.
• Fieldwork-ready: warm the SQLite cache once, then HMCP_OFFLINE=1 gives the full toolset with zero connectivity.

Start here: docs/for-researchers.md · notebooks.

Installation

Requires Node.js ≥ 20 for source installs (SQLite cache uses built-in node:sqlite on Node ≥ 22.5; older Nodes fall back to memory automatically). Docker route needs only Docker.

From npm — no clone needed

npx humanitarian-mcp --version   # → humanitarian-mcp 0.6.0

Register it with Claude Code in one line:

claude mcp add humanitarian -- npx -y humanitarian-mcp

Claude Desktop — one click (no terminal)

Download humanitarian-mcp.mcpb from the latest release and double-click it. Done.

From source

git clone https://github.com/ahmedvnabil/humanitarian-mcp
cd humanitarian-mcp
npm install
npm run build
node dist/index.js --version   # → humanitarian-mcp 0.6.0

Docker

docker run -p 8642:8642 -v hmcp-cache:/data ghcr.io/ahmedvnabil/humanitarian-mcp
# → MCP endpoint at http://localhost:8642/mcp + dashboard at http://localhost:8642

Or docker compose up -d with the provided compose.yaml.

Connect your client (self-hosted, stdio)

{
  "mcpServers": {
    "humanitarian": {
      "command": "node",
      "args": ["/absolute/path/to/humanitarian-mcp/dist/index.js"]
    }
  }
}

claude mcp add humanitarian -- node /absolute/path/to/humanitarian-mcp/dist/index.js

{
  "mcpServers": {
    "humanitarian": {
      "command": "node",
      "args": ["/absolute/path/to/humanitarian-mcp/dist/index.js"]
    }
  }
}

{
  "servers": {
    "humanitarian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/humanitarian-mcp/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "humanitarian": {
      "command": "node",
      "args": ["/absolute/path/to/humanitarian-mcp/dist/index.js"]
    }
  }
}

Then ask: "What are the top refugee-hosting countries this year?"

Enable the HDX crisis datasets (optional)

# one-time: generate a free identifier (base64 of app-name:email — not a secret)
curl 'https://hapi.humdata.org/api/v2/encode_app_identifier?application=<your-app>&email=<your-email>'

HMCP_PROVIDERS=unhcr,worldbank,hdx HMCP_HDX_APP_ID=<identifier> node dist/index.js

Enable ReliefWeb situation reports (optional)

# one-time: request a pre-approved appname (short form, reviewed by ReliefWeb)
# https://apidoc.reliefweb.int/parameters#appname

HMCP_PROVIDERS=unhcr,worldbank,reliefweb HMCP_RELIEFWEB_APPNAME=<appname> node dist/index.js

All configuration knobs: .env.example.

Verify without any client

npm run dashboard   # → http://localhost:8642 — providers, health, live logs, query playground
npm run inspect     # → official MCP Inspector

In --http mode, GET /health is a dependency-free liveness probe for uptime monitors, and every other route is rate limited per client IP (HMCP_HTTP_RATE_LIMIT_RPM, default 120/min) so a public endpoint cannot be used to exhaust the upstream quotas all providers share.

Repository tour

Development

npm run dev            # stdio server via tsx
npm run dev:http       # HTTP + dashboard on :8642
npm test               # vitest — unit + integration + MCP compliance
npm run check          # typecheck + lint + format + tests (run before pushing)
npm run build          # emit dist/

Releases: bump the version, tag v*, push — CI publishes the GitHub release with the .mcpb bundle, the Docker image to GHCR, and (once the npm token is configured) the npm package. Full guide: docs/development.md · adding a data source: docs/adding-providers.md.

Roadmap

✅ Completed

• v0.1.0 — UNHCR provider, 17 tools, resources, prompts, caching/offline, dashboard, compliance suite
• v0.2.0 — release automation (npm workflow + .mcpb), CITATION.cff, Arabic country names, reproducible extraction manifests
• v0.3.0 — World Bank provider + normalize_by per-capita / per-GDP analytics
• v0.4.0 — HDX/HAPI provider (conflict, food security, funding, IDPs) + 3 crisis tools + Docker/GHCR
• v0.5.0 — codebooks, Python/R notebooks, JOSS paper draft
• v0.5.1 — HDX fixes from the first live verification round (per-theme admin levels, server-side year windows, pagination)
• v0.6.0 — ReliefWeb provider (situation reports + latest report links), situation_reports tool, crisis_overview prompt, hardened public HTTP mode (per-IP rate limiting, GET /health), bilingual landing page
• Published to npm — npx humanitarian-mcp is live

🚧 In progress

• Zenodo DOI per release
• JOSS paper review & submission
• npm provenance signing on future releases (via the release workflow once its token is configured)

🔭 Future (contributions welcome)

• ReliefWeb disasters dataset (the situation-reports pipeline already shipped)
• Full Arabic report generation (locale: "ar")
• UNHCR Operational Data Portal situations
• Sturdier statistics (confidence intervals, changepoint detection)
• Redis cache backend

FAQ

Contributing

Contributions welcome — most wanted: new providers (IOM DTM, UNHCR ODP situations), country-alias corrections, and documentation in more languages. Start with CONTRIBUTING.md; the golden rules: read-only always, provider isolation, no network in tests, attribution is not optional.

Citation

Software (also available via GitHub's "Cite this repository" button — CITATION.cff; a Zenodo DOI per release is being set up):

BibTeX

@software{nabil_humanitarian_mcp_2026,
  author  = {Nabil, Ahmed},
  title   = {humanitarian-mcp: a Model Context Protocol server for humanitarian open data},
  year    = {2026},
  version = {0.6.0},
  url     = {https://github.com/ahmedvnabil/humanitarian-mcp},
  license = {MIT}
}

APA — Nabil, A. (2026). humanitarian-mcp: A Model Context Protocol server for humanitarian open data (Version 0.6.0) [Computer software]. https://github.com/ahmedvnabil/humanitarian-mcp

Chicago — Nabil, Ahmed. humanitarian-mcp: A Model Context Protocol Server for Humanitarian Open Data. V. 0.6.0. Computer software, 2026. https://github.com/ahmedvnabil/humanitarian-mcp.

Cite the data as its producers: UNHCR Refugee Data Finder; World Bank World Development Indicators (CC BY 4.0); ACLED / IPC / OCHA FTS / IOM DTM via HDX HAPI — every export's manifest carries the exact citation string for its dataset. Method notes: docs/for-researchers.md.

Data, attribution & responsibility

• Data © its original producers: UNHCR (Refugee Data Finder), World Bank (CC BY 4.0), and via HDX HAPI: ACLED, IPC, OCHA FTS, IOM DTM. This project is unofficial and unaffiliated.
• The server is strictly read-only and respects upstream rate limits.
• Figures are end-year stocks; recent years may be preliminary; series get revised — record extraction dates (manifests do).
• Forecasts are naive extrapolations, clearly labelled.
• These numbers represent people. Present them with the care they deserve.

License

MIT — free for research, NGO, commercial and government use.