Stats Nz

What Stats Nz does

Stats Nz provides MCP access to New Zealand’s official statistics through the Aotearoa Data Explorer API. Its catalogue search covers 911 published dataflows and returns identifiers, titles, descriptions where available, agencies, and versions. Agents can then use a dataset identifier to retrieve observations, inspect dimensions and code lists, or query a dedicated census smoking-by-region view.

The available datasets include the 2013, 2018, and 2023 censuses, LEED earnings, business demography, population estimates and projections, household expenditure, corrections, and justice. The integration is independent and unofficial; it is not published or endorsed by Stats NZ.

How it works

The hosted MCP endpoint is available at https://gateway.pipeworx.io/stats-nz/mcp. Add that URL to an MCP client and call the exposed tools. The catalogue is fetched from Stats NZ’s keyless dataflow endpoint. Observation and structure requests use the live api.data.stats.govt.nz host and require the platform subscription key or a caller-provided _apiKey.

Stats NZ returns SDMX data. Stats Nz translates the response into period/value records with dimension labels and can expose the structure needed to interpret compact keys such as 1.2.Q. It also handles the catalogue’s SDMX-ML response format and the flat observation layout used by the upstream API.

For an unfiltered request that is too broad, the integration may select total geography or other total-coded dimensions and return a narrowed explanation. A caller-supplied key is not changed. Dataset identifiers are checked against the catalogue before observation requests, helping distinguish an unknown dataset from an empty result.

Setup and configuration

Configure the MCP URL in a compatible client, for example:

{
  "mcpServers": {
    "stats-nz": {
      "url": "https://gateway.pipeworx.io/stats-nz/mcp"
    }
  }
}

The gateway uses PLATFORM_STATSNZ_KEY for its Stats NZ subscription credential. Callers do not need their own key when the platform credential is available. A Stats NZ API subscription can also be obtained through the Aotearoa Data Explorer API product, and individual tool calls support a _apiKey override.

Tools and capabilities

• statsnz_datasets: Search the full catalogue by keyword with limit and offset. This tool is keyless.
• statsnz_observations: Retrieve observations for a dataset, optionally constrained by agency, version, dimension key, period range, or the last N observations.
• statsnz_resources: Return dimension order, time-dimension information, measures, and code lists. Code-list expansion can be controlled with includeCodes and maxCodesPerList.
• statsnz_smoking_by_region: Return census smoking-status counts and percentages by regional council for 2006, 2013, 2018, and 2023.

Observation responses may report collapsed dimensions when lastNObservations removes one axis from the returned keys. Period filters apply when the dataset declares the standard TIME_PERIOD dimension; other year-like dimensions may need to be selected through the dataset key.

Limitations and notes

The smoking tool covers census self-reports and should not be treated as the Ministry of Health New Zealand Health Survey. The catalogue does not provide CPI, GDP, or merchandise-trade data. Dataset descriptions are available for only part of the catalogue, so searches often depend on formal dataset titles.

A broad query can be automatically narrowed to stay within the response-size limit. The response identifies the requested key and the dimensions that were pinned. Queries with an explicit key are not narrowed and may fail if they are too large. A zero-result response includes an explanation such as an empty period range, an unmatched dimension key, or an upstream gap.

Use the current Stats NZ host through the MCP endpoint. The older api.stats.govt.nz host is not the service endpoint used by this integration, and SDMX flow-reference commas must remain literal when constructing upstream paths.