worldbank-mcp-server

<div align="center">
  <h1>@cyanheads/worldbank-mcp-server</h1>
  <p><b>Query 29,500+ World Bank development indicators for 200+ countries across 60+ years via MCP. STDIO or Streamable HTTP.</b>
  <div>9 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![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/worldbank-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/worldbank-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.0-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/worldbank-mcp-server/releases/latest/download/worldbank-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=worldbank-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvd29ybGRiYW5rLW1jcC1zZXJ2ZXIiXX0=) [![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%22worldbank-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fworldbank-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)

**Public Hosted Server:** [https://worldbank.caseyjhand.com/mcp](https://worldbank.caseyjhand.com/mcp)

</div>

---

## Tools

9 tools for browsing and querying the World Bank Open Data API:

| Tool | Description |
|:---|:---|
| `worldbank_list_topics` | List all 21 World Bank thematic topics with descriptions |
| `worldbank_list_sources` | List 70+ World Bank data sources (datasets) with pagination |
| `worldbank_list_countries` | List countries and regional aggregates with ISO codes, region, income level, and coordinates |
| `worldbank_get_country` | Fetch full metadata for a specific country or aggregate by ISO2, ISO3, or aggregate code |
| `worldbank_search_indicators` | Search the 29,500+ indicator catalog by keyword, topic, or source |
| `worldbank_get_indicator` | Fetch complete metadata for a single indicator: name, description, source, unit, and topics |
| `worldbank_get_data` | Query indicator values for one or more countries across a time range or most-recent N values |
| `worldbank_get_poverty` | Poverty headcount, gap, and severity at any poverty line, plus the Gini coefficient and decile shares, from the Poverty and Inequality Platform |
| `worldbank_search_projects` | Search the World Bank lending portfolio by text, country, region, status, and board approval date |

### `worldbank_list_topics`

List all 21 World Bank thematic topic categories.

- No input required — returns the complete fixed taxonomy
- Topics include Agriculture, Economy & Growth, Education, Energy & Mining, Environment, Financial Sector, Health, Infrastructure, Poverty, Private Sector, Public Sector, Science & Technology, Social Development, Social Protection & Labor, Trade, Urban Development, and more
- Returns topic IDs used to filter `worldbank_search_indicators`

---

### `worldbank_list_sources`

List the 70+ World Bank data sources (datasets).

- Paginated with configurable page size (up to 100 per page)
- Each source includes ID, name, short code, last-updated date, and data/metadata availability status
- Source IDs used to filter `worldbank_search_indicators` by dataset origin (e.g. "2" for World Development Indicators, "6" for IDS)

---

### `worldbank_list_countries`

List countries and regional aggregates with metadata.

- Returns ISO codes, World Bank region, income level, capital city, and coordinates
- Filterable by region code (EAS, ECS, LCN, MEA, NAC, SAS, SSF) and income level (LIC, LMC, UMC, HIC)
- By default returns individual countries only; set `include_aggregates=true` to include regional, income-group, and world aggregate entities
- Paginated with up to 300 entries per page

---

### `worldbank_get_country`

Fetch full metadata for a single country or aggregate entity.

- Accepts one ISO2 (US), ISO3 (USA), or World Bank aggregate code (EAS, HIC, WLD); `all` or a list of codes is rejected with a pointer to `worldbank_list_countries`
- Returns region, income level, lending type, capital city, and coordinates
- Structured error with recovery hint when code is not found

---

### `worldbank_search_indicators`

Search the 29,500+ World Bank indicator catalog.

- Keyword search, topic filter, source filter — at least one required; a topic and a source together narrow to indicators in both. Topic and source IDs are numeric
- The upstream `searchterm` parameter does not filter, so keyword matching runs locally over the full catalog (or the full selected topic/source): every term must appear in the indicator ID, name, or description, in any word order, with punctuation ignored. A query with no letters or digits is rejected rather than matching everything
- Exact ID or name matches rank first, then whole-phrase matches, then other ID/name matches, then description-only matches — so pasting an indicator name (`GDP (current US$)`) or ID (`NY.GDP.MKTP.CD`) returns it as the top hit
- Returns indicator IDs, names, source dataset, and thematic topics
- One row per indicator ID — the 43 indicators published under both a live source and an archived copy collapse to the live row, and `worldbank_get_indicator` resolves to the same one
- Indicator IDs (e.g. `NY.GDP.PCAP.CD`, `SP.POP.TOTL`) feed directly into `worldbank_get_data`
- Echoes the filters it applied (`query`, `topic_id`, `source_id`) alongside the results
- Paginated with up to 100 results per page

---

### `worldbank_get_indicator`

Fetch complete metadata for a known indicator ID.

- Returns full description, unit of measurement, source dataset, source organization, and thematic topics
- One ID per call, made of letters, digits, `.`, `_`, or `-` — `all`, a list, or any other character is rejected with a pointer to `worldbank_search_indicators`
- Descriptions are plain text: HTML line breaks in provider notes become line breaks, and other markup is removed with its text kept
- Structured error with recovery hint when ID is not found

---

### `worldbank_get_data`

Query indicator values for countries across time. The primary data-access tool.

- Single country, array of countries, or one comma- or semicolon-separated string; regional codes (EAS, LCN, …), income codes (HIC, LMC, …), world code (WLD), or `"all"` on its own for every entry. At least one code is required — an empty value is rejected rather than read as `"all"`
- Time filtering: `date_range` for a period or range — annual (`2020`, `2010:2023`), quarterly (`2020Q1:2021Q4`), or monthly (`2020M01:2020M06`) — or `mrv` for the N most recent available values (1–100). Mutually exclusive. A range running latest first (`2020:2010`), or `"all"` mixed with country codes, is rejected with a recovery hint before any request
- A `date_range` the API can't apply is enforced locally over the whole series, so observations outside the requested window are never returned as matches
- Returns observations with `null` values when data is not available for a country×year cell — common for sparse series
- Includes `nullCount` per page to surface data sparsity
- Output grouped by country for readability; `isAggregate` flag distinguishes all 78 regional, income-group, and lending-group aggregates from individual countries
- Echoes the parameters it sent upstream — indicator, normalized country codes, date range or `mrv`, `dimension_value`, page and page size
- Paginated with up to 1000 entries per page
- Indicators the standard data endpoint doesn't serve — WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition — are answered from their catalog source's own dataset through the source-scoped data API. The response then carries `sourceScoped`, naming the source and the value of its extra dimension that applied (a WDI release such as `2025 Mar`, a classification, a sector, or a counterpart area) and stating that the figures are not from the standard data endpoint and may be archived or superseded. Each row carries its own dimension value too
- For those indicators, `dimension_value` picks the release, classification, sector, or counterpart area by id; an id the dataset doesn't list is rejected with the valid ones. Without it, the default is the only value a dataset lists, `WLD` (World) for counterpart areas, or the newest WDI Database Archives release holding a value for the requested countries and periods, because a series the archive retired carries only nulls in later releases. Multi-valued classifications and sectors come back with every value, each row labelled. `date_range` and `mrv` work the same as on the standard endpoint, and a request too large to read in one go (for example every country across all years of every archive release) is rejected with a hint to narrow it or pin `dimension_value`
- An indicator that neither endpoint can serve is reported as such, not blamed on the country codes
- `indicator_id` takes one catalog ID under the same rules as `worldbank_get_indicator`

---

### `worldbank_get_poverty`

Poverty and inequality estimates from the World Bank [Poverty and Inequality Platform](ht