worldbank-mcp-server

---

Overview

World Bank Open Data: 29,500+ development indicators, poverty and inequality estimates, and the Bank's lending projects. Search indicators, query country time series, pull poverty metrics, and search active and historical projects. No API key required.

Tools

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, lending type, and coordinates, filterable by region, income level, and lending type
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, the most recent N periods, or each country's latest N non-empty values, annually, quarterly, or monthly
worldbank_get_poverty	Poverty headcount, gap, and severity at any poverty line for economies and PIP's regional, income-group, lending-group, and fragility-group aggregates, 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, financing window, and board approval date

Resources

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

Capability reference

worldbank_list_topics _tool

• No input required — returns the complete fixed taxonomy of 21 thematic topics
• Topic IDs (e.g. 1 Agriculture, 3 Economy & Growth) feed topic_id on worldbank_search_indicators

---

worldbank_list_sources _tool

• Paginated list of the 70+ World Bank data sources (datasets); up to 100 per page
• Each entry carries ID, name, short code, last-updated date, and data/metadata availability
• Source IDs (e.g. 2 for World Development Indicators) feed source_id on worldbank_search_indicators

---

worldbank_list_countries _tool

• Filters by region code (EAS, SSF, … plus membership groupings such as AFE, EUU, LDC), income level (LIC, LMC, UMC, HIC), and lending type (IDX, IBD, IDB, LNX), combined by AND; up to 150 per page (~50 KB)
• Returns ISO codes, region, income level, lending type, capital, and coordinates; an invalid region or income code is a typed invalid_filter error
• Individual countries only by default — include_aggregates=true adds regional, income-group, and world aggregates, flagged isAggregate

---

worldbank_get_country _tool

• Accepts one ISO2 (US), ISO3 (USA), or World Bank aggregate code (EAS, HIC, WLD) — all or a list is rejected as multiple_countries
• Returns region, income level, lending type, capital, and coordinates
• Typed country_not_found error with a recovery hint pointing to worldbank_list_countries

---

worldbank_search_indicators _tool

• At least one of query, topic_id, or source_id; every keyword term must match the indicator ID, name, or description, in any order; up to 100 per page
• Ranked exact ID/name matches first, then names starting with the phrase, then looser matches, then description-only ones; World Development Indicators series lead each tier, and a series leads its own breakdowns (SP.DYN.LE00.IN ahead of SP.DYN.LE00.FE.IN)
• Each indicator ID appears once, with the first 150 characters of its description; worldbank_get_indicator returns the whole

---

worldbank_get_indicator _tool

• One indicator ID per call, made of letters, digits, ., _, or - — all, a list, or any other character is rejected
• Returns description, unit, source dataset, source organization, and topics; HTML line breaks in the description are preserved, other markup is stripped
• Typed indicator_not_found error pointing to worldbank_search_indicators

---

worldbank_get_data _tool

• countries as ISO2, ISO3, aggregate codes, WLD, or all alone; at most one of date_range (a year, quarter, or month, or a range of one type), mrv (the latest N periods across the countries), or mrnev (each country's own latest N values — Eritrea's GDP per capita at 2011, where mrv gives 2025 and null); frequency (annual, quarterly, monthly) picks the period form on series that publish several (CPTOTSAXN for Kenya, monthly, mrv: 3 → 2026M07–M05); up to 200 observations a page (~50 KB)
• Rows carry both country codes, isAggregate, and value: null for a missing cell, with nullCount per page and lastUpdated, the source's data vintage; every date_range, mrv, and mrnev read is checked for another query's cached answer and re-read once, and one that fails twice is an upstream_inconsistent error rather than a served result
• Indicators the standard endpoint doesn't serve (WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition) come from their own dataset, disclosed in sourceScoped with the release, classification, sector, or counterpart area applied (dimension_value)

---

worldbank_get_poverty _tool

• Economies by ISO3 or ISO2 code, including those PIP publishes only as model estimates (AFG), plus PIP's aggregates: WLD, regions (SSF, AFE), income groups (LMIC/LMC), lending groups (IDX, IDB, IBD, REST), and fragility groups (FCVY, FCVN; WDI's FCS is rejected with FCVY guidance, without asserting the same membership); year as a year, all, or MRV; any poverty_line, defaulting to the applied PPP vintage's international line; up to 70 estimates a page (~50 KB)
• Headcount, gap, severity, and Watts index, plus the Gini coefficient, mean log deviation, polarization, and decile shares on survey rows; estimationType separates survey rows from gap-filled ones, whose inequality fields are null, and isAggregate flags aggregate rows
• fill_gaps (default true) includes gap-filled years; welfare_type and reporting_level narrow economy results, and ppp_version picks the PPP vintage

