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.

Resources

The same metadata is available through eurostat_get_dataset_info for tool-only clients.

Agent skill

eurostat-guide covers 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.

Capability reference

eurostat_search_datasets _tool

• query words are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code, ignoring spacing beside punctuation (Rev.2 finds Rev. 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 (pharmacist finds Pharmacists, med_spec=PHARM). limit is a positive integer (default 20), clamped to 100 with a notice. Page by passing nextCursor back as cursor; cursor calls ignore limit
• Results carry code, label, type (dataset / table), period coverage, obsCount, lastUpdated, and themePath, with totalMatches across every page. A row found through dimension value labels carries matchedValues (dimension, code, label; the code is the filter eurostat_query_dataset takes) and the response carries a notice. Fails as no_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 retryable upstream_fault when no catalogue is loaded and Eurostat's table of contents is unreachable
• If the Comext dataflow list cannot be loaded, results carry comextListMissing and a notice; a catalogue that could not be refreshed carries catalogueLoadedAt

eurostat_browse_themes _tool

• Omit theme_code for the top-level theme folders; pass a folder code for its immediate children. Codes resolve exact-first, then case-insensitively. The Comext collections sit under ext_go_detail (detailed trade, in ext_go) and prom (PRODCOM, in icts)
• Items carry code, label, type (folder / dataset / table), and hasChildren, with a parentPath breadcrumb and otherPlacements for a folder filed in several branches; fails as not_found for an unknown code, not_a_folder for a dataset or table code, or a retryable upstream_fault when no catalogue is loaded and Eurostat's table of contents is unreachable
• If the Comext dataflow list cannot be loaded, ext_go and icts carry comextListMissing and a notice; a catalogue that could not be refreshed carries catalogueLoadedAt

eurostat_get_dataset_info _tool

• One dataset_code; returns every dimension with valuesCount and up to 10 sampleValues, plus timeRange, obsCount, lastUpdated, and the ESMS metadataUrl
• Fails as not_found for an unknown dataset, or upstream_fault when Eurostat returns a structure the server cannot read (retryable when the endpoint is down)

eurostat_get_dimension_values _tool

• dataset_code plus dimension, resolved exact-first then case-insensitively (TIME_PERIOD aliases time); returned value codes and labels stay unchanged. For geo, geo_level picks a NUTS level (aggregate, country by default, nuts1, nuts2, nuts3). filter keeps values whose code and label contain every word given, ignoring case and accents (palma frankfurt finds DE_EDDF_ES_LEPA); code_prefix keeps values whose code starts with the text, ignoring case (geo_level nuts2 with DE lists the German NUTS 2 regions). Both apply before paging and are counted in matchCount
• limit defaults to 25 and clamps to 1,000 with a notice. Pages contain that many values, fewer at the end, with totalCount for the full list; a page with more after it carries truncated, nextCursor (pass back as cursor), and a notice. Continuations retain the effective count and ignore a new limit; older cursors above 1,000 normalize to 1,000 with disclosure. Fails as not_found, no_results, conflicting_params, invalid_cursor, upstream_fault (retryable when the endpoint is down), or canvas_not_found
• canvas_id stages the dimension's whole list on that canvas as a code / label table (canvasId / tableName / stagedRowCount), whatever filter, code_prefix or limit say, that labels a download's code columns through a join; it never starts a canvas of its own. A geo table adds a level column (NULL for a code with no NUTS level) and, without geo_level, holds every level, aggregates and regions overlapping the countries they contain: filter level before joining or aggregating

eurostat_query_dataset _tool

• dataset_code plus filters ({dimension_code: [values]}), geo_level, and either since_period / until_period (2020, 2020-Q1, 2020-01, down to YYYY-Wnn and YYYY-Dnnn) or last_n_periods; preview_limit is a positive integer (default 25), clamped to 500 with a notice; lang is EN, FR, or DE
• No 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, and emptyValues names it
• stage: true stages the whole match on an available canvas, regardless of size; reuse canvas_id or omit it to create one. Without it, automatic staging starts above 5,000 observations. truncated still describes that threshold; tableName identifies a staged result. Canvas-disabled deployments disclose an explicit staging request as unavailable
• last_n_periods counts 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 a since_period–until_period range ending at the slice's latest period with a cell, only when every such period follows that period
• Eurostat 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 as time=<date>, because Eurostat ignores one-day bounds
• Each observation carries code/label pairs per dimension, a nullable value, status (OBS_FLAG), and confStatus (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), and timeRange cover the whole match. A notice names periods outside that span. truncated is true above 5,000 observations, unmatchedValues names filter values that matched nothing, and emptyValues names values the dataset has but this match carries no cell for (under geo_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, or geo_level as 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-retryable async_response for a query too large to serve, retry_deadline_exceeded when the Statistics API does not complete the query within the request deadline, canvas_not_found, or a retryable upstream_fault when the Statistics API is down

eurostat_download_dataset _tool

• dataset_code plus the same filters map and since_period / until_period (no last_n_periods: the TSV keeps a column per period unless a range drops it); preview_limit is a positive integer (default 25), clamped to 500 with a notice
• The 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_value and 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 names
• filters follow the query tool's rules: a value holding + is split into separate values (OR), and one holding . is rejected as invalid_dimension before any request, since no Eurostat code contains one. A valid value with no observation in the selected periods adds no rows, and emptyValues names it (omitted when budgetExceeded is true)
• Returns rowCount (echoed as totalCount), 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), and bytesRead for the whole download; fails as not_found, invalid_dimension, invalid_period, filter_arity, a non-retryable async_queued or extraction_too_big, no_results, upstream_fault (retryable when the SDMX endpoint is down), retry_deadline_exceeded when the transfer outlasts EUROSTAT_BULK_TIMEOUT_MS or a filtered download's structure read outlasts the request deadline, or canvas_not_found
• The EUROSTAT_BULK_MAX_BYTES budget (default 50 MiB decoded) retains complete rows within the permitted prefix and returns budgetExceeded: true. A budget too small for a complete header and usable row fails as byte_budget_exceeded, with the configured limit and narrowing guidance. bytesRead counts accepted decoded bytes, never more than the budget; incomplete trailing rows are discarded.

eurostat_dataframe_describe _tool

• canvas_id from a staging response; lists each table's name, rowCount, typed columns, and expiresAt (sliding CANVAS_TTL_MS, default 24h); fails as canvas_not_found or canvas_disabled
• Columns depend on the staging tool: eurostat_query_dataset writes a code and a _label column per dimension, eurostat_download_dataset codes only plus time (both share the obs_* and conf_status* measures), and eurostat_get_dimension_values writes code and label (plus level for geo)

eurostat_dataframe_query _tool

• One read-only SELECT per call; chained statements, other verbs, and functions that read files or external data are rejected
• Returns columns, rows, rowCount, and required boolean truncated. Every row supplied by the canvas is returned intact, up to CANVAS_DEFAULT_ROW_LIMIT (default 10,000). Cells render as lossless JSON, including nesting and quoted strings; 64-bit integers arrive as strings. Fails as missing_table, canvas_not_found, or canvas_disabled
• A cut sets truncated: true and adds a notice. Page an unchanged deterministic SELECT with a total ORDER BY (tie-breakers required), LIMIT and OFFSET; advance by actual rowCount. 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_id plus table_name, exactly as eurostat_dataframe_describe lists it; removes that one table and leaves the canvas and its other tables in place. Listed only when EUROSTAT_DATAFRAME_DROP_ENABLED=true is set beside the canvas
• Returns canvasId, tableName, dropped, and expiresAt; dropped is false, with a notice, when nothing by that name was staged, so repeating a drop is safe. Fails as canvas_not_found, identifier_reserved, or canvas_disabled

eurostat://dataset/{dataset_code} _resource

• Same payload as eurostat_get_dataset_info, returned as application/json; a failed read carries the same reason and a recovery hint, and retryable on an outage
• dataset_code comes from eurostat_search_datasets or eurostat_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 for whole datasets at roughly half the bytes, 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, freq included, since trade flows mix annual and monthly series; aggregates such as TOTAL, EU27_2020, and EXT_EU27_2020 double-count when summed with their members. PRODCOM text values arrive in valueText / obs_value_text
• NUTS geo-level filtering (aggregate / country / nuts1 / nuts2 / nuts3), and OBS_FLAG and CONF_STATUS decoded into separate fields
• Too-large-to-serve responses come back as non-retryable async_response, extraction_too_big, or async_queued errors that name the dimensions left to filter
• A 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 .mcpb bundle strips the native DuckDB binding and runs with CANVAS_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 reason and a recovery.hint naming the next tool to call
• Next-step hints: eurostat_search_datasets and eurostat_browse_themes return a nextStep pointing at the follow-up call
• Unknown stays unknown: counts and period bounds Eurostat doesn't report (obsCount, timeRange.start / end, lastUpdated) are omitted rather than zeroed
• Effective-query echo: appliedFilters on eurostat_query_dataset and appliedQuery (with the SDMX url) on eurostat_download_dataset, plus a notice when the preview omits rows

Getting started

Connect to the hosted instance:

claude mcp add --transport http eurostat-mcp-server https://eurostat.caseyjhand.com/mcp

Or run it locally:

claude mcp add eurostat-mcp-server -- npx -y @cyanheads/eurostat-mcp-server

For 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

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 default

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run 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:latest

The 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

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays in src/index.ts
• Wrap 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 test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.