eurostat-mcp-server
Public Hosted Server: https://eurostat.caseyjhand.com/mcp
Overview
EU statistics from Eurostat: economy, demography, trade, health, and NUTS regional data, including detailed Comext trade and PRODCOM industrial production. Search or browse the catalogue, inspect a dataset's dimensions, then query a slice or bulk-download the whole thing.
Tools
The three eurostat_dataframe_* tools need the dataframe canvas, which is on by default and off with CANVAS_PROVIDER_TYPE=none; eurostat_dataframe_drop also needs EUROSTAT_DATAFRAME_DROP_ENABLED=true.
Tool | Description |
| Search the Eurostat catalogue by keyword — returns codes, descriptions, period coverage, and theme breadcrumbs |
| Navigate the Eurostat theme hierarchy — list root themes or drill into subthemes and datasets |
| Fetch dataset metadata: dimensions with sample values, time range, observation count, and last-update date |
| List all valid codes for one dataset dimension, paged, with a code/label word filter, a code-prefix filter and NUTS hierarchy filtering for |
| Fetch a bounded preview of decoded observations with dimension filters, NUTS geo-level, and time-range controls |
| Download a whole dataset via the SDMX bulk endpoint and stage every row on the dataframe canvas, within a 55 s time budget beside the 50 MiB byte budget; either keeps the rows read |
| List the tables staged on a dataframe canvas, with row counts and column types |
| Run a read-only SQL SELECT across staged tables |
| Remove one staged table from a dataframe canvas, leaving its other tables in place (opt-in) |
Resources
Resource | Description |
| Dataset metadata (dimensions, time range, observation count, last-updated) by URI |
| Statistical comparison gates, identifier provenance, and SQL analysis workflows |
The same metadata is available through eurostat_get_dataset_info for tool-only clients.
Agent skill
eurostat-guide covers finding datasets and codes, choosing period ranges, country and regional comparisons, Comext aggregation, missing-data interpretation, and SQL joins over staged observations. It ships with plugin, npm, Docker, and MCPB installs and is served over MCP at skill://eurostat-guide/SKILL.md; supporting SQL examples are included under the skill's references/ directory.
Related MCP server: eurostat-mcp
Capability reference
eurostat_search_datasets tool
querywords are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code, ignoring spacing beside punctuation (Rev.2findsRev. 2). Matches are ordered by where the words were found: a label containing the query as a phrase beginning at the start of a word, then a label or code containing every word, then a theme breadcrumb only, each group in table-of-contents order. When no dataset holds every word, a query of up to 10 distinct words is searched again with each missing word also matching where it begins a word of the English label of one of the dataset's dimension values (pharmacistfindsPharmacists,med_spec=PHARM).limitis a positive integer (default 20), clamped to 100 with a notice. Page by passingnextCursorback ascursor; cursor calls ignorelimitResults carry
code,label,type(dataset/table), period coverage,obsCount,lastUpdated, andthemePath, withtotalMatchesacross every page. A row found through dimension value labels carriesmatchedValues(dimension,code,label; the code is the filtereurostat_query_datasettakes) and the response carries anotice. Fails asno_match(naming the words whose removal finds matches or, when none does, the words that match no dataset, checking the first 32 distinct words; it also says when dimension value labels were not searched, because their index has not loaded or the query has more than 10 distinct words),invalid_cursor, or a retryableupstream_faultwhen no catalogue is loaded and Eurostat's table of contents is unreachableIf the Comext dataflow list cannot be loaded, results carry
comextListMissingand anotice; a catalogue that could not be refreshed carriescatalogueLoadedAt
eurostat_browse_themes tool
Omit
theme_codefor the top-level theme folders; pass a folder code for its immediate children. Codes resolve exact-first, then case-insensitively. The Comext collections sit underext_go_detail(detailed trade, inext_go) andprom(PRODCOM, inicts)Items carry
code,label,type(folder/dataset/table), andhasChildren; datasets and tables add their period,obsCountandlastUpdated(dd.mm.yyyy, aseurostat_search_datasetsreports it) when Eurostat reports them, with aparentPathbreadcrumb andotherPlacementsfor a folder filed in several branches; fails asnot_foundfor an unknown code,not_a_folderfor a dataset or table code, or a retryableupstream_faultwhen no catalogue is loaded and Eurostat's table of contents is unreachableIf the Comext dataflow list cannot be loaded,
ext_goandictscarrycomextListMissingand anotice; a catalogue that could not be refreshed carriescatalogueLoadedAt
eurostat_get_dataset_info tool
One
dataset_code; returns every dimension withvaluesCountand up to 10sampleValues, plustimeRange,obsCount,lastUpdated, and the ESMSmetadataUrlFails as
not_foundfor an unknown dataset, orupstream_faultwhen Eurostat returns a structure the server cannot read (retryable when the endpoint is down)
eurostat_get_dimension_values tool
dataset_codeplusdimension, resolved exact-first then case-insensitively (TIME_PERIODaliasestime); returned value codes and labels stay unchanged. Forgeo,geo_levelpicks a NUTS level (aggregate,countryby default,nuts1,nuts2,nuts3).filterkeeps values whose code and label contain every word given, ignoring case and accents (palma frankfurtfindsDE_EDDF_ES_LEPA);code_prefixkeeps values whose code starts with the text, ignoring case (geo_levelnuts2withDElists the German NUTS 2 regions). Both apply before paging and are counted inmatchCountlimitdefaults to 25 and clamps to 1,000 with a notice. Pages contain that many values, fewer at the end, withtotalCountfor the full list; a page with more after it carriestruncated,nextCursor(pass back ascursor), and anotice. Continuations retain the effective count and ignore a newlimit; older cursors above 1,000 normalize to 1,000 with disclosure. Fails asnot_found,no_results,conflicting_params,invalid_cursor,upstream_fault(retryable when the endpoint is down), orcanvas_not_foundcanvas_idstages the dimension's whole list on that canvas as acode/labeltable (canvasId/tableName/stagedRowCount), whateverfilter,code_prefixorlimitsay, that labels a download's code columns through a join; it never starts a canvas of its own. Ageotable adds alevelcolumn (NULL for a code with no NUTS level) and, withoutgeo_level, holds every level, aggregates and regions overlapping the countries they contain: filterlevelbefore joining or aggregating. On a dataset that lists no country values (tgs00010is NUTS 2 only), omittinggeo_levelwithcanvas_idstill stages every level it lists over an empty page, and thenoticenames the levels with their rows; without staging the call fails asno_results
eurostat_query_dataset tool
dataset_codeplusfilters({dimension_code: [values]}),geo_level, and eithersince_period/until_period(2020,2020-Q1,2020-01, down toYYYY-WnnandYYYY-Dnnn) orlast_n_periods;preview_limitis a positive integer (default 25), clamped to 500 with a notice;langisEN,FR, orDENo Eurostat code contains
+or.: a filter value holding+is split into separate values, read as OR (["DE+FR"]is["DE", "FR"]), and one holding.stays one value that matches nothing. A valid value with no cell in the selected periods contributes no rows, andemptyValuesnames itstage: truestages the whole match on an available canvas, regardless of size; reusecanvas_idor omit it to create one. Without it, automatic staging starts above 5,000 observations.truncatedstill describes that threshold;tableNameidentifies a staged result. Canvas-disabled deployments disclose an explicit staging request as unavailablelast_n_periodscounts dataset time positions, which can include periods with no populated cells. A notice names gaps across the full match (up to the newest 24, with an omitted count) and advises a larger N (the exact one for a single frequency), or asince_period–until_periodrange ending at the slice's latest period with a cell, only when every such period follows that periodEurostat keeps only periods wholly inside
since_period–until_period, per frequency. A notice names a period a bound falls inside and the bound that includes it. A one-day range goes out astime=<date>, because Eurostat ignores one-day boundsEach observation carries code/label pairs per dimension, a nullable
value,status(OBS_FLAG), andconfStatus(CONF_STATUS);obsCount,missingObsCount,absentCellCount(periods a matched series lacks inside each frequency's span, from its first to its latest period with a cell; they are not observations and are never staged), andtimeRangecover the whole match. A notice names periods outside that span.truncatedis true above 5,000 observations,unmatchedValuesnames filter values that matched nothing, andemptyValuesnames values the dataset has but this match carries no cell for (undergeo_level, every code of that level with none)Fails as
not_found,no_results(naming the unmatched values with their dimension's valid codes, or a value search when it holds more than 25, the periods with no value, why a range selected no period, orgeo_levelas the likely cause when Eurostat's reply says nothing more),invalid_dimension(naming every filter key that is not a dimension, with the dataset's dimensions in key order),invalid_period,conflicting_params, a non-retryableextraction_too_bigfor a query too large to serve, a retryableasync_responsewhile Eurostat prepares a large extraction (repeat the call in a few minutes),retry_deadline_exceededwhen the Statistics API does not complete the query within the request deadline,canvas_not_found, or a retryableupstream_faultwhen the Statistics API is down
eurostat_download_dataset tool
dataset_codeplus the samefiltersmap andsince_period/until_period(nolast_n_periods: the TSV keeps a column per period unless a range drops it);preview_limitis a positive integer (default 25), clamped to 500 with a noticeThe wholly-inside rule and its notice apply here too. A one-day range requests that day and the next, and the later day's column is dropped before anything is counted or staged
Stages one row per non-blank TSV cell. A row with null
obs_valueand no flag, status or text (an unflagged:) is not an observation: it is a period the series lacks, a period of a frequency the series has no observation of (the padding of a mixed-frequency slice), or a period before or after the span in which any downloaded row has an observation, which a notice namesfiltersfollow the query tool's rules, except that atimeortime_periodkey is rejected (the period is set withsince_period/until_period): a value holding+is split into separate values (OR), and one holding.is rejected asinvalid_dimensionbefore any request, since no Eurostat code contains one. A valid value with no observation in the selected periods adds no rows, andemptyValuesnames it (omitted whenbudgetExceededis true)Returns
rowCount(echoed astotalCount),missingCount,absentCellCount(the unflagged rows at periods of a frequency the series carries, inside that frequency's span from its first to its latest period with an observation in any downloaded row),periodRange(bounded by rows carrying a value, flag, status, or text), andbytesReadfor the whole download; fails asnot_found,invalid_dimension(atimeortime_periodfilter key is answered with thesince_period/until_periodto set instead),invalid_period,filter_arity, a retryableasync_queued(Eurostat is still preparing the extraction: repeat the call in a few minutes, or narrow it), a non-retryableextraction_too_big,no_results,upstream_fault(retryable when the SDMX endpoint is down),retry_deadline_exceededwhen the call's time budget ends before the first row arrives or a filtered download's structure read outlasts the request deadline, orcanvas_not_foundTwo budgets bound the transfer: the
EUROSTAT_BULK_MAX_BYTESbudget (default 50 MiB decoded) and a time budget counted from the call's start (55 s by default, under the 60 s MCP SDK client timeout). Either one, reached after rows have streamed, retains the complete rows read as a prefix and returnsbudgetExceeded: true; thenoticenames which budget stopped it. A byte budget too small for a complete header and usable row fails asbyte_budget_exceeded, with the configured limit and narrowing guidance.bytesReadcounts accepted decoded bytes, never more than the byte budget; incomplete trailing rows are discarded.
eurostat_dataframe_describe tool
canvas_idfrom a staging response; lists each table'sname,rowCount, typed columns, andexpiresAt(slidingCANVAS_TTL_MS, default 24h); fails ascanvas_not_foundorcanvas_disabledColumns depend on the staging tool:
eurostat_query_datasetwrites a code and a_labelcolumn per dimension,eurostat_download_datasetcodes only plustime(both share theobs_*andconf_status*measures), andeurostat_get_dimension_valueswritescodeandlabel(pluslevelforgeo)
eurostat_dataframe_query tool
One read-only
SELECTper call; chained statements, other verbs, and functions that read files or external data are rejectedReturns
columns,rows,rowCount, and required booleantruncated. Every row supplied by the canvas is returned intact, up toCANVAS_DEFAULT_ROW_LIMIT(default 10,000). Cells render as lossless JSON, including nesting and quoted strings; 64-bit integers arrive as strings. Fails asmissing_table,canvas_not_found, orcanvas_disabledA cut sets
truncated: trueand adds a notice. Page an unchanged deterministic SELECT with a totalORDER BY(tie-breakers required),LIMITandOFFSET; advance by actualrowCount. Restart an initially unordered result sorted at offset zero. Volatile SQL and changing or expired tables cannot provide stable paging
eurostat_dataframe_drop tool
canvas_idplustable_name, exactly aseurostat_dataframe_describelists it; removes that one table and leaves the canvas and its other tables in place. Listed only whenEUROSTAT_DATAFRAME_DROP_ENABLED=trueis set beside the canvasReturns
canvasId,tableName,dropped, andexpiresAt;droppedisfalse, with anotice, when nothing by that name was staged, so repeating a drop is safe. Fails ascanvas_not_found,identifier_reserved, orcanvas_disabled
eurostat://dataset/{dataset_code} resource
Same payload as
eurostat_get_dataset_info, returned asapplication/json; a failed read carries the samereasonand a recovery hint, andretryableon an outagedataset_codecomes fromeurostat_search_datasetsoreurostat_browse_themes
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Eurostat-specific:
The Statistics API (JSON-stat 2.0) for slices, the SDMX 2.1 TSV bulk endpoint, a more compact format, for whole datasets, and the catalogue TOC cached in memory for 12 hours
The Comext host's
DS-*collections (detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM) through the same tools. Filter every request,freqincluded, since trade flows mix annual and monthly series; aggregates such asTOTAL,EU27_2020, andEXT_EU27_2020double-count when summed with their members. PRODCOM text values arrive invalueText/obs_value_textNUTS geo-level filtering (
aggregate/country/nuts1/nuts2/nuts3), and OBS_FLAG and CONF_STATUS decoded into separate fieldsToo-large-to-serve responses come back as non-retryable
extraction_too_bigerrors that name the dimensions left to filter. An extraction Eurostat is still preparing comes back as a retryableasync_response(query) orasync_queued(download), whose hint offers the repeat in a few minutes beside the same narrowingA query with
stage: true, a match above 5,000 observations, or any bulk download is staged as a SQL table (canvasId/tableName/stagedRowCount) on the DuckDB dataframe canvas, which is on by default. The.mcpbbundle strips the native DuckDB binding and runs withCANVAS_PROVIDER_TYPE=none, so SQL analytics need the npm, Docker, or from-source install
Agent-friendly output:
Typed error contracts: every declared failure carries a
reasonand arecovery.hintnaming the next tool to callNext-step hints:
eurostat_search_datasetsandeurostat_browse_themesreturn anextSteppointing at the follow-up callUnknown stays unknown: counts and period bounds Eurostat doesn't report (
obsCount,timeRange.start/end,lastUpdated) are omitted rather than zeroedEffective-query echo:
appliedFiltersoneurostat_query_datasetandappliedQuery(with the SDMXurl) oneurostat_download_dataset, plus anoticewhen the preview omits rows
Getting started
Connect to the hosted instance:
claude mcp add --transport http eurostat-mcp-server https://eurostat.caseyjhand.com/mcpOr run it locally:
claude mcp add eurostat-mcp-server -- npx -y @cyanheads/eurostat-mcp-serverFor other clients, add this to the MCP config file:
{
"mcpServers": {
"eurostat-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/eurostat-mcp-server"]
}
}
}No API key is required. For Docker or a source build, see Running the server.
Configuration
Variable | Description | Default |
| Eurostat API base URL. |
|
| Comext dissemination host, which serves every |
|
| Total allowance for one request, including retries, backoff and body reads, in ms. |
|
| Total allowance for one dataset's SDMX dataflow structure, including retries, backoff and body reads, in ms. |
|
| Catalogue TOC cache lifetime, in ms. |
|
| Time budget for one |
|
| Byte budget for one bulk download. |
|
| Dataframe canvas backend; |
|
| Sliding lifetime of a staged canvas, in ms. |
|
| Max complete rows one |
|
| Clamp positive integer preview/search/dimension limits to 500/100/1,000 with a notice. |
|
|
|
|
| Transport: |
|
| HTTP server port. |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level ( |
|
| Directory for log files (Node.js only). |
|
| Log each failed tool call's arguments and result, redacted by key name and capped at |
|
| Storage backend: |
|
| Enable OpenTelemetry. |
|
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
git clone https://github.com/cyanheads/eurostat-mcp-server.git
cd eurostat-mcp-server && bun install
cp .env.example .env # optional; every setting has a defaultBuild and run the production version:
# One-time build bun run rebuild # Run the built server bun run start:http # or bun run start:stdioRun checks and tests:
bun run devcheck # Lints, formats, type-checks, and more bun run test # Runs the test suite bun run lint:mcp # Validates MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/eurostat-mcp-server:latestThe image defaults to HTTP transport, stateless session mode, and logs to /var/log/eurostat-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/eurostat-mcp-server:latest. Build locally with docker build -t eurostat-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Directory | Purpose |
|
|
| Tool definitions ( |
| Resource definitions. Dataset metadata resource. |
| Catalogue service — fetches and parses the Eurostat TOC, merges the Comext dataflow list into it, and builds the dimension value index search falls back to (metabase codes, codelist labels), with a TTL-bounded in-memory cache. |
| Statistics API service — SDMX metadata parsing with a per-dataset cache, JSON-stat 2.0 decoding, async-response detection, canvas row source. |
| SDMX 2.1 TSV bulk service — streaming download, byte and time budgets, SOAP fault mapping, canvas row source. |
| OBS_FLAG and CONF_STATUS codelists, the measure column names both stagers write, and the text-value decoder. |
| Which host serves a dataset code: |
| Accessor for the optional DataCanvas and the acquire helper canvas-touching tools share. |
| Lets concurrent callers await one shared download, so one caller's cancellation releases only that caller. |
| Server-specific environment variable parsing and validation with Zod. |
| Published eurostat-guide and SQL reference, served over MCP and included in installation packages. |
| Unit and integration tests, mirroring the |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor logging,ctx.statefor storageRegister new tools and resources in the
createApp()arrays insrc/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Experimental MCP providing read-only population statistics from Eurostat.
Access European statistics: GDP, unemployment, inflation, population data.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes the Eurostat Statistics API, enabling LLMs to discover, explore, and retrieve official EU statistical data through search, dimension inspection, and data retrieval tools.3-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides tools to query Eurostat APIs for European statistics data.11MIT
- AlicenseNot gradedqualityBmaintenanceEnables querying Eurostat statistical data through natural language or direct MCP tools, wrapping the Eurostat API without authentication.146 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables searching and accessing EU open datasets from data.europa.eu, including metadata discovery and dataset retrieval.91 npmMIT