io.github.cyanheads/worldbank-mcp-server

Official7 tools

by cyanheads · TypeScript

Query 29,500+ World Bank development indicators for 200+ countries across 60+ years.

Search World Bank development indicators across 200+ countries and 60+ years.

Topics

ai-agentbundevelopment-indicatorseconomicsmcpmcp-servermodel-context-protocolopen-datatypescriptworld-bankworldbankcyanheads

Captured live from the server via tools/list.

worldbank_list_topics

Lists all 21 World Bank thematic topics (Economy & Growth, Health, Education, etc.) with descriptions. Use to browse the indicator space or find a topic_id for worldbank_search_indicators.

No parameters.

worldbank_list_sources

Lists the 70+ World Bank data sources (datasets) such as World Development Indicators, IDS, and Doing Business. Returns source IDs and names for use as source_id in worldbank_search_indicators. Supports pagination.

Parameters (2)

pageinteger
Pagination page number (1-based).
per_pageinteger
Results per page (default: server default, max: 100).

worldbank_list_countries

Lists countries and regional aggregates with metadata: ISO codes, region, income level, capital, and coordinates. Filterable by region code (e.g. EAS, SSF, NAC) and income level (LIC, LMC, UMC, HIC). By default, excludes regional/income-group aggregate entries and returns individual countries only. Set include_aggregates=true to also see region, income group, and world aggregate entities.

Parameters (5)

regionstring
Filter by World Bank region code. Valid codes: EAS (East Asia & Pacific), ECS (Europe & Central Asia), LCN (Latin America & Caribbean), MEA (Middle East & North Africa), NAC (North America), SAS (South Asia), SSF (Sub-Saharan Africa).
income_levelstring
Filter by income group code: LIC (Low income), LMC (Lower middle income), UMC (Upper middle income), HIC (High income).
include_aggregatesboolean
When true, includes regional, income-group, and world aggregate entries alongside individual countries. Default false (individual countries only).
pageinteger
Pagination page number (1-based).
per_pageinteger
Results per page (default: server default, max: 300).

worldbank_get_country

Fetches full metadata for a specific country or aggregate entity: region, income level, capital, coordinates, and lending type. Accepts ISO2 codes (US, DE), ISO3 codes (USA, DEU), or World Bank aggregate codes (EAS, HIC, WLD).

Parameters (1)

country_codestringrequired
Country code. Accepts ISO2 (US), ISO3 (USA), or aggregate code (EAS, HIC, WLD). Use worldbank_list_countries to browse valid codes.

worldbank_search_indicators

Searches the 29,500+ World Bank indicator catalog by keyword, topic, or source. Returns indicator IDs and metadata for chaining into worldbank_get_data. At least one of query, topic_id, or source_id must be provided. When combined with topic_id or source_id, keyword filtering applies across all results in that topic or source. Use worldbank_list_topics for topic IDs, worldbank_list_sources for source IDs.

Parameters (5)

querystring
Keyword search terms. At least one of query, topic_id, or source_id must be provided.
topic_idstring
Filter by topic ID (e.g. "1" for Agriculture, "3" for Economy & Growth). Use worldbank_list_topics to browse valid IDs.
source_idstring
Filter by data source ID (e.g. "2" for World Development Indicators). Use worldbank_list_sources to browse valid IDs.
pageinteger
Pagination page number (1-based).
per_pageinteger
Results per page (default: server default, max: 100).

worldbank_get_indicator

Fetches complete metadata for a single World Bank indicator by its ID: name, description, source dataset, source organization, unit, and thematic topics. Use worldbank_search_indicators to discover indicator IDs if you only know the concept.

Parameters (1)

indicator_idstringrequired
Indicator code (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL). Use worldbank_search_indicators to find valid IDs.

worldbank_get_data

Queries World Bank indicator values for one or more countries across a time range. The primary data-access tool — use worldbank_search_indicators to find indicator_id values. Returns observations with null values when data is not available for a country×year cell (common for sparse series). Specify either date_range (historical analysis) or mrv (most recent N values), not both. For "all" countries, use pagination (per_page up to 1000) since the API returns ~266 entries per indicator.

Parameters (6)

