unhcr-refugees-mcp-server

<div align="center">
  <h1>@cyanheads/unhcr-refugees-mcp-server</h1>
  <p><b>Query UNHCR refugee, IDP, and stateless populations, asylum decisions, returns, and resettlement via MCP. STDIO or Streamable HTTP.</b>
  <div>8 Tools (+1 opt-in)</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/unhcr-refugees-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/unhcr-refugees-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/unhcr-refugees-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/unhcr-refugees-mcp-server/releases/latest/download/unhcr-refugees-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=unhcr-refugees-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdW5oY3ItcmVmdWdlZXMtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22unhcr-refugees-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Funhcr-refugees-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## Overview

Displacement statistics from the keyless [UNHCR Refugee Data Finder API](https://api.unhcr.org/docs/refugee-statistics.html): refugee, asylum-seeker, IDP, and stateless populations by country of origin and asylum from 1951, asylum applications and decisions from 2000, and returns, resettlement, and naturalisation from 1959. Resolve country names to ISO3 codes, pull annual figures with notes on how to read them, and run SQL over results too large to return inline. Runs as a stdio process or a local Streamable HTTP server.

### Tools

| Tool | Description |
|:---|:---|
| `unhcr_list_reference` | Decode countries (ISO3, ISO2, and UNHCR codes, names, regions), regional bureaus, dataset coverage years, population types, and asylum codes |
| `unhcr_get_population` | Year-end displacement stocks by origin and/or asylum country from 1951, with UNRWA and IDMC series alongside and an optional current-year nowcast |
| `unhcr_get_demographics` | Year-end stocks by population type, sex, and age band from 2001, with the share UNHCR could disaggregate |
| `unhcr_get_asylum_applications` | Asylum applications lodged per year from 2000, split by application stage by default |
| `unhcr_get_asylum_decisions` | Asylum decisions per year from 2000 by outcome, with the Refugee Recognition Rate and Total Protection Rate |
| `unhcr_get_solutions` | Refugee returns, resettlement, naturalisation, and IDP returns per year from 1959 |
| `unhcr_dataframe_describe` | Describe a staged dataframe by name, or list them all where listing is on, with provenance, expiry, completeness, and column schema |
| `unhcr_dataframe_query` | Run one read-only SQL `SELECT` across staged dataframes, optionally saving the result as a new one |
| `unhcr_dataframe_drop` | Drop a staged dataframe before its TTL — opt-in, absent from `tools/list` by default |

`unhcr_dataframe_drop` is registered only when `UNHCR_DATAFRAME_DROP_ENABLED=true`; the other eight tools are always advertised.

### Dataframe workflow

1. A `unhcr_get_*` call whose full result exceeds `limit`, or that sets `stage: true`, stages every row as a `df_XXXXX_XXXXX` table and returns its handle in `dataset`.
2. `unhcr_dataframe_describe` lists the staged tables with their columns, source call, and expiry. Listing is off over HTTP with `MCP_AUTH_MODE=none`, so there describe each table by the name in `dataset`.
3. `unhcr_dataframe_query` runs one read-only DuckDB `SELECT` across them; `register_as` saves the result as a new table for the next query.
4. Tables expire after `UNHCR_DATASET_TTL_SECONDS` (24 hours by default). With `UNHCR_DATAFRAME_DROP_ENABLED=true`, `unhcr_dataframe_drop` removes one sooner. Once a tenant's staged rows pass 1,000,000, the oldest tables are evicted first, and the call that pushed the total over names them in `evicted`.

Dataframes run on DuckDB's native binding, which the npm and Docker installs carry. The Claude Desktop `.mcpb` bundle ships without it, so there the data tools answer inline only. Set `CANVAS_PROVIDER_TYPE=none` to turn dataframes off anywhere.

## Capability reference

The five `unhcr_get_*` tools share one contract:

- **Scope:** `origin` and `asylum` take ISO3 codes, case-insensitive, as a string or a list, up to 50 each. ISO2 codes are rewritten to ISO3; UNHCR's own codes and country names are rejected. Each listed code returns its own rows, and an omitted dimension is summed into one row unless `expand` (`origin`, `asylum`, or `both`) lists every country. `year_from` / `year_to` default to the dataset's span and are clamped to it.
- **Rows:** the full result is sorted by `sort_by`, then cut to `limit` (1–500, default 100). Where dataframes are on, the full set of a larger result is staged, and `stage: true` stages a result that fits too.
- **Output:** `total_rows`, `complete` (false when `UNHCR_MAX_ROWS` stopped the fetch), `measure` (`stock` or `flow`), `applied_scope`, `latest_year`, `dataset` when staged, `data_notes`, and `attribution`.
- **Errors:** `unknown_country_code`, `invalid_year_window`, `year_out_of_coverage`, `conflicting_scope`, and the retryable `upstream_busy`, which carries `retryAfter`.

---

### `unhcr_list_reference` <sub>tool</sub>

- `topic`: `countries`, `regions`, `coverage`, `population_types`, or `asylum_codes`. With `countries`, `name_contains` keeps countries whose names contain every word given, or whose ISO3, ISO2, or UNHCR code equals one; there is no fuzzy matching
- `coverage` gives each dataset's `first_year`, `latest_year`, and `measure`, plus the month of the current `nowcast`
- Countries, regions, and coverage come from the live API and are cached for 24 hours; population types and asylum codes are static, and asylum codes UNHCR's methodology does not define carry `documented: false`

---

### `unhcr_get_population` <sub>tool</sub>

- Year-end stocks `refugees`, `asylum_seekers`, `oip`, `idps`, `stateless`, `ooc`, and `hst`, plus `returned_refugees` and `returned_idps`, which are flows during the year; `sort_by` takes any of them or `year`
- `unrwa_refugees` (Palestine refugees registered with UNRWA) and `idmc_conflict_idps` (IDMC's conflict-IDP estimate) sit beside a row when that series has one and are never added into UNHCR's counts. Matching UNHCR `footnotes` come back too, up to 20, with `footnotes_total`
- `include_nowcast: true` appends UNHCR's current-year monthly estimate of refugees and asylum-seekers by asylum country; it is skipped when `origin` lists codes

---

### `unhcr_get_demographics` <sub>tool</sub>

- `population_types` filters to `REF`, `ASY`, `OIP`, `IDP`, `STA`, `OOC`, `HST`, `RET`, or `RDP`; `sort_by` takes `year` or `total`
- Each row is one population type: `total`, fourteen sex × age bands (`female_0_4` … `female_60_plus`, `female_unknown_age`, `female_total`, and the `male_*` twins), `disaggregated`, and `sex_disaggregated_share` (0–1). Bands are null where UNHCR has no breakdown
- Totals come from a separate collection and need not match `unhcr_get_population`; matching `footnotes` come back as there

---

### `unhcr_get_asylum_applications` <sub>tool</sub>

- `split_by` names which of `authority`, `stage`, and `decision_level` stay separate rows (default `["stage"]`; `[]` gives one total per year, scope, and unit). `stages` filters before summing, e.g. `["N"]` for new applications; `sort_by` takes `year` or `applied`
- Each row lists the `authorities`, `stages`, and `decision_levels` codes summed into it, its `unit` (`persons` or `cases`), and `applied`. Cases are never added to persons

---

### `unhcr_get_asylum_decisions` <sub>tool</sub>

- `split_by` names which of `authority` and `decision_level` stay separate rows (default `[]`, all summed, as UNHCR does for its rates). `decision_levels` filters before summing, e.g. `["FI"]` for first instance
- Each row carries `recognized`, `complementary_protection`, `rejected`, `otherwise_closed`, `total_decisions`, `substantive_decisions`, and a `unit`, plus `refugee_recognition_rate` and `total_protection_rate` as percentages of substantive decisions. A rate is null when that denominator is 0 or null
- `sort_by` takes `year` or a count (`total_decisions`, `substantive_decisions`, `recognized`, `rejected`); rates are not sortable

---

### `unhcr_get_solutions` <sub>tool</sub>

- Flows `returned_refugees`, `resettlement`, `naturalisation`, and `returned_idps`; `sort_by` takes any of them or `year`. Matching `footnotes` come back as with population
- The asylum country means something different per column: the country refugees returned from, the country they were resettled to, the country that naturalised them. IDP returns sit on the origin country itself

---

### `unhcr_dataframe_de