# `worldbank__worldbank_get_data`

**Get World Bank Indicator Data**

Query World Bank indicator values for one or more countries across a time range — the primary data-access tool; find indicator_id values with worldbank_search_indicators. Observations carry a null value where data is not available for a country×year cell, which is common for sparse series. Set either date_range (historical analysis) or mrv (most recent N values), not both. For "all" countries, page through the results (per_page up to 1000), since the API returns several hundred entries per indicator. Indicators the standard data endpoint does not serve — WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition — are answered from their own dataset instead; the response then carries sourceScoped, naming that dataset and the release, classification, sector, or counterpart area applied (see dimension_value), because those values can be archived or superseded figures rather than current ones.

- Server: [World Bank](https://gateway.mcpharbor.dev/docs/servers/worldbank) (`dev.mcpharbor.gateway/worldbank`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/worldbank`
- Upstream tool: exposed by the provider; called through this gateway as `worldbank__worldbank_get_data`
- Provider terms: <https://data.worldbank.org/summary-terms-of-use> (verified 2026-09-19)
- Upstream API documentation: <https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation>
- Rate limit: 500 requests per minute
- Attribution required: "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Parameters

- `countries` (any, required): 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" on its own ...
- `date_range` (string, optional): Time window to filter observations to. Accepts a whole year (\`2020\`), a quarter (\`2020Q1\`), or a month (\`2020M03\`), or a range of two periods of the same type separated by a colon, earliest first (...
- `dimension_value` (string, optional): For indicators answered from their own dataset (the response carries sourceScoped), the id of the value of that dataset's extra dimension to query, matched case-insensitively: a WDI Database Archiv...
- `indicator_id` (string, required): One indicator code to query (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) — not "all" or a list of codes. Use worldbank_search_indicators to find valid IDs.
- `mrv` (integer, optional): Return the N most recent periods (1–100) holding a value for any requested country, clamped to the length of the series. Every requested country comes back at those periods, null where it has no va...
- `page` (integer, optional): Pagination page number (1-based). Default: `1`.
- `per_page` (integer, optional): Results per page (default: server default, max: 1000). Use higher values for "all" country queries.

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: worldbank__worldbank_get_data
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "countries": "example",
      "indicator_id": "example"
    },
    "name": "worldbank__worldbank_get_data"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Query World Bank indicator values for one or more countries across a time range — the primary data-access tool; find indicator_id values with worldbank_search_indicators. Observations carry a null value where data is not available for a country×year cell, which is common for sparse series. Set either date_range (historical analysis) or mrv (most recent N values), not both. For \"all\" countries, page through the results (per_page up to 1000), since the API returns several hundred entries per indicator. Indicators the standard data endpoint does not serve — WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition — are answered from their own dataset instead; the response then carries sourceScoped, naming that dataset and the release, classification, sector, or counterpart area applied (see dimension_value), because those values can be archived or superseded figures rather than current ones.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "countries": {
        "anyOf": [
          {
            "description": "A single country code, a comma- or semicolon-separated list, or \"all\".",
            "pattern": "[^\\s;,]",
            "type": "string"
          },
          {
            "description": "An array of country codes.",
            "items": {
              "description": "A country code.",
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          }
        ],
        "description": "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\" on its own for every entry (use pagination). Pass a single code, an array, or one string separated by commas or semicolons. At least one code is required — an empty value is rejected rather than treated as \"all\"."
      },
      "date_range": {
        "description": "Time window to filter observations to. Accepts a whole year (`2020`), a quarter (`2020Q1`), or a month (`2020M03`), or a range of two periods of the same type separated by a colon, earliest first (`2010:2023`, `2020Q1:2021Q4`, `2020M01:2020M06`); a range running latest first is rejected. A window and an observation match whenever the periods overlap, so a year window also selects the quarters and months inside it. A window covering no part of the series returns zero observations rather than the full series. Mutually exclusive with mrv.",
        "pattern": "^\\s*(?:\\d{4}(?::\\d{4})?|\\d{4}[Qq][1-4](?::\\d{4}[Qq][1-4])?|\\d{4}[Mm](?:0[1-9]|1[0-2])(?::\\d{4}[Mm](?:0[1-9]|1[0-2]))?)?\\s*$",
        "type": "string"
      },
      "dimension_value": {
        "description": "For indicators answered from their own dataset (the response carries sourceScoped), the id of the value of that dataset's extra dimension to query, matched case-insensitively: a WDI Database Archives release (\"202503\"), an ICP or Food Prices for Nutrition classification (\"PPPGlob\", \"FPN 5.0\"), a GDLD sector (\"WHT\"), or an International Debt Statistics counterpart area (\"265\"). Omit it for the default, which sourceScoped.dimension reports: the only value when the dataset has one, \"WLD\" (World) for counterpart areas, the newest WDI Database Archives release holding data for the requested countries and periods (the newest release when none does), or otherwise every value with each row labelled. A value the dataset does not list is rejected with the valid ids, and a value for an indicator the standard data endpoint serves is rejected too.",
        "type": "string"
      },
      "indicator_id": {
        "description": "One indicator code to query (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) — not \"all\" or a list of codes. Use worldbank_search_indicators to find valid IDs.",
        "pattern": "^[A-Za-z0-9._-]+$",
        "type": "string"
      },
      "mrv": {
        "description": "Return the N most recent periods (1–100) holding a value for any requested country, clamped to the length of the series. Every requested country comes back at those periods, null where it has no value there rather than with its own older values. Rows are mrv × countries, so page through them with per_page. Mutually exclusive with date_range.",
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      },
      "page": {
        "default": 1,
        "description": "Pagination page number (1-based).",
        "maximum": 9007199254740991,
        "minimum": 1,
        "type": "integer"
      },
      "per_page": {
        "description": "Results per page (default: server default, max: 1000). Use higher values for \"all\" country queries.",
        "maximum": 1000,
        "minimum": 1,
        "type": "integer"
      }
    },
    "required": [
      "indicator_id",
      "countries"
    ],
    "type": "object"
  },
  "name": "worldbank__worldbank_get_data",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "data",
          "indicator",
          "nullCount",
          "appliedFilters",
          "totalCount",
          "currentPage",
          "totalPages"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "appliedFilters": {
        "additionalProperties": false,
        "description": "The effective parameters sent to the World Bank API — confirms country code normalization and which filters were in force for these observations.",
        "properties": {
          "countries": {
            "description": "Country codes as sent to the API — array elements and comma- or semicolon-separated strings are split and rejoined with semicolons, so this shows the normalized value.",
            "type": "string"
          },
          "dateRange": {
            "description": "Date window applied, omitted when none was requested.",
            "type": "string"
          },
          "dimensionValue": {
            "description": "dimension_value as requested, omitted when none was given.",
            "type": "string"
          },
          "indicatorId": {
            "description": "Indicator ID queried.",
            "type": "string"
          },
          "mrv": {
            "description": "Most-recent-values count applied, omitted when none was requested.",
            "type": "number"
          },
          "page": {
            "description": "Page number requested.",
            "type": "number"
          },
          "perPage": {
            "description": "Results per page used, including the server default.",
            "type": "number"
          }
        },
        "required": [
          "indicatorId",
          "countries",
          "page",
          "perPage"
        ],
        "type": "object"
      },
      "currentPage": {
        "description": "Page number requested — past totalPages when the request ran off the end.",
        "type": "number"
      },
      "data": {
        "description": "Indicator observations for this page. Null values are common for sparse series.",
        "items": {
          "additionalProperties": false,
          "description": "A single country×period observation.",
          "properties": {
            "countryCode": {
              "description": "ISO2 country code (or aggregate code).",
              "type": "string"
            },
            "countryIso3": {
              "description": "ISO3 country code (empty for some aggregates).",
              "type": "string"
            },
            "countryName": {
              "description": "Country or aggregate name.",
              "type": "string"
            },
            "date": {
              "description": "Period of observation: a year (2020), quarter (2020Q1), or month (2020M03).",
              "type": "string"
            },
            "dimension": {
              "additionalProperties": false,
              "description": "The value of the dataset's extra dimension (sourceScoped.dimension.concept) this row belongs to. Present on source-scoped rows from a dataset that has one.",
              "properties": {
                "id": {
                  "description": "Dimension value id, e.g. \"202503\".",
                  "type": "string"
                },
                "label": {
                  "description": "Dimension value label, e.g. \"2025 Mar\".",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "label"
              ],
              "type": "object"
            },
            "isAggregate": {
              "description": "True when this row is a regional or income-group aggregate rather than an individual country.",
              "type": "boolean"
            },
            "obsStatus": {
              "description": "Observation status code (empty string when no special status; non-empty values signal data quality notes).",
              "type": "string"
            },
            "value": {
              "description": "Indicator value. Null when data is not available for this country×year cell.",
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "countryCode",
            "countryIso3",
            "countryName",
            "date",
            "value",
            "obsStatus",
            "isAggregate"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `invalid_params`: Both date_range and mrv are provided simultaneously. `mixed_all_selector`: countries combines \"all\" with one or more country codes. `reversed_date_range`: date_range names a range whose first period comes after its second. `multiple_indicators`: The indicator ID is \"all\", which selects every indicator rather than one. `indicator_not_found`: The indicator ID does not exist. `indicator_not_queryable`: The standard data endpoint does not serve the indicator, and no catalog source can serve it through the source-scoped data API instead — the catalog no longer lists the ID, the catalog lookup failed, or the source is not organized by country, series, and time plus at most one further dimension. `unknown_dimension_value`: dimension_value is not a value the indicator's dataset lists for its extra dimension. `dimension_not_applicable`: dimension_value is given for an indicator the standard data endpoint serves, or whose dataset has no dimension beyond country, series, and time. `source_scope_too_large`: A source-scoped query would read more rows (countries × periods × unpinned dimension values) than one request allows. `country_not_found`: One or more country codes are invalid. `indicator_and_country_not_found`: The indicator ID and the country codes are both invalid. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "invalid_params",
                  "mixed_all_selector",
                  "reversed_date_range",
                  "multiple_indicators",
                  "indicator_not_found",
                  "indicator_not_queryable",
                  "unknown_dimension_value",
                  "dimension_not_applicable",
                  "source_scope_too_large",
                  "country_not_found",
                  "indicator_and_country_not_found"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "indicator": {
        "additionalProperties": false,
        "description": "Indicator metadata echoed from the response.",
        "properties": {
          "id": {
            "description": "Indicator ID echoed for chaining context.",
            "type": "string"
          },
          "name": {
            "description": "Indicator name.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "type": "object"
      },
      "notice": {
        "description": "Recovery hint for an empty result set — how to broaden the query when nothing matched, or the page range that exists when the requested page is past the end — and, for source-scoped data, the requested country codes the serving dataset publishes nothing for.",
        "type": "string"
      },
      "nullCount": {
        "description": "Count of null values on this page — indicates data sparsity for the requested filter.",
        "type": "number"
      },
      "sourceScoped": {
        "additionalProperties": false,
        "description": "Present only when the standard data endpoint does not serve the indicator and its catalog source served the values instead. Absent for indicators the standard endpoint serves.",
        "properties": {
          "dimension": {
            "anyOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "concept": {
                    "description": "The extra dimension: Version, Classification, Sector, or Counterpart-Area.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Applied value id; null for every_value.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "label": {
                    "description": "Applied value label; null for every_value.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "selection": {
                    "description": "How the value was chosen: requested (dimension_value), only_value (the only one the dataset lists), world_total (WLD, all counterpart areas), newest_with_data (newest release holding a value for the requested countries and periods), newest (newest release; none holds a value in that scope), or every_value (no single value; each row carries its own).",
                    "enum": [
                      "requested",
                      "only_value",
                      "world_total",
                      "newest_with_data",
                      "newest",
                      "every_value"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "concept",
                  "selection",
                  "id",
                  "label"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "The dimension value applied; null when the dataset has no extra dimension."
          },
          "note": {
            "description": "States that the values came from the source-scoped data API rather than the standard World Bank data endpoint, and may be archived or superseded figures.",
            "type": "string"
          },
          "sourceId": {
            "description": "ID of the World Bank data source that served the values.",
            "type": "string"
          },
          "sourceName": {
            "description": "Name of that data source, e.g. \"WDI Database Archives\".",
            "type": "string"
          }
        },
        "required": [
          "sourceId",
          "sourceName",
          "dimension",
          "note"
        ],
        "type": "object"
      },
      "totalCount": {
        "description": "Total observations before pagination.",
        "type": "number"
      },
      "totalPages": {
        "description": "Total number of pages.",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Get World Bank Indicator Data"
}
```