ONS + Nomis MCP server

An MCP server over two UK statistics platforms, exposed from one server:

1. ONS beta Customise My Data (https://api.beta.ons.gov.uk/v1) — headline economic and social time series (CPIH, regional GDP, wellbeing). Open, no key, rate-limited to 120 req/10s and 200/min.
2. Nomis (https://www.nomisweb.co.uk/api/v01) — census and labour-market statistics (Claimant Count, Annual Population Survey, Census 2011/2021 tables, workforce jobs). Open; an optional uid (NOMIS_API_KEY) lifts limits for large queries.

The two APIs share no dimension model, so the Nomis tools are namespaced nomis_*. Rule of thumb: ONS beta for headline economic indicators, Nomis for granular local-area, census and labour-market tables.

Implementations

Two interchangeable implementations of the same 18-tool surface live here:

• Python (ons_mcp/, FastMCP) — the reference implementation.
• .NET / C# (dotnet/, ASP.NET Core + the MCP C# SDK) — a like-for-like port, and what runs in production.

Both expose the identical tools and behaviour. The live service is https://ons-mcp.library-apps.dev/mcp (the .NET container, behind Cloudflare Access). See dotnet/README.md for the port and docs/deploy.md for deployment.

Which route to use

For headline indicators — use get_timeseries. It serves the published figure straight from the ONS website's series (the same number ONS quotes), already chronologically ordered.

For multi-dimensional slicing — use the CMD dataset tools. They can filter by geography, age, category etc. in ways the published series can't.

CMD curation is uneven. Some datasets track publication closely (weekly-deaths-region, updated within days); others lag badly (cpih01 was five months behind the published CPIH series in July 2026; regional-gdp-by-year was three years behind). get_dataset and search_datasets return last_updated and a staleness_warning — check them before quoting a CMD figure.

Option codes can also change between versions (cpih1dim1A0 in v1 became CP00 in v67). A wrong code returns zero observations, not an error — get_observations now diagnoses this and lists valid codes.

ONS beta API — data model

Datasets are held in tidy format. Every dataset has a time and a geography dimension plus one or more topic dimensions. A dataset is published as versions, grouped into editions. A single observation is addressed by one option code per dimension; one dimension may be a * wildcard to sweep a whole axis (e.g. a full time series) in one call.

Tools

The tools are designed to be called in sequence, discovery-first:

Tool	Purpose
get_timeseries	Published headline series by URI — prefer for latest rates
list_datasets	Page through the catalogue
search_datasets	Client-side substring search over title/description/keywords
get_dataset	Resolve a dataset's latest edition + version
get_dimensions	List a version's variables
get_options	List valid option codes for one dimension
get_observations	Fetch observation(s); one dimension may be *
get_metadata	Provenance and bulk CSV/XLSX download links
list_releases	Live release calendar — upcoming/published/cancelled
get_release	One release: confirmed vs provisional date, related datasets
list_topics	Browse the ONS topic taxonomy (root, or a topic's subtopics)
get_topic_content	Publications under a topic; bridges series to get_timeseries

Typical flow: search_datasets("inflation") → get_dataset("cpih01") → get_dimensions(...) → get_options(..., "aggregate") → get_observations(..., {"time": "*", "geography": "K02000001", "aggregate": "CP00"}).

Geography uses ONS codes, e.g. K02000001 = United Kingdom.

Discovery: releases and topics

Release calendar. list_releases(status="upcoming") is the authoritative schedule of ONS publications — use it for "when is the next X out", not the next_release field on get_timeseries/get_dataset, which is a snapshot from the last publication and can be stale (it reported 15 July when the calendar said 22 July). get_release(uri) gives one entry's confirmed-or-provisional date, any cancellation notice, and the datasets it will contain.

Topics. list_topics() returns the top-level taxonomy; pass a topic id (list_topics(parent_id="1245")) to drill into subtopics. get_topic_content(topic_id) lists the bulletins, articles and key series under a topic — and fills in timeseries_uri on series items so you can hand them straight to get_timeseries.

Nomis tools

Tool	Purpose
nomis_search_datasets	Keyword search over the Nomis catalogue
nomis_get_dataset	Dataset overview + dimensions (with conceptrefs)
nomis_dimension_options	Valid codes for a dimension (e.g. sex, age, measures)
nomis_geography_search	Resolve a place name to Nomis geography code(s)
nomis_get_data	Fetch observations (simple flat JSON)
nomis_data_url	Build a direct CSV/XLS/JSON bulk-download URL

Nomis uses internal integer codes, not ONS mnemonics, and they differ per dataset — always resolve via nomis_dimension_options / nomis_geography_search first. Data retrieval uses Nomis' simple JSON format (flat records with named dimensions), avoiding SDMX positional-key decoding. measures=20100 (value) is usually required.

Typical flow: nomis_search_datasets("claimant") → nomis_get_dataset("NM_1_1") → nomis_geography_search("NM_1_1", "Birmingham") and nomis_dimension_options("NM_1_1", "sex") → nomis_get_data("NM_1_1", {"geography": "...", "sex": "5,6,7", "time": "latest", "measures": "20100"}).

Install

python -m venv .venv && . .venv/bin/activate
pip install -e .

Run

Stdio (default, for desktop clients):

ons-mcp

Streamable HTTP (for a self-hosted deployment behind a tunnel), served at /mcp:

ONS_MCP_HTTP=1 ONS_MCP_PORT=8095 ons-mcp

Bound to 127.0.0.1 by design — front it with Cloudflare Tunnel rather than exposing the port. In production it runs at https://ons-mcp.library-apps.dev/mcp, fronted by Cloudflare Access (Managed OAuth), with the origin re-verifying the Access JWT for defence in depth. See docs/deploy.md for the systemd unit, tunnel ingress and auth setup.

Verify

scripts/verify.py exercises both halves — the published-series route (get_timeseries) and the CMD route (search → observations, with staleness and the invalid-code diagnosis) — through the real in-memory MCP dispatch path against the live ONS API, plus the Cloudflare Access guard wiring:

python scripts/verify.py

Client config (stdio)

{
  "mcpServers": {
    "ons-beta": {
      "command": "ons-mcp"
    }
  }
}

Environment

Variable	Default	Meaning
ONS_API_BASE	https://api.beta.ons.gov.uk/v1	API root
ONS_API_TIMEOUT	30	Per-request timeout (s)
ONS_MCP_HTTP	unset	Set to 1 for HTTP transport (serves /mcp)
ONS_MCP_PORT	8095	HTTP port (bound to 127.0.0.1)
ONS_MCP_ALLOWED_HOSTS	ons-mcp.library-apps.dev,127.0.0.1,localhost	DNS-rebinding Host allowlist
CF_ACCESS_TEAM_DOMAIN	unset	Cloudflare Access team domain; enables origin-side JWT checks (with CF_ACCESS_AUD)
CF_ACCESS_AUD	unset	Access application AUD; both must be set to enforce auth
NOMIS_API_BASE	https://www.nomisweb.co.uk/api/v01	Nomis API root
NOMIS_API_KEY	unset	Optional Nomis uid for larger queries
NOMIS_API_TIMEOUT	60	Nomis per-request timeout (s)

Notes

The beta API has no server-side text search, so search_datasets pages the catalogue and filters locally. It's fine for a few hundred datasets but does one request per 100 items; cache the result if you call it often.

The ONS beta tools are verified end-to-end against the live API by scripts/verify.py (see Verify above). The Nomis tools were built against the documented SDMX-JSON structure and unit-tested for parsing, but not smoke-tested against the live Nomis service — validate the first few nomis_* calls in your environment.

Licence: the code is MIT — see LICENSE. The data it serves contains public sector information licensed under the Open Government Licence v3.0.