indicator_idstringrequired
Indicator code to query (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL). Use worldbank_search_indicators to find valid IDs.
countriesanyrequired
Country codes. Accepts: ISO2 (US, CN), ISO3 (USA, CHN), regional aggregate codes (EAS, LCN, MEA, SAS, SSF, ECS, NAC), income group codes (HIC, UMC, LMC, LIC), world code (WLD), or "all" for all 266 entries (use pagination). Pass a single string or an array of codes for multi-country queries.
date_rangestring
Year or year range in YYYY or YYYY:YYYY format (e.g. "2020" or "2010:2023"). Mutually exclusive with mrv.
mrvinteger
Return the N most recent available values (1–10). Mutually exclusive with date_range.
pageinteger
Pagination page number (1-based).
per_pageinteger
Results per page (default: server default, max: 1000). Use higher values for "all" country queries.

README.md12 KBView on GitHub

<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>7 Tools • 2 Resources</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://worldbank.caseyjhand.com/mcp

</div>

Tools

7 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_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 ISO2 (US), ISO3 (USA), or World Bank aggregate codes (EAS, HIC, WLD)
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
When topic_id or source_id is combined with a keyword query, client-side filtering is applied (the upstream API ignores searchterm when a topic/source filter is active)
Returns indicator IDs, names, source dataset, and thematic topics
Indicator IDs (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) feed directly into worldbank_get_data
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
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, regional codes (EAS, LCN, …), income codes (HIC, LMC, …), world code (WLD), or "all" for all ~266 entries
Time filtering: date_range for historical analysis (YYYY or YYYY:YYYY format), or mrv for the N most recent available values (1–10). Mutually exclusive.
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 regional aggregates from individual countries
Paginated with up to 1000 entries per page

Resources

Type	Name	Description
Resource	`worldbank://indicator/{indicatorId}`	Indicator metadata by ID — name, description, source, unit, and topics
Resource	`worldbank://country/{countryCode}`	Country metadata by ISO2, ISO3, or aggregate code — region, income level, capital, coordinates

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

World Bank-specific:

Full World Bank Open Data API v2 coverage — topics, sources, countries, indicators, and observations
60+ years of development data across 29,500+ indicators for 200+ countries and regional aggregates
Client-side topic/source + keyword compound filtering (works around upstream API limitation)
Null-value transparency — null observations and nullCount surfaced rather than silently dropped
isAggregate flag on every country/data row to distinguish individual countries from aggregate entities

Agent-friendly output:

Tool cross-references woven into descriptions — e.g. worldbank_search_indicators names worldbank_list_topics for topic IDs, worldbank_get_data names worldbank_search_indicators for indicator discovery
Structured error contracts with typed reason codes and actionable recovery hints on every tool
Consistent pagination metadata (page, pages, total) across all list/search/data tools

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/worldbank-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/worldbank-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node.js ≥24.0.0).
No API key required — the World Bank Open Data API is public and unauthenticated.

Installation

Clone the repository:

git clone https://github.com/cyanheads/worldbank-mcp-server.git

Navigate into the directory:

cd worldbank-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_HOST`	HTTP server hostname	`127.0.0.1`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path where the MCP server is mounted	`/mcp`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments	none
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`)	`info`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP exporter endpoint	none
`WORLDBANK_API_BASE_URL`	World Bank API base URL override	`https://api.worldbank.org/v2`
`WORLDBANK_DEFAULT_PER_PAGE`	Default page size for list/search/data operations	`50`

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

Project structure

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Seven tools covering topics, sources, countries, indicators, and data.
`src/mcp-server/resources`	Resource definitions. Indicator and country metadata resources.
`src/services/worldbank`	World Bank API service layer — API client and domain types.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Minimum log level for output: 'debug', 'info', 'notice', 'warning', 'error'.

WORLDBANK_API_BASE_URLdefault https://api.worldbank.org/v2

World Bank API base URL override.

WORLDBANK_DEFAULT_PER_PAGEdefault 50

Default page size for list, search, and data operations.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/worldbank-mcp-server@0.1.14",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "WORLDBANK_API_BASE_URL": "https://api.worldbank.org/v2",
        "WORLDBANK_DEFAULT_PER_PAGE": "50"
      }
    }
  }
}