who-gho-mcp-server

<div align="center"> <h1>@cyanheads/who-gho-mcp-server</h1> <p><b>Query WHO Global Health Observatory data — 3,059 indicators across 194 member states with country, region, year, and sex filters via MCP. STDIO or Streamable HTTP.</b> <div>6 Tools • 2 Resources</div> </p> </div>

<div align="center">

      

</div>

<div align="center">

  


Public Hosted Server: https://who-gho.caseyjhand.com/mcp

</div>

---

Tools

6 tools for working with WHO Global Health Observatory data:

| Tool | Description | |:---|:---| | who_search_indicators | Search the GHO indicator catalog by keyword in indicator names | | who_list_indicators | Browse the full indicator catalog with pagination | | who_get_indicator_metadata | Fetch indicator names and supported filter dimensions for up to 10 codes | | who_list_dimensions | List all dimension type codes available in the GHO API | | who_list_dimension_values | List valid codes and labels for a dimension type (COUNTRY, REGION, SEX, etc.) | | who_query_indicator_data | Query data rows for an indicator with spatial, temporal, and dimension filters |

who_search_indicators

Search the WHO GHO indicator catalog by keyword.

• Substring match on indicator names — try terms like "life expectancy", "immunization", "mortality", "diabetes", or "HIV"
• Returns indicator codes and display names for use with who_query_indicator_data
• Reports total matches; suggests narrowing when the limit is reached
• Default limit 20, max 100

---

who_list_indicators

Browse the full indicator catalog with offset-based pagination.

• No keyword required — lists all 3,059+ indicators
• Pagination via limit (default 50, max 500) and offset
• Returns total and hasMore for iteration

---

who_get_indicator_metadata

Fetch metadata for one to ten indicator codes in a single call.

• Returns the full indicator name and the dimension types it supports (e.g. COUNTRY, SEX, REGION, AGEGROUP)
• Call before who_query_indicator_data to confirm which filter dimensions are valid
• Unresolved codes are reported in notFound rather than raising an error

---

who_list_dimensions

List all dimension type codes available in the GHO API.

• Returns every dimension type with its human-readable title
• Common types: COUNTRY, REGION, SEX, WORLDBANKINCOMEGROUP, AGEGROUP
• Use to discover codes before calling who_list_dimension_values

---

who_list_dimension_values

List valid filter values for a single dimension type.

• Returns codes and labels for every value under the dimension (e.g. all 194 country ISO codes, all WHO region codes)
• Includes optional parent hierarchy fields (parentCode, parentLabel, parentDimension)
• Use to confirm exact codes before passing them to who_query_indicator_data

---

who_query_indicator_data

Query data rows for a single WHO GHO indicator.

• Spatial filters (mutually exclusive): country_codes (ISO 3166-1 alpha-3), region_codes (WHO regions), or income_group_codes (World Bank groups)
• Time range filter: year_from / year_to
• Sex filter: SEX_BTSX (both), SEX_FMLE, SEX_MLE — only applies when the indicator uses SEX as its first cross-cutting dimension
• Arbitrary dim1_value for indicators using non-SEX cross-cutting dimensions
• Optional uncertainty interval bounds (low/high) via include_uncertainty (default true)
• Default limit 200, max 1000; returns totalRows and truncated for handling large result sets
• Primary data tool in the find-then-query workflow

Resources

| Type | URI | Description | |:---|:---|:---| | Resource | who://indicator/{indicatorCode}/metadata | Indicator name and supported filter dimensions for a single code | | Resource | who://dimension/{dimensionCode}/values | All valid values for a dimension type |

Recommended workflow

1. who_search_indicators — find indicator codes by keyword
2. who_get_indicator_metadata — confirm which filter dimensions the indicator supports
3. who_query_indicator_data — fetch data with country/region/year/sex filters

To look up filter codes: who_list_dimensions → who_list_dimension_values.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

WHO GHO-specific:

• Full coverage of the WHO GHO OData API v2 — indicators, dimensions, dimension values, and data queries
• Configurable base URL and request timeout for custom or mirrored deployments
• Parallel metadata fan-out for multi-code indicator lookups

Agent-friendly output:

• Tool descriptions encode the cross-tool workflow — agents discover the right call order from descriptions alone
• Structured truncation signaling (truncated, truncatedNote, hasMore) so agents can decide whether to paginate
• Discriminated error codes with recovery hints on every failure path

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/who-gho-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/who-gho-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.3.2 or higher (or Node.js ≥24).
• No API key required — the WHO GHO API is public.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd who-gho-mcp-server

1. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

| Variable | Description | Default | |:---|:---|:---| | MCP_TRANSPORT_TYPE | Transport: stdio or http | stdio | | MCP_HTTP_PORT | HTTP server port | 3010 | | 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_LOG_LEVEL | Log level (debug, info, warning, error, etc.) | info | | MCP_GC_PRESSURE_INTERVAL_MS | Opt-in Bun-only forced-GC pressure loop (ms). Try 60000 if RSS grows under sustained HTTP load. | 0 (disabled) | | LOGS_DIR | Directory for log files (Node.js only) | <project-root>/logs | | STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1 | in-memory | | GHO_BASE_URL | WHO GHO OData API base URL (override for custom/mirrored deployments) | https://ghoapi.azureedge.net/api/ | | GHO_REQUEST_TIMEOUT_MS | HTTP request timeout in milliseconds | 30000 | | OTEL_ENABLED | Enable OpenTelemetry | false |

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  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

| Directory | Purpose | |:---|:---| | src/mcp-server/tools | Tool definitions (*.tool.ts). Six tools across indicator discovery, dimension lookup, and data queries. | | src/mcp-server/resources | Resource definitions. Indicator metadata and dimension values resources. | | src/services/gho | WHO GHO OData API service layer — HTTP client, query builder, 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

Contributing

Issues and pull requests 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.