eurostat-mcp-server

Public Hosted Server: https://eurostat.caseyjhand.com/mcp

Overview

EU statistics from the Eurostat catalogue — economy, demography, trade, health, and NUTS regional data. Search and browse the catalogue by keyword or theme, inspect dataset dimensions, and query a slice or bulk-download a whole dataset from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Two of the eight are listed only when the dataframe canvas is enabled (CANVAS_PROVIDER_TYPE=duckdb).

Resources

Related MCP server: eurostat-mcp

Capability reference

eurostat_search_datasets tool

• 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 match

• Returns code, label, type (dataset/table), period coverage, observation count, and theme breadcrumb per result

• One row per dataset code — Eurostat files some datasets under multiple theme branches; matches are deduplicated so totalMatches and page slots count unique targets

• Cursor pagination: limit (1–100, default 20) sets page size, totalMatches reports the full count, and passing nextCursor back as cursor pages through every match. A cursor is bound to its 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 on each result names the next tool to call

• Catalogue TOC is cached in memory for 12 hours (EUROSTAT_TOC_CACHE_TTL_MS), refreshed on the next call past that age

eurostat_browse_themes tool

• Without theme_code: returns the top-level theme folders (Economy, Population, Transport, etc.)

• With theme_code: returns immediate children — subtheme folders and datasets in that branch

• Each entry carries code, label, type (folder/dataset/table), data period, and observation count where available

• Returns a breadcrumb parentPath from root to the current node, plus a nextStep hint suited to the level

• One branch per folder code — Eurostat files a few folder codes under several branches; a code resolves to the branch listed first in the catalogue (never fewer children than the ones it shadows), and otherPlacements names those so the ambiguity is visible

eurostat_get_dataset_info tool

• Returns all dimensions with their codes, labels, and up to 10 sample values each

• Dimension values reflect the full dataset-available set (including every period for time), not just what appears in populated observations

• Reports overall time range and total observation count, each omitted — not zeroed — when Eurostat does not report it

• For a dimension with more than 10 values, call eurostat_get_dimension_values for the full list

• metadataUrl links to the ESMS metadata page when Eurostat provides one

eurostat_get_dimension_values tool

• Returns the complete dataset-available set of codes and labels for any dimension, from the same content constraint eurostat_get_dataset_info uses

• For geo, NUTS hierarchy filtering via geo_level: aggregate, country (default), nuts1, nuts2, nuts3 — an empty level reports no_results rather than implying the dataset lacks data, and pairing geo_level with any other dimension is rejected

• Verify codes here before eurostat_query_dataset or eurostat_download_dataset — an invalid dimension value returns no data silently from the former and a rejected fault from the latter

eurostat_query_dataset tool

• Dimension filters as {dimension_code: [values]}; a geo filter and geo_level (NUTS: aggregate/country/nuts1/nuts2/nuts3) are mutually exclusive, as are since_period/until_period and last_n_periods; an empty filter array is dropped rather than applied

• preview_limit (1–500, default 50) bounds only the inline prefix of decoded observations — it never changes obsCount, missingObsCount, timeRange, or what gets staged. There is deliberately no cursor or offset; filters and period controls are the only way to shrink the match itself

• Each observation carries dimension code/label pairs, a nullable value, an optional OBS_FLAG status (e.g. p=provisional, e=estimated), and a separate optional CONF_STATUS confStatus marker — usually why a value is null

• truncated is true only when the match exceeds the 5,000-observation staging threshold, independent of preview_limit. With the dataframe canvas enabled, a match above that threshold is staged whole as a SQL table (canvasId / tableName / stagedRowCount) — call eurostat_dataframe_describe before eurostat_dataframe_query; without a canvas those fields are absent and narrowing the query is the only way to reach the rest

• canvas_id reuses an existing canvas so a result can be joined against earlier ones; an oversized unfiltered query is caught by async-response detection and returned as an actionable, non-retryable error instead of timing out

• Fetches a slice — for a whole dataset, eurostat_download_dataset reads the SDMX bulk endpoint instead, at roughly half the bytes

eurostat_download_dataset tool

• TSV bulk body runs 48–63% of the JSON-stat bytes eurostat_query_dataset reads for the same data — measured across four datasets from 1.1M to 12.8M observations

• Filters take the same {dimension_code: [values]} map, applied server-side; the positional key needs every dimension in the dataset's own order, so a filter naming one the dataset lacks is rejected with the real dimension list rather than sent malformed