---

worldbank_search_projects _tool

• Free-text query combined by AND with countries (ISO3, ISO2, or a World Bank regional code such as 3A), region, status, financial_type, and a board-approval window (approved_from/approved_to); up to 80 projects a page, newest approval first
• Returns ID, name, country, region, status, dates, the commitment amount with its IBRD, IDA, and grant parts, financing windows, sectors, and a URL; countryCodes chain into the other tools, a bad code or unparseable query is a typed invalid_country_code / invalid_query error, and an empty result names the filter that emptied it
• include_abstract (off by default) adds abstracts at 8 projects a page, each cut at 5,000 characters

---

worldbank://indicator/{indicatorId} _resource

• Indicator metadata as application/json — name, description, unit, source dataset, source organization, and topics
• indicatorId comes from worldbank_search_indicators; an unknown ID returns a typed not-found error with a recovery hint, while an upstream outage or timeout keeps its own classification instead of reading as a bad ID

---

worldbank://country/{countryCode} _resource

• Country/aggregate metadata as application/json — ISO codes, region, income level, capital, coordinates
• Accepts one ISO2, ISO3, or World Bank aggregate code — all or a list is rejected; an unknown code returns a typed not-found error, distinct from a transient upstream failure

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

World Bank-specific:

• Full World Bank Open Data coverage across three separate upstream APIs — the Indicators API, the Poverty and Inequality Platform, and the Projects lending portfolio
• 60+ years of development data (PIP coverage from 1963) across 29,500+ indicators for 200+ countries and regional aggregates
• Client-side keyword search over the indicator catalog, since the upstream searchterm parameter doesn't filter
• 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 (totalCount, currentPage, totalPages) across all list/search/data tools, with a notice naming the pages that exist when a request runs past the end

Getting started

Public Hosted Instance

A public instance is available at https://worldbank.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "type": "streamable-http",
      "url": "https://worldbank.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "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):

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

Or with Docker:

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/worldbank-mcp-server:latest"
      ]
    }
  }
}

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.4.0 or higher (or Node.js ≥24.0.0).
• No API key required — the World Bank Open Data API is public and unauthenticated.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd worldbank-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# edit .env and set optional overrides

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_SESSION_MODE	HTTP session handling: stateful, stateless, or auto. The server declares stateless in code — it holds no per-session state — and a value set here overrides that declaration	stateless
MCP_LOG_LEVEL	Log level (debug, info, notice, warning, error)	info
LOG_TOOL_FAILURE_PAYLOADS	Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted	false
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	Enable OpenTelemetry	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Opt-in OTLP log export (e.g. http://localhost:4318/v1/logs); the base OTEL_EXPORTER_OTLP_ENDPOINT never enables it	none
WORLDBANK_API_BASE_URL	World Bank Indicators API base URL override	https://api.worldbank.org/v2
WORLDBANK_PIP_BASE_URL	Poverty and Inequality Platform API base URL override	https://api.worldbank.org/pip/v1
WORLDBANK_PROJECTS_BASE_URL	Projects API base URL override	https://search.worldbank.org/api/v3
WORLDBANK_DEFAULT_PER_PAGE	Default page size for list/search/data operations; worldbank_get_data, worldbank_list_countries, worldbank_search_projects, and worldbank_get_poverty still cap it at their own page limits	50
WORLDBANK_CATALOG_CACHE_TTL_MS	Lifetime of the in-process reference caches — the indicator catalog behind keyword-only search, the country index behind isAggregate, source-scoped country codes, and poverty ISO2 codes, each source-scoped dataset's concept/country/period/dimension listings, and PIP's versions listing behind ppp_version, regions table behind aggregate codes, and economy list behind model-estimate-only economies; 0 disables them all	3600000

See .env.example for the full list of optional overrides.

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  # Lint, format, typecheck, and more
  bun run test      # Runs the test suite
  

Docker

docker build -t worldbank-mcp-server .
docker run --rm -p 3010:3010 worldbank-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/worldbank-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/mcp-server/tools	Tool definitions (*.tool.ts). Nine tools covering topics, sources, countries, indicators, data, poverty, and projects.
src/mcp-server/resources	Resource definitions. Indicator and country metadata resources.
src/services/worldbank	World Bank Indicators API service layer — API client and domain types.
src/services/pip	Poverty and Inequality Platform API service layer — separate client and domain types.
src/services/projects	Projects API service layer — separate 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
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues 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.