StatsMapped MCP server exposes Irish and UK public statistics as MCP tools for AI agents.
Query data: list all datasets, or get latest figures/summaries/history for a specific area or dataset using query_data.
List geographies: get area IDs and names by boundary level using list_areas.
Compare: rank areas by a stat, list registered comparison pairs, get pair details, or check whether two stats are comparable using compare.
Explain metrics: get definition, methodology, and standing caveats for a stat using explain_metric.
Supports both Ireland and the United Kingdom via a country argument, and requires no API key.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@StatsMapped: Irish statistics (CSO, county & council data) Rank Irish counties by median house price"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Published on PyPI as statsmapped-mcp (confirmed live: https://pypi.org/project/statsmapped-mcp/):
pip install statsmapped-mcpRelated MCP server: UK ONS MCP Server
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"
}
}
}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.
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.
cd mcp-server
pip install -e .
python tests/test_client.pyThe 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.
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).
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.
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.
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.
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. comparable is one of "yes"
(a real, hand-vetted registered pair -- only this case may be treated
as a confirmed relationship), "no" (a real structural impossibility,
the two stats share no geography level at all), or "unknown" (not
registered, not ruled out either -- StatsMapped genuinely hasn't
vetted this pair; never treat this as "probably comparable"). Read
reasons before deciding how to present any answer other than "yes".
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.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| country | No | ireland | |
| pair_key | No | ||
| stat_key | No | ||
| stat_key_a | No | ||
| stat_key_b | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so extensively. It discloses error-vs-empty-list behavior, the meaning of `comparable` values including how to treat `unknown`, the registry-backed limitation that never computes fresh correlations, the `rate_per_1000` vs `latest_value` distinction, and the requirement to carry forward caveats. This is far beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but exceptionally well-structured, using numbered modes and front-loading the unifying concept before detailing each mode. Every sentence provides operational guidance, and the clear mode-by-mode organization makes the length justified by the tool's genuine complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's decision space: four modes, parameter combinations, error conditions, output semantics (correlation stats, comparability values, caveats, rate/raw distinction), and data provenance. With an output schema present, the description is complete enough that an agent can invoke the tool correctly without needing to infer anything about behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It explains each parameter's role and valid combinations: `stat_key` alone for mode 1, `pair_key` alone for mode 2, both `stat_key_a`/`stat_key_b` for mode 3, and none for mode 4, plus the conditional meaning of `level`. It also gives source constraints for parameter values, making every parameter semantically meaningful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's core purpose immediately: 'how does this stat compare' at different scopes, and explicitly maps the four modes to the four tools it consolidates. Each mode is described with a specific verb and resource (rank areas, get pair detail, check comparability, list pairs), making it easy to disambiguate from siblings and between modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance for each mode, clarifies that exactly one mode's arguments should be given, and explains error behavior for mixing modes or providing `level` without `stat_key`. It also names where valid keys come from (`query_data`'s dataset-listing mode) and reinforces the country consistency requirement, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland | |
| stat_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly discloses that the tool never returns a current figure and that it returns definition, methodology, and caveats. It does not explicitly state read-only behavior, but the described purpose makes side effects highly unlikely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, with each sentence serving a purpose: what the tool returns, when to use it, and where stat_key originates. It is slightly over-worded with parenthetical examples, but it remains well organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and the description covers purpose, usage boundaries, and stat_key provenance, it is mostly complete. The main gap is the unclear relationship between the country and stat_key parameters, which could confuse an agent despite the helpful examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains where stat_key comes from (query_data for the same country) and hints at country values via 'ireland'/'united-kingdom', but it does not clearly define the country parameter or enumerate allowed values. The 'ONE stat' phrasing combined with country examples is somewhat ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool provides definition, methodology, and standing caveats for one statistic, and explicitly contrasts this with current-value lookups handled by query_data/compare. This makes the resource, scope, and non-current-value nature clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance (questions about what a metric means or how it is measured), explicit when-not-to-use guidance (specific area values), and names the sibling tools query_data/compare as the alternatives. It also tells the agent where stat_key comes from, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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) and name.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | county | |
| country | No | ireland |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains that the tool lists geographies, returns id and name, and always pairs id with the same country. It does not explicitly state the operation is read-only, but the verb 'List' and the absence of any mutation language strongly imply it, and the description adds useful context about ID usage with query_data. A score of 4 reflects good transparency for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. The description leads with the core purpose and then efficiently covers defaults, country-specific differences, examples, and a pointer to query_data. No fluff or repetition; it is dense but well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 optional parameters, output schema exists), and the description covers all needed decision points: default levels per country, available levels, how the output IDs connect to query_data, and the requirement to pair ID with the same country. There is nothing an agent needs to know to invoke the tool correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate for parameter documentation. It explains both parameters in depth: `level` is described with defaults, country-specific primary levels, and examples of other possible values, and `country` is explicitly limited to 'ireland' or 'united-kingdom'. It also tells users where to find valid levels per dataset (compatible_levels from query_data), going far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List every geography at one boundary level, for one country', which states a specific verb and resource. It further distinguishes itself from siblings by explaining that it returns area IDs used by query_data's area-scoped modes and directs users to query_data for compatible levels, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool—when you need to enumerate geographies or obtain IDs for query_data—and references query_data for dataset-specific levels. While it does not explicitly say 'use X instead' or provide when-not-to-use exclusions, the relationship to query_data and the level guidance provide clear context for choosing it. It earns a 4 rather than 5 because the when-not guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Three modes, depending on which of area_id/dataset are given --
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:
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.
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). area_id comes from list_areas; country
must match whichever country that call used, or this simply 404s
("unknown geography").
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| area_id | No | ||
| country | No | ireland | |
| dataset | No | ||
| history_months | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the three modes, what each returns (including caveat labels vs. full caveat text), error behavior ('404s' for country mismatch, 'raises' when preconditions are violated), and the nuanced meaning of history_months (0 = everything, actual months not years). This is thorough and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is efficiently structured with numbered modes and a clear hierarchy. It front-loads the main concept (three modes) and then details each mode. Every sentence adds necessary information; there is no fluff or repetition. The formatting (numbered list, bullet-style details) makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an agent to call correctly: it covers all three modes, parameter dependencies, error conditions, and the meaning of history_months. The output schema exists, so return values are defined elsewhere. No essential behavioral or contextual information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does: every parameter (area_id, dataset, history_months, country) is explained in the context of each mode, with examples (e.g., 'county:kerry', 'uk:lad:e09000033') and constraints (dataset only meaningful with area_id, history_months only in mode 3). This far exceeds what the raw schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Three modes' and explicitly names what the tool does: consolidates three former tools into one for querying data at different specificity levels. It distinguishes from siblings by referencing list_areas (source of area_id) and compare (which uses stat_key from mode 1). The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance per mode: 'call this first' for mode 1, mode 2 for a specific area, mode 3 for full detail. It also states prerequisites (area_id from list_areas, country must match) and warns that mismatches cause errors. Alternatives like compare and explain_metric are implicitly referenced, but the routing among the three modes is crystal clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0check_comparabilitycompareget_comparisonget_dataset_for_arealist_area_datasetslist_comparisonslist_datasetsquery_datarank_areasv0.1.0check_comparabilityexplain_metricget_comparisonget_dataset_for_arealist_area_datasetslist_areaslist_comparisonslist_datasetsrank_areasScored across 4 tools
The four tools have clearly distinct jobs: retrieving data (query_data), listing geographies (list_areas), comparing/ranking statistics (compare), and explaining metric definitions (explain_metric). Despite compound modes inside query_data and compare, the descriptions enforce mutually exclusive argument patterns that prevent ambiguity.
Three tools follow a clear verb_noun snake_case pattern (query_data, list_areas, explain_metric), and 'compare' is also a verb in the same style but lacks an explicit noun object. Overall the naming is predictable and readable, with only this minor inconsistency.
Four tools is well within the ideal range for this server's read-only statistics domain. Each tool represents a distinct capability and intentionally consolidates multiple related modes, so no tool feels redundant or missing.
The server covers the full query workflow: discover datasets, list geographies, get area/dataset detail with history, rank/compare areas, check registered pair comparisons, and explain metric methodology. The documented limitations around registered comparisons and country matching are described as deliberate constraints, not gaps.
Query UK Parliament, elections, crime stats, ONS census data, and national archives
UK property research tools - crime stats, schools, demographics, valuations for AI.
UK area & property intelligence for AI agents: reports, EPC, comparables, with source provenance.
Official UK, US and Australia public datasets as filtered CSV, REST API and MCP for AI agents.
