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, then query a slice or bulk-download a whole dataset. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

The catalogue spans two Eurostat hosts. Most datasets come from the dissemination API; the DS-* collections — detailed trade by CN8, HS, SITC, BEC and CPA (Comext), and PRODCOM industrial production — come from the Comext dissemination host. Every tool routes a DS-* code there by its prefix, in any case, so the same calls work on both.

Tools

Three of the nine are listed only when the dataframe canvas is enabled (CANVAS_PROVIDER_TYPE=duckdb), and 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.

Related MCP server: eurostat-mcp

Capability reference

eurostat_search_datasets tool

• query tokens are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code; limit 1–100 (default 20), paged by passing nextCursor back as cursor

• Results carry code, label, type (dataset / table), period coverage, obsCount, lastUpdated, and themePath, with totalMatches across every page; fails as no_match or invalid_cursor

eurostat_browse_themes tool

• Omit theme_code for the top-level theme folders; pass a folder code for its immediate children. 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 code filed in several branches; fails as not_found for an unknown code, not_a_folder for a dataset or table code

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 or content constraint the server cannot read

eurostat_get_dimension_values tool

• dataset_code plus dimension; for geo, geo_level picks a NUTS level (aggregate, country by default, nuts1, nuts2, nuts3). At most 2,000 values come back inline, in Eurostat's order

• Returns code/label pairs in values with totalCount, and truncated / shown / cap past the inline cap; fails as not_found, no_results, conflicting_params, upstream_fault, or canvas_not_found

• canvas_id stages every value, past the inline cap too, on that canvas as a code / label table (canvasId / tableName / stagedRowCount) that labels a download's code columns through a join; this tool never starts a canvas of its own

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 1–500 (default 50) sets the inline rows; lang is EN, FR, or DE

• Each observation carries code/label pairs per dimension, a nullable value, status (OBS_FLAG), and confStatus (CONF_STATUS); obsCount, missingObsCount, and timeRange cover the whole match, truncated is true above 5,000 observations, and unmatchedValues names filter values that matched nothing

• Fails as not_found, no_results (naming the unmatched values and the periods that carry no value), invalid_dimension, invalid_period, conflicting_params, a non-retryable async_response for a query too large to serve inline, or canvas_not_found

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 1–500 (default 50)

• Returns rowCount (echoed as totalCount), missingCount, periodRange, 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, or canvas_not_found

• The EUROSTAT_BULK_MAX_BYTES budget (default 50 MiB) stops a transfer mid-stream and returns what arrived with budgetExceeded: true

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 differ by the tool that staged them: eurostat_query_dataset writes a code and a _label column per dimension, eurostat_download_dataset codes only plus time — both with the same obs_* and conf_status* measures, so they join on dimension codes and time — and eurostat_get_dimension_values writes code and label

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 truncated, true past CANVAS_DEFAULT_ROW_LIMIT (default 10,000) rows; 64-bit integers arrive as strings. Fails as missing_table, canvas_not_found, or canvas_disabled

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

• 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 through the same tools: detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM. They report no period coverage or obsCount, and the trade flows mix annual and monthly series in one dataset, so filter freq; product, reporter and partner carry aggregates (TOTAL, EU27_2020, EXT_EU27_2020) that double-count when summed with their members. The Comext host serves no large collection unfiltered. PRODCOM values published as text arrive in valueText / obs_value_text (the unit KG), and its :C as confidentiality status C. A collection on neither host, such as the legacy DS-056120, is not disseminated

• NUTS geo-level filtering (aggregate / country / nuts1 / nuts2 / nuts3) on eurostat_query_dataset and eurostat_get_dimension_values, and OBS_FLAG (provisional, estimated, and so on) and CONF_STATUS (confidentiality) decoded into separate fields, with the same codes from JSON-stat and the bulk TSV

• Eurostat's too-large-to-serve responses (HTTP-200 async warnings, HTTP 413, SOAP fault 413, SOAP queue tickets) come back as non-retryable async_response, extraction_too_big, or async_queued errors that name the dataset's own dimensions left to filter, not timeouts

• Inline rows are capped by preview_limit (at most 500). With CANVAS_PROVIDER_TYPE=duckdb, a query match above 5,000 observations, or any bulk download, is staged whole as a SQL table (canvasId / tableName / stagedRowCount) for the dataframe tools, and canvas_id stages the next result beside earlier ones for joins — including a dimension's code/label list from eurostat_get_dimension_values, which labels a bulk table's codes. An empty download fails as no_results without creating or touching a canvas. The .mcpb bundle strips the native DuckDB binding, 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 inline preview omits rows, naming the staged table when there is one; eurostat_query_dataset's notice also names any filter value that matched nothing

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 (or Node.js v24+).

• No API key: Eurostat's dissemination API and its Comext host are 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

4. Configure environment (optional, every setting has a default):

cp .env.example .env

Configuration

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