Skip to main content
Glama
StatsMapped: Irish statistics (CSO, county & council data)

StatsMapped: Irish statistics (CSO, county & council data)

statsmapped-mcp

An MCP server exposing StatsMapped's public API as tools for AI agents (Claude Desktop, Cursor, and any other MCP client).

StatsMapped tracks public data for Ireland (by county) and the UK (by local authority) — housing, crime, health, the economy and social welfare — from official publishers (CSO, PSRA, Central Bank of Ireland, DHLGH, NTPF, the Office of Government Procurement, EU Publications Office for Ireland; ONS/HM Land Registry/Nomis/DfE/DfT for the UK), each figure carrying its own caveats. This package lets an agent query that data directly as tool calls instead of crawling and parsing web pages. Every tool below takes a country argument ("ireland" or "united-kingdom", default "ireland") — the two countries track genuinely different datasets and geography levels, so call query_data/list_areas for the country you actually want rather than assume Ireland's defaults apply.

This is a thin client. It calls StatsMapped's already-public, unauthenticated HTTPS API (documented at statsmapped.com/openapi.json); no API key is needed for anything below. Runs on your own machine over stdio by default (the recommended way to use it today) -- see Why stdio for a hosted streamable-http mode this package also supports, and the real tradeoff that comes with it.

Install