• No last_n_periods here — only since_period / until_period actually shrink the response, since the TSV layout keeps a column per period regardless of selector

• Byte budget (EUROSTAT_BULK_MAX_BYTES, default 50 MiB) is enforced while streaming — Eurostat sends no Content-Length, so a transfer stopped mid-flight returns its rows with budgetExceeded: true instead of an error

• Failure modes are typed: an async queue ticket (Eurostat's too-costly-to-serve-inline response) is a non-retryable error; XML SOAP faults map to not_found (100), filter_arity (140), and invalid_dimension (150 — also covers an out-of-coverage period range), each with a recovery hint naming the next tool

• With the dataframe canvas enabled, every observation is staged as a SQL table (canvasId / tableName / stagedRowCount), streamed row by row — call eurostat_dataframe_describe before eurostat_dataframe_query. Without a canvas, only preview_limit rows (default 50, max 500) survive the call; rowCount / missingCount / periodRange still describe the whole download

eurostat_dataframe_describe tool

• Lists tables staged on the canvas (from canvas_id, returned by eurostat_query_dataset or eurostat_download_dataset) with row counts, column names, types, and nullability — call before writing SQL, since the two stagers write different dimension columns

• Also reports the canvas's and each table's expiresAt; every call against a canvas slides its lifetime forward (CANVAS_TTL_MS, default 24h)

• Errors canvas_disabled when this deployment runs without a canvas, canvas_not_found when the ID is unknown or expired

eurostat_dataframe_query tool

• Runs a single read-only SELECT against staged tables; statement chaining, non-SELECT verbs, and functions that read files or external data are rejected with a typed error

• eurostat_query_dataset tables carry a code column per dimension plus a _label companion; eurostat_download_dataset tables carry code columns only (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) with matching codes, so tables from either stager join on dimension codes and time

• A confidential cell reads obs_flag = NULL with conf_status = 'C' on either table — JSON-stat folds the two into one string (|C) that eurostat_query_dataset splits before staging

• Results are bounded by CANVAS_DEFAULT_ROW_LIMIT (default 10,000); truncated: true means add a LIMIT, an aggregate, or a narrower WHERE. 64-bit integer results — COUNT(*) included — arrive as strings so values outside the JSON number range survive intact

• The DuckDB binding ships with the server — CANVAS_PROVIDER_TYPE=duckdb is the only switch — except the one-click .mcpb bundle, which strips native bindings to stay portable; use the npm, Docker, or from-source install for SQL analytics

eurostat://dataset/{dataset_code} resource

• Same payload as eurostat_get_dataset_info, addressable as a resource URI for cache-injectable context

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

• NUTS hierarchy geo-level filtering (aggregate / country / nuts1 / nuts2 / nuts3) across eurostat_query_dataset and eurostat_get_dimension_values

• OBS_FLAG (provisional, estimated, etc.) and CONF_STATUS (confidentiality) decoded into separate fields from Eurostat's combined encoding, consistent whether the observation came from JSON-stat or the bulk TSV

• Async-response detection across every data-fetching tool — Eurostat's over-limit HTTP-200 warnings and HTTP-413/SOAP faults are classified into one typed, non-retryable error with filter guidance instead of surfacing as a timeout

• SDMX 2.1 TSV bulk downloads at roughly half the JSON-stat byte cost, with a mid-transfer byte budget

• Optional DuckDB dataframe canvas stages a query match above 5,000 observations, or a whole bulk download, as a queryable SQL table

Agent-friendly output:

• Structured error contracts — every declared failure carries a typed reason and a recovery.hint naming the exact next tool to call, not just an error string

• Next-step hints — eurostat_search_datasets and eurostat_browse_themes responses carry a nextStep field pointing at the right follow-up call

• Omitted-vs-unknown fields — counts and period bounds Eurostat doesn't report (obsCount, timeRange.start/end, lastUpdated) are omitted from the response rather than defaulted to zero or blank

• Truncation and staging notices — a response that exceeds an inline cap carries an enrichment notice naming the exact eurostat_dataframe_describe → eurostat_dataframe_query follow-up

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.4.0 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:

See .env.example for the full list of optional overrides.

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
  bun run lint:mcp  # Validates MCP definitions against spec

Docker

docker build -t eurostat-mcp-server .
docker run --rm -p 3010:3010 eurostat-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/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

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