Tools

6 tools for discovering and querying Eurostat statistical datasets, plus 2 more when the optional dataframe canvas is enabled:

eurostat_search_datasets

Search the Eurostat dataset catalogue by keyword.

• Tokenized keyword match — whitespace-separated tokens are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code, so word order and theme-named queries resolve without a verbatim label
• Returns code, label, type (dataset/table), period coverage, observation count, and theme breadcrumb
• One row per dataset code — Eurostat files some datasets under several theme branches; matches are deduplicated so totalMatches and page slots count unique query targets
• Cursor pagination: limit (1–100, default 20) sets the page size, totalMatches reports the full count, and passing the returned nextCursor back as cursor pages through every match over a stable order. Cursors are bound to their originating query and catalogue snapshot — reusing one with a different query, or after the catalogue refreshes, returns invalid_cursor instead of a silently shifted page
• nextStep hint on each result points at the next tool to call
• Catalogue TOC cached in memory for 12 hours (EUROSTAT_TOC_CACHE_TTL_MS), then refreshed on the next call
• Pair with eurostat_browse_themes for structured domain exploration when keywords are unclear

eurostat_browse_themes

Navigate the Eurostat theme tree.

• Without theme_code: returns the top-level themes (Economy and finance, Population, Transport, etc.)
• With theme_code: returns immediate children — subtheme folders and datasets in that branch
• Each entry includes code, label, type (folder/dataset/table), data period, and observation count where available
• Returns a breadcrumb path from root to the current node, plus a nextStep hint suited to the level (drill into folders or inspect a dataset)
• One branch per folder code — Eurostat files a few folder codes under several branches; a code resolves to the first one the catalogue lists, which never has fewer children than the branches it shadows, and otherPlacements names those so the ambiguity is visible
• Use for structured discovery when you know the domain but not the exact dataset code

eurostat_get_dataset_info

Fetch metadata for a Eurostat dataset before querying it.

• Returns all dimensions with their codes, labels, and up to 10 sample values each
• Reports overall time range and total observation count across all periods, each omitted when Eurostat does not report it
• Uses a minimal Statistics API call (most recent period only), plus one bounded follow-up to count the dataset's periods when it has a time dimension. If that follow-up fails, the call still returns everything the first request produced, with the time dimension's value count omitted rather than reported as 1
• For dimensions with more than 10 values, use eurostat_get_dimension_values for the full list
• Provides a link to the ESMS metadata page when available

eurostat_get_dimension_values

List all valid values for a specific dataset dimension.

• Retrieves the complete set of valid codes and labels for any dimension (unit, na_item, geo, etc.)
• For the geo dimension, supports NUTS hierarchy filtering: aggregate (EU/EA totals), country (41 states), nuts1 (127 major regions), nuts2 (309 basic regions), nuts3 (1,343 small regions). Pairing it with any other dimension is rejected rather than ignored
• Prevents silent no-data returns — invalid dimension values in eurostat_query_dataset return nothing without error; verify codes here first

eurostat_query_dataset

Fetch statistical data from a Eurostat dataset.

• Accepts dimension filters as a map of {dimension_code: [value1, value2, ...]}
• NUTS geo-level filter (aggregate, country, nuts1, nuts2, nuts3) — mutually exclusive with a non-empty geo entry in filters; an empty array is treated as no filter and dropped
• Time range via since_period/until_period (e.g., "2020", "2023-Q1") or last_n_periods for the N most recent
• Returns decoded observations with dimension codes and labels, numeric values, an OBS_FLAG status (p = provisional, e = estimated, etc.) and a separate CONF_STATUS confidentiality marker (C = confidential, usually the reason a value is null)
• Reports total observation count, missing value count, and the effective time range of the result, each period bound omitted when neither the observations nor Eurostat report it
• Inline rows are capped at 5,000, applied while decoding so a broad query never builds the rest; obsCount, missingObsCount and timeRange still describe the whole match, and truncated flags when the cap bit. Filter the query to shrink what Eurostat sends — the cap bounds the decode, not the transfer
• With the dataframe canvas enabled, a match past the cap is also staged whole as a SQL table and the response returns canvasId / tableName / stagedRowCount; the rows are streamed into the table one at a time from the response body already in memory, so nothing extra is fetched and the match is never materialized as an array. Without a canvas those fields are absent and narrowing the query is the way to the rest
• Pass canvas_id from an earlier response to stage several results side by side and join across them
• Async-response detection — large unfiltered queries return an actionable, non-retryable error with filter guidance rather than silently timing out
• Fetches a slice. When the target is a whole dataset, eurostat_download_dataset reads the SDMX bulk endpoint instead, at roughly half the bytes

eurostat_download_dataset

Download a whole dataset through the SDMX 2.1 TSV bulk endpoint (/sdmx/2.1/data/{dataset}?format=TSV).