Published on PyPI as statsmapped-mcp (confirmed live: https://pypi.org/project/statsmapped-mcp/):

pip install statsmapped-mcp

Related MCP server: ELS MCP server

Configure

Add to your MCP client's config (for Claude Desktop, claude_desktop_config.json; Cursor uses an equivalent mcp.json):

{
  "mcpServers": {
    "statsmapped": {
      "command": "statsmapped-mcp"
    }
  }
}

Tools

6 tools (consolidated from an original 9 -- query_data and compare are each one tool with a few modes, chosen by which arguments you give, rather than several near-identical single-purpose ones). Every tool takes a country argument ("ireland" or "united-kingdom", default "ireland") — Ireland and the UK track different datasets and geography levels, so call query_data/list_areas for the country you want rather than assume Ireland's defaults apply.

  • query_data(area_id=None, dataset=None, history_months=0, country="ireland") — three modes:

    • neither area_id nor dataset: every stat StatsMapped tracks for one country, with its key, label, and which geography levels it's published at. Start here.

    • area_id given, dataset omitted: every dataset available for one area (e.g. "county:kerry" for Ireland, "uk:lad:e09000033" for the UK), with its latest figure and year-on-year change. Caveats are projected to label + severity only, not full text — the point is deciding which datasets matter before paying for the full detail on any one of them.

    • both area_id and dataset given: full detail on one dataset in one area — a written summary, full caveat text, and (optionally, via history_months) recent history.

  • list_areas(level="county", country="ireland") — every geography at one boundary level. level defaults to Ireland's 26 counties; the UK's own primary level is "lad" (local authority districts), not "county" — other levels exist per country too (Ireland's local_authority/garda_division among them).

  • compare(stat_key=None, level=None, pair_key=None, stat_key_a=None, stat_key_b=None, country="ireland") — four modes, exactly one set of arguments at a time (mixing them raises an error):

    • stat_key alone: every area at one level, ranked by its latest figure for that stat, highest first.

    • pair_key alone: full detail for one registered comparison pair — each axis's label/unit/publisher, the correlation stats (r, rho, a leave-one-out sensitivity range), and caveats. pair_key comes from the no-argument mode below.

    • both stat_key_a and stat_key_b: does StatsMapped have a registered, hand-vetted comparison between these two stats? Registry-backed only — never computes a fresh correlation for an arbitrary pair. comparable is a string, not a bool: "yes" (a registered, hand-vetted pair; pair_key names it), "no" (the two stats share no geography level at all), or "unknown" (not registered, but not ruled out: treat as "ask a human", not "probably yes"). "unknown" is the normal result for most pairs. Compare the value explicitly (result["comparable"] == "yes"); a truthiness test is true for all three. reasons (a list) always explains the answer.

    • none of the above: every registered cross-dataset comparison pair for one country (e.g. "median sale price vs new dwelling completions per 1,000 residents"). A small, hand-curated set, not an arbitrary-pair engine.

  • explain_metric(stat_key, country="ireland") — definition, methodology and standing caveats for one stat, never a current figure. Use this when the question is about what a metric means or how it's measured, not about one area's value.

  • get_scene(scene_id="ireland-builds", purpose="analytical", vintage=None, country="ireland") — the data to draw one chart or short clip of a citable figure (rows, a table twin, alt text, the licence block, scene_hash), nothing rendered. Two scenes exist: "ireland-builds" and "county-in-motion" (one county against the county median, one row per year; pass county="county:cork" and terms="real" or "nominal"). A promotional use of a source whose licence forbids advertising is refused.

  • notable_changes(limit=8, stat_key=None, geography_id=None, country="ireland") — the statistical movements StatsMapped flagged as notable, newest first (limit 1 to 50), optionally narrowed to one stat or one area. They are movements, not verdicts on what they mean.

Citing an answer. A single-figure answer (query_data with both arguments, compare with pair_key, explain_metric) carries attribution: the publisher's own required wording when the publisher states one (for example "Source: Office for National Statistics. Contains public sector information licensed under the Open Government Licence v3.0."), otherwise StatsMapped's note. StatsMapped's note is always in attribution_note. Quote attribution where you show the figure; publisher, license and licence_class sit beside it (on each axis, for a comparison). A list of many datasets (query_data with area_id alone) has more than one publisher, so its top-level attribution is StatsMapped's note, and each entry carries its own publisher's attribution when that publisher states one. notable_changes carries only attribution_note.

Why stdio, not a hosted server, by default

StatsMapped runs on a single free-tier instance. A remote MCP endpoint hosted there would let an agent's own multi-area query pattern (calling the same tool once per area, in a loop) reproduce exactly the load pattern that has already caused timeouts on that instance under a large geography fan-out. Running over stdio means every call goes through your own network connection to the same public HTTPS API this package's tools call directly, with no shared bottleneck -- each user's own machine makes the HTTP calls, so N users' traffic is naturally spread across N source IPs, not funnelled through one.

server.py also supports a real hosted streamable-http mode (MCP_TRANSPORT=streamable-http) for a deployment that accepts that tradeoff -- StatsMapped's public API is itself rate-limited per source IP (600 requests/hour), but a hosted MCP endpoint proxies every remote user's calls through ONE shared egress IP, so all remote users of a hosted endpoint would share that one bucket rather than each getting their own. A StatsMapped-hosted endpoint is live at https://mcp.statsmapped.com/mcp (Streamable HTTP) -- confirmed responding correctly, no separate install needed for a client that speaks Streamable HTTP directly. The bare host (https://mcp.statsmapped.com, no path) redirects to the same endpoint as a courtesy.

What the client reports, and how to turn it off

After each tool call the client sends one small usage event to StatsMapped. It contains:

  • the tool name, whether the call succeeded, how it ended (answered, empty, error or unsupported) and its latency;

  • identifier-shaped arguments from a closed list, such as stat_key or area_id, and never free text;

  • a random install id kept in ~/.statsmapped-mcp/install_id.

To send nothing, set either of these in the server's environment (for example in the env block of your MCP client config):

  • STATSMAPPED_NO_LOG=1

  • DO_NOT_TRACK=1 (the cross-tool convention)

With either set, no event is sent and no install id is written.

Development

cd mcp-server
pip install -e .
python tests/test_client.py

The test suite runs against the real live API (https://statsmapped.com by default, or STATSMAPPED_MCP_BASE_URL if set) — read-only GETs only, nothing here writes any data or needs a key.

Licence

MIT for this package. The underlying data keeps each publisher's own licence — see statsmapped.com/ireland/sources for Ireland's own publisher/licence detail before reusing any figure outside of querying it through an agent (a UK equivalent page doesn't exist yet — check each UK tool response's own caveats/sources fields in the meantime).

Available Tools

6 tools
compareAInspect

Use when the question is how areas rank or compare on a stat, or whether two stats can be compared fairly. For one area's own figures use query_data.

Four modes, depending on which arguments are given -- consolidates what were four separate tools (rank_areas, list_comparisons, get_comparison, check_comparability) behind one, since they are all really "how does this stat compare" at different scopes. Exactly one mode's arguments should be given; mixing arguments from different modes (e.g. both stat_key and pair_key, or only one of stat_key_a/stat_key_b) raises an error rather than silently guessing which mode was meant.

  1. stat_key alone (no pair_key, no stat_key_a/stat_key_b): ranks every area at one geography level by its latest figure for that stat, for one country -- e.g. "which counties have the highest median sale price" (country="ireland"). stat_key comes from query_data's dataset-listing mode, for the SAME country. level omitted uses this ranking's own default level; pass one of that dataset's own compatible_levels for a different one -- a level this ranking doesn't have registered returns an empty list rather than an error. Where the underlying stat has no honest per-area denominator (crime, homelessness, live_register and similar -- StatsMapped's own RANKING_NO_DENOMINATOR_STATS), each row's rate_per_1000 is the real figure to rank/compare by, not latest_value, which is a raw count dominated by area population size. Always carry forward every entry in caveats when using a row in an answer.

  2. pair_key alone: full detail for one registered comparison pair -- each axis's label, unit and publisher, the correlation stats (r, rho, and a leave-one-out sensitivity range naming the single most influential area), and caveats. pair_key comes from mode 4's own response, for the SAME country.

  3. Both stat_key_a and stat_key_b given: does StatsMapped have a registered, hand-vetted comparison between these two stats? Registry- backed only -- never computes a fresh correlation for an arbitrary pair. Both stat_keys come from query_data's dataset-listing mode, for the SAME country. verdict is one of "SUPPORT" (a real, hand-vetted registered pair with no open caveats -- may be treated as a confirmed relationship), "QUALIFY" (hand-vetted, but the evidence carries real caveats -- e.g. no robustness check for outliers, or an unverified geography-level join; read uncertainty and reasons before presenting it as confirmed), "REJECT" (a real structural impossibility or a human-vetted "no" -- the two stats share no geography level at all, or a reviewer rejected this exact pairing), or "INSUFFICIENT" (not registered, not ruled out either -- StatsMapped genuinely hasn't vetted this pair; never treat this as "probably comparable"). uncertainty names 4 separate dimensions (data_quality, comparability, statistical_strength, causal_strength) -- causal_strength is always "not_established", since no comparison here implies causation regardless of verdict. comparable (DEPRECATED, kept only for callers that haven't migrated) collapses verdict to the old 3-way yes/no/unknown -- "yes" for both SUPPORT and QUALIFY (both mean "hand-vetted", the old comparable meaning this field has always carried; the caveats a QUALIFY pair carries live in uncertainty/reasons, not in demoting comparable), "no" for REJECT, "unknown" for INSUFFICIENT. Prefer verdict directly when you need to distinguish a fully-confirmed SUPPORT from a caveated QUALIFY. Read reasons before presenting any answer other than "SUPPORT" as unqualified.

  4. None of the above given: lists every registered cross-dataset comparison pair for one country -- e.g. "median sale price vs new dwelling completions per 1,000 residents". A small, hand-curated set, not an arbitrary-pair engine: pass one of the returned pair_key values to mode 2 for the real correlation and axis detail.

    level is only meaningful together with stat_key (mode 1); giving it without stat_key raises rather than silently dropping it and falling through to mode 4's unrelated pair listing.

Inputs: level, country, pair_key, stat_key, +2 more. Returns: result

explain_metricAInspect

Use when the question is what a metric means or how it is measured; for a figure use query_data.

Definition, methodology and standing caveats for ONE stat ('ireland' or 'united-kingdom') -- never a current figure. Call this when the question is about what a metric MEANS or how it's measured ("how is the claimant count defined", "is this a mean or a median"), not about a specific area's value -- query_data/compare already answer that. stat_key comes from query_data(country=...) for the SAME country.

Inputs: stat_key (required), country. Returns: object

get_sceneAInspect

Use when asked for a chart, still or short clip of a figure you can cite: returns the data to DRAW one scene, nothing rendered.

Two scenes exist. "ireland-builds" is Ireland's homes granted permission, with a commencement notice and completed, by quarter from 2018Q1. "county-in-motion" is one county against the county median, one row per year: pass county (for example county:cork; default county:dublin) and terms ("real" default, or "nominal"); vintage does not apply to it. For ireland-builds the licence DIFFERS BY STAGE (see licence.stages): a stage whose licence is unconfirmed or ShareAlike is withheld (its cells are absences, not zeros) and the licence line names its holder. You get rows, a table twin, alt text, notes, absences (a missing figure is a typed absence, never a zero), the licence block, scene_hash, a receipt and the canonical URL. YOU draw it, and the last frame must match the table. Print the scene_hash and the licence line in the first, middle and last frame, quote only numbers that are in rows, do not loop, and keep the "stages are not a cohort" note. purpose is "analytical" (default) or "promotional": a promotional use of a source whose licence forbids advertising is refused (licence_refused). vintage (ISO date) omitted = the current data; an earlier vintage is not stored and returns unknown_vintage. Example: get_scene(scene_id="ireland-builds").

Inputs: terms, county, country, purpose, +2 more. Returns: object

list_areasAInspect

Use when you need the ids and names of the areas (counties, local authorities, districts) to pass to query_data.

List every geography at one boundary level, for one country ('ireland' or 'united-kingdom'). level defaults to "county" (Ireland's 26 counties); the UK's own primary level is "lad" (local authority districts), not "county". Other levels exist per country (e.g. Ireland's "local_authority", "garda_division") -- see a dataset's own compatible_levels from query_data for which levels a given stat is actually published at. Returns each area's id (used by query_data's area-scoped modes, always paired with the SAME country), name and level. Slim by default; include_parents=True adds each area's parents (the regions it sits in) and Irish-language name.

Inputs: level, country, include_parents. Returns: result

notable_changesAInspect

Use when the question is what changed lately, which figures moved most, or what is new; for one area's full history use query_data. Returns statistical movements databeat flagged as notable, not verdicts on what they mean; limit is 1 to 50 (default 8), and stat_key or geography_id narrows the list.

Ireland and united-kingdom. Cite StatsMapped (https://statsmapped.com) as the source. Source: GET /{country}/api/v1/alerts/notable.

Inputs: limit, country, stat_key, geography_id. Returns: object

query_dataAInspect

Use when you need to find which datasets exist, which exist for one area, or the figures and history for one area and dataset (or a council planning view). For what a metric means use explain_metric; for how areas rank use compare.

Three modes, depending on which of area_id/dataset are given (plus a planning mode, council, described last) -- consolidates what were three separate tools (list_datasets, list_area_datasets, get_dataset_for_area) behind one, since they are all really "how do I get data" at different levels of specificity:

  1. Neither area_id nor dataset: lists every dataset (stat) StatsMapped tracks for one country ('ireland' or 'united-kingdom'), with its key, human label, and which geography levels it can be shown at. Ireland and the UK track genuinely different datasets -- call this first for the right country before assuming a stat_key exists there, to find the right stat_key for compare's ranking mode.

  2. area_id given, dataset omitted: lists every dataset available for that one area (e.g. "county:kerry" for Ireland, "uk:lad:e09000033" for the UK), with its latest figure, year-on-year change, and caveat labels only (not full caveat text -- use mode 3 for the full detail on any one dataset that matters). Pass stat_key (from mode 1) to list only that stat's series for the area: a full listing is tens of KB, one stat is a few hundred bytes. area_id comes from list_areas; country must match whichever country that call used, or this simply 404s ("unknown geography").

  3. Both area_id and dataset given: full detail for one dataset in one area -- the latest figure, a written summary, full caveat text, and (if history_months is set) recent history. dataset is a series_key from mode 2's own response. history_months means actual months of history (0 = everything) -- e.g. 24 returns 2 years of an annual series, not 24 years. country must match area_id's own country. A stat key from mode 1 is also accepted as dataset when the area has exactly one series for it (the reply says resolved_from_stat_key); with several, the error names the series keys to use.

  4. council alone (an Irish council slug, e.g. "cork-city-council"; country "ireland" only; no other argument): that council's planning applications by year received -- count, grant and refusal share of decided applications, median days to a decision -- with source, licence, the last data date, a receipt, plain notes, and typed absences instead of zeros. A council the national planning feed has stopped carrying (for example Cork City, last record 2025-11-04) says status: "stopped_reporting": a low recent figure is a feed gap, not fewer applications. Example: query_data(council="cork-city-council").

    dataset and history_months are only meaningful together with area_id (and, for history_months, dataset too, since it only applies to mode 3); giving either without its real precondition raises rather than silently dropping the argument and dispatching to the wrong mode.

Inputs: area_id, council, country, dataset, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool has a clearly stated purpose and the descriptions explicitly cross-reference each other (e.g. 'for how areas rank use compare', 'for what a metric means use explain_metric'), which strongly aids selection. The main risk is that `compare` and `query_data` are each multi-mode dispatchers whose behavior depends on argument combinations, so an agent must parse long descriptions to pick a mode, but the boundaries between tools themselves remain distinct.

    Naming Consistency4/5

    Most names follow a verb_noun pattern (get_scene, explain_metric, list_areas, query_data), which is predictable and readable. Two deviations — the bare verb `compare` and the noun-phrase `notable_changes` — slightly break the pattern but remain understandable and unambiguous.

    Tool Count5/5

    Six tools is well within the sweet spot and each covers a genuinely distinct capability (questions, areas, comparisons, definitions, changes, scenes). The authors deliberately consolidated previously separate tools into multi-mode tools, keeping the surface lean rather than sprawling.

    Completeness4/5

    The surface covers the core statistical workflow: discovering datasets, listing areas, fetching area figures and history, ranking/comparing, explaining metrics, spotting notable changes, and generating scene data, plus a council planning view. Minor gaps exist — no direct cross-country comparison and no batch multi-area time-series fetch outside ranking mode — but agents can work around these.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform due diligence on Irish properties by querying public datasets for planning applications, sold prices, flood risk, radon risk, and zoning.
      1
      49 npm
      9
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM agents to query the Explore Local Statistics API for local area data like employment rates and demographics.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search, inspect, and retrieve Irish Central Statistics Office PxStat datasets through MCP tools. Supports catalog search, metadata discovery, full-table reads, and filtered JSON-stat queries.
      65 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search, preview, and query Ireland's public-sector open data catalogue, including CSV, Excel, JSON, GeoJSON, and JSON-stat resources. It supports filtering, grouping, counting, summing, and sorting datasets conversationally without manual downloads or cleanup.
      MIT