# World Bank Indicators MCP Server

Read-only Model Context Protocol server for country and economic data from the
[World Bank Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). No API key or
credentials are required. This independent project is not affiliated with or
endorsed by the World Bank Group.

## Tools

| Tool | Use |
| --- | --- |
| `find_countries` | Resolve country codes by name, region, or income level. |
| `get_indicator_metadata` | Read an indicator definition, source, and topics. |
| `get_indicator_data` | Fetch a paginated time series for up to 20 countries. |
| `compare_countries` | Compare latest non-empty indicator values across countries. |
| `get_country_profile` | Read latest GDP, growth, population, inflation, and unemployment data. |

Every tool has bounded input and structured output schemas plus read-only MCP
annotations. HTTP, network, timeout, and malformed-response failures return
bounded tool errors without writing protocol noise to stdout.

## Requirements

- Node.js 20 or newer.
- Network access to `https://api.worldbank.org`.

## Run With npx

After npm publication, run the pinned package without cloning:

```powershell
npx -y world-bank-indicators-mcp@0.1.0
```

The process is a stdio MCP server. Direct terminal use waits silently for
JSON-RPC input.

For source development after GitHub publication:

```powershell
git clone https://github.com/ryanngit/world-bank-indicators-mcp.git
cd world-bank-indicators-mcp
npm ci
npm run verify
npm run build
node .\dist\src\index.js
```

## Claude Desktop

Add this entry to Claude Desktop configuration. It uses the future pinned npm
release and needs no local source path or environment variables.

```json
{
  "mcpServers": {
    "world-bank-indicators": {
      "command": "npx",
      "args": ["-y", "world-bank-indicators-mcp@0.1.0"]
    }
  }
}
```

Configuration locations:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Save the file and restart Claude Desktop. On Windows, if Claude cannot resolve
`npx`, use `"command": "cmd"` and prepend `"/c", "npx"` to `args`.

## Examples

Resolve country codes:

```json
{
  "name": "find_countries",
  "arguments": {
    "query": "united",
    "limit": 10
  }
}
```

Compare latest reported GDP values:

```json
{
  "name": "compare_countries",
  "arguments": {
    "countries": ["CAN", "MEX", "USA"],
    "indicator": "NY.GDP.MKTP.CD"
  }
}
```

Read a bounded time series page:

```json
{
  "name": "get_indicator_data",
  "arguments": {
    "countries": ["IND", "CHN"],
    "indicator": "SP.POP.TOTL",
    "startYear": 2015,
    "endYear": 2023,
    "page": 1,
    "pageSize": 100
  }
}
```

`get_indicator_data` returns `page`, `pages`, `perPage`, and `total` metadata.
Use `page` to retrieve later result pages.

## Development

```powershell
npm run typecheck
npm test
npm run verify
npm audit --audit-level=high
npm pack --dry-run --json
```

Tests use Node's built-in test runner and deterministic fetch fixtures. They do
not require live World Bank access. Package tests guard repository and license
metadata against unresolved publication markers.

For an optional local protocol check with
[`mcp-smoke`](https://github.com/ryanngit/mcp-smoke):

```powershell
git clone --branch v0.1.0 --depth 1 https://github.com/ryanngit/mcp-smoke.git .mcp-smoke
python .\.mcp-smoke\mcp_smoke.py check --out .\mcp-smoke-out --server-name world-bank-indicators --overwrite -- node .\dist\src\index.js
```

## Data Attribution

Data and indicator metadata come from the World Bank Indicators API. The
software license in this repository does not relicense World Bank data. Review
the [World Bank dataset terms](https://www.worldbank.org/en/about/legal/terms-of-use-for-datasets)
and each indicator's source metadata before redistribution or production use.

## Limitations

- Live values can be revised, delayed, or absent for some country-year pairs.
- Latest non-empty observations can come from different years by country.
- Requests have a 10-second full-response timeout and no retry or cache layer.
- `find_countries` excludes aggregate regions by default; set
  `includeAggregates` to include them.
- Inputs allow at most 20 countries, 100 years per request, 1,000 records per
  page, and page numbers through 10,000.
- `get_country_profile` always returns five fixed metrics. Missing values use
  `status: "missing"` with null `year` and `value`.

## Support

Search or open a reproducible report in
[GitHub Issues](https://github.com/ryanngit/world-bank-indicators-mcp/issues).
Include server version, Node.js version, tool name, sanitized input, and error
text. Do not include credentials or private conversation content.

## License

MIT. Copyright (c) 2026 ryanngit.