worldbank-mcp-server

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

Overview

World Bank Open Data across three separate upstream APIs — development indicators, poverty and inequality estimates, and the Bank's lending portfolio. Search the 29,500+ indicator catalog, query country-level time series, pull poverty and inequality metrics from the Poverty and Inequality Platform, and search active and historical lending projects from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

Related MCP server: worldbank-mcp

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), and lending groups (IDX, IDB, IBD, REST); 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:

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

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.