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

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

4 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.

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.

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).