• The TSV wire format runs 48–63% of the JSON-stat body eurostat_query_dataset reads for the same data, because the wide layout writes each dimension key once per row instead of once per observation. Measured across four datasets from 1.1M to 12.8M observations
• Filters take the same {dimension_code: [value, ...]} map as eurostat_query_dataset and are applied by Eurostat before the body is sent. They become a positional key on the request path, which must carry one position per dimension — the server builds it from the dataset's own dimension order, so a filter naming a dimension the dataset does not have is rejected with the real list rather than sent as a malformed key
• Narrow periods with since_period / until_period. There is deliberately no "last N periods": the TSV layout keeps a column for every period whichever selector is used, and lastNObservations merely blanks the unselected cells — measured at ~3× the equivalent JSON-stat body. startPeriod removes the columns
• Byte budget enforced while streaming. Eurostat sends the body chunked with no Content-Length, so the limit is applied as bytes arrive and the transfer is aborted the moment it is spent — not measured after the fact. A truncated download returns its rows with budgetExceeded: true rather than an error, so the work already paid for is not discarded. EUROSTAT_BULK_MAX_BYTES sets the ceiling
• gzip is sniffed off the stream, not read from headers. Eurostat compresses large bodies with no Content-Encoding header; the only header-level tell is a .tsv.gz filename on Content-Disposition, and the switch does not track dataset size, so the magic bytes are what decide
• The asynchronous queue envelope is detected explicitly. When an extraction is too costly to serve inline Eurostat answers HTTP 200 with a SOAP syncResponse ticket instead of data; read as TSV that yields a header row of XML and no observations, so it is classified up front as a non-retryable error naming what to narrow
• Errors arrive as XML SOAP faults, not JSON: faultcode 100 → not_found, 140 → filter_arity, 150 → invalid_dimension (which also covers a period range outside the dataset's coverage). Each maps to a typed reason with a recovery hint naming the tool to call next
• With the dataframe canvas enabled, every observation is staged as a SQL table and the response returns canvasId / tableName / stagedRowCount; rows stream into the table one at a time, so a multi-million-row download never materializes as an array. Only preview_limit rows (default 50, max 500) come back inline, and they are the leading rows of the staged table
• Without a canvas the download still runs so rowCount, missingCount and periodRange describe it, but only the preview is retained — the response says so plainly instead of implying the rest is reachable

eurostat_dataframe_describe / eurostat_dataframe_query

SQL over the results eurostat_query_dataset and eurostat_download_dataset stage. Listed only when the dataframe canvas is enabled (CANVAS_PROVIDER_TYPE=duckdb); the server is fully functional without it, and clients never see tools they cannot call.

• eurostat_dataframe_describe lists the staged tables with row counts and column names and types — call it before writing SQL
• eurostat_dataframe_query runs a single read-only SELECT. Statement chaining, non-SELECT verbs, and functions that read files or external data are rejected with a typed error
• Staged columns are flat, and the two stagers write different dimension columns — call eurostat_dataframe_describe rather than assuming. eurostat_query_dataset gives each dimension a code column named after the dimension (geo) plus a label companion (geo_label); eurostat_download_dataset gives code columns only, since the bulk endpoint carries no labels, plus a time column. Both write the same five measure columns: obs_value, obs_flag, obs_flag_label, conf_status, conf_status_label
• Tables from the two stagers join on their dimension code columns and time — same names, same VARCHAR type, obs_value DOUBLE on both — and their measure columns carry the same codes for the same observation. JSON-stat has no CONF_STATUS field and folds the marker into the observation status as |C; eurostat_query_dataset splits it back out before staging, so a confidential cell reads obs_flag = NULL with conf_status = 'C' on either table
• The DuckDB binding ships with the server, so CANVAS_PROVIDER_TYPE=duckdb is the only switch. The exception is the one-click .mcpb bundle, which strips platform-specific native bindings to stay portable — a bundle install cannot run the canvas, so reach for the npm, Docker, or from-source install for SQL analytics

Resource

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Eurostat-specific:

• TTL-bounded in-memory cache for the TOC file — reused across all search and browse calls, refreshed on the first call past its 12-hour lifetime, with the last loaded copy served if a refresh fails
• JSON-stat 2.0 stride-based decoder for the Statistics API response format
• Async-response detection — Eurostat returns a warning object rather than an error for over-limit queries; the server intercepts it and returns an actionable error with filter guidance
• NUTS hierarchy geo-level filtering across query and dimension-value tools
• Status decoding against both published codelists — the OBS_FLAG observation flag (provisional, estimated, definition differs) and the CONF_STATUS confidentiality marker, each in its own field. JSON-stat folds the two into one string and SDMX TSV into one cell; both are split on their separator, so a given observation reads the same whichever endpoint served it
• Optional DuckDB dataframe canvas — a query matching more than the inline cap is streamed row by row into a SQL table, reaching the observations the cap drops without a second request to Eurostat
• SDMX 2.1 TSV bulk downloads with streaming gzip detection, a mid-transfer byte budget, wide-to-long expansion, and SOAP fault classification — the whole-dataset counterpart to the per-query path

Agent-friendly output:

• Discovery workflow: eurostat_search_datasets / eurostat_browse_themes → eurostat_get_dataset_info → eurostat_get_dimension_values → eurostat_query_dataset for a slice, or eurostat_download_dataset for the whole dataset
• Invalid dimension codes in query filters silently return no data from Eurostat — the eurostat_get_dimension_values tool prevents this by letting agents verify codes first
• Structured error contracts with typed reasons and recovery hints on all tools

Getting started

Public Hosted Instance

A public instance is available at https://eurostat.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "eurostat-mcp-server": {
      "type": "streamable-http",
      "url": "https://eurostat.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "eurostat-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/eurostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "eurostat-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/eurostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "eurostat-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/eurostat-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.2 or higher. No API key required — Eurostat's dissemination API is public.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/eurostat-mcp-server.git

2. Navigate into the directory:

cd eurostat-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Running the server

Local development

• 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
  

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

Contributing

Issues and pull requests 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.