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

• Returns ISO codes, region, income level, capital, and coordinates; up to 300 per page

• Filterable by region code (EAS, ECS, LCN, MEA, NAC, SAS, SSF) and income level (LIC, LMC, UMC, HIC); an invalid code is a typed invalid_filter error

• Individual countries only by default — include_aggregates=true adds regional, income-group, and world aggregate entries, distinguished by 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 is required; a topic and a source together narrow to indicators in both

• Keyword search runs client-side over the full catalog (or the selected topic/source): every term must match the indicator ID, name, or description, in any word order, punctuation ignored — a query with no letters or digits is rejected

• Ranking: exact ID/name matches first, then whole-phrase matches, then other ID/name matches, then description-only matches

• Each indicator ID appears once, even where the catalog publishes it under both a live source and an archived copy

• Echoes the applied query, topic_id, and source_id; paginated up to 100 per page

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: single code, array, or comma-/semicolon-separated string — ISO2, ISO3, regional/income aggregate codes, WLD, or all alone for every entry; an empty value is rejected rather than read as all

• date_range (a year, quarter, or month, or a colon-separated range of the same period type, earliest first) and mrv (1–100 most recent values) are mutually exclusive; a reversed range or all mixed with codes is rejected before any request

• Sparse cells return value: null; nullCount per page surfaces sparsity, and isAggregate distinguishes aggregates from individual countries

• Indicators the standard endpoint doesn't serve (WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition) are answered from their own catalog source instead — the response carries sourceScoped, naming the source and the applied dimension_value (a release, classification, sector, or counterpart area)

• Paginated up to 1000 per page; echoes the normalized request as appliedFilters

worldbank_get_poverty tool

• Individual economies only, by ISO3 code, from the Poverty and Inequality Platform (PIP) — a separate dataset from the WDI series the other tools read; regional and aggregate codes are rejected

• Headcount ratio, poverty gap, severity, and the Watts index at any poverty_line (defaults to the international line of the applied PPP vintage); the same row carries the Gini coefficient, mean log deviation, polarization, and ten decile shares

• estimationType: "survey" rows carry the full inequality block; interpolation/extrapolation/CMD estimation rows are gap-filled and null out gini, mld, polarization, and decileShares — fill_gaps (default true) controls whether gap-filled years are returned at all

• welfare_type (income/consumption) and reporting_level (national/urban/rural) narrow results; ppp_version picks the PPP vintage, defaulting to the newest

• year accepts a four-digit year, all, or MRV; coverage starts in 1963

• Paginated locally, capped at 70 estimates per page (~50 KB) regardless of the requested per_page, since PIP itself has no pagination

worldbank_search_projects tool

• Free-text query across project names, abstracts, and objectives, combined by AND with exact filters on countries, region (World Bank operational regions), status (Active, Closed, Dropped, Pipeline), and a board-approval date window (approved_from/approved_to, real calendar days, earliest first)

• Countries are ISO2 here (BR, IN, ZA) or a two-character World Bank regional code (3A, 4E) — the one place this server departs from the ISO3 codes its other tools take; an ISO3 code is rejected as invalid_country_code rather than silently returning zero hits

• Returns project ID, name, borrowing country/region, status, board approval and closing dates, total commitment in USD, financing windows, major sectors, and a project-page URL

• include_abstract (off by default) always returns each abstract whole, capping a page at 8 projects instead of 80 to keep responses within ~50 KB

• An empty result names which filter emptied it — when a country filter was in force, the response reports whether the codes match anything on their own

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.