ClaudeCodeMod

All shelves / MCP servers

io.github.cyanheads/eurostat-mcp-server

io.github.cyanheads/eurostat-mcp-server · 10 stars · TypeScript · Apache-2.0

MCP server Search and query the Eurostat catalogue — EU economy, demography, trade, and NUTS regional data.

Install

The repo has no one-line install. Follow its README.

Published as

  • npm@cyanheads/eurostat-mcp-serverstdio · Streamable HTTP
  • Remotehttps://eurostat.caseyjhand.com/mcpStreamable HTTP

From the server's entry in the official MCP Registry.

Open the repo

Configuration

NameSet asWhat it is
EUROSTAT_CLAMP_LIMITSOptionalEnv varClamp positive integer preview/search/dimension limits to 500/100/1000 with a notice. False restores schemas rejecting over-cap inputs.
MCP_LOG_LEVELOptionalEnv varSets the minimum log level for output (e.g., 'debug', 'info', 'warn').
EUROSTAT_BASE_URLOptionalEnv varEurostat API base URL. Override when using a mirror or proxy.
EUROSTAT_COMEXT_BASE_URLOptionalEnv varBase URL of the Comext dissemination host, which serves every DS-* dataset code (detailed trade and PRODCOM). Override when using a mirror or proxy.
EUROSTAT_REQUEST_TIMEOUT_MSOptionalEnv varTotal allowance for one Eurostat request across retries, backoff and body consumption, in milliseconds.
EUROSTAT_METADATA_TIMEOUT_MSOptionalEnv varTotal allowance for one dataset's SDMX dataflow structure across retries, backoff and body consumption, in milliseconds. Defaults to 120000; separate from EUROSTAT_REQUEST_TIMEOUT_MS for large structures.
EUROSTAT_TOC_CACHE_TTL_MSOptionalEnv varHow long a fetched catalogue TOC stays usable before the next catalogue call refreshes it, in milliseconds. Defaults to 12 hours.
EUROSTAT_BULK_TIMEOUT_MSOptionalEnv varTime budget for one eurostat_download_dataset call in milliseconds, counted from the start of the call: a filtered download's structure read, request retries, backoff and the streamed body with its staging all come out of it. Reached after rows have streamed, it keeps them as a prefix with budgetExceeded set; before the first row, the call fails as retry_deadline_exceeded. Defaults to 55000, under the 60-second request timeout of MCP SDK clients.
EUROSTAT_BULK_MAX_BYTESOptionalEnv varByte budget for one eurostat_download_dataset transfer, counted on the decoded TSV rather than on the wire. Eurostat sends the body chunked with no Content-Length, so the budget is enforced while streaming and the transfer is aborted when it is reached. Defaults to 50 MiB.
CANVAS_PROVIDER_TYPEOptionalEnv varDataframe canvas backend. The default, 'duckdb', lists eurostat_dataframe_describe and eurostat_dataframe_query, stages query matches with stage=true or above 5,000 observations, and retains bulk downloads beyond their previews. Set to 'none' to disable the canvas and those tools. The DuckDB binding ships with the server.
CANVAS_TEMP_PATHOptionalEnv varParent directory for DuckDB canvas spill files: a private 'mcp-canvas-XXXXXX' directory is created inside it, so it must be writable by the server process. Defaults to the OS temp directory.
CANVAS_TTL_MSOptionalEnv varSliding lifetime of a staged dataframe canvas in milliseconds; every call against it extends the window. Defaults to 24 hours.
CANVAS_DEFAULT_ROW_LIMITOptionalEnv varMaximum complete rows a single eurostat_dataframe_query returns before reporting truncated.
EUROSTAT_DATAFRAME_DROP_ENABLEDOptionalEnv varSet to 'true' to list eurostat_dataframe_drop, which removes one staged table from a dataframe canvas and leaves its other tables in place. Off by default because a drop cannot be undone; staged tables expire with their canvas either way. Has no effect with CANVAS_PROVIDER_TYPE=none.
MCP_TRANSPORT_TYPEOptionalEnv varSelects the HTTP transport.
MCP_HTTP_HOSTOptionalEnv varThe hostname for the HTTP server.
MCP_HTTP_PORTOptionalEnv varThe port to run the HTTP server on.
MCP_HTTP_ENDPOINT_PATHOptionalEnv varThe endpoint path for the MCP server.
MCP_PUBLIC_URLOptionalEnv varPublic origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).
MCP_AUTH_MODEOptionalEnv varAuthentication mode to use: 'none', 'jwt', or 'oauth'.

Files

README.md

@cyanheads/eurostat-mcp-server

Search and query the Eurostat catalogue — EU economy, demography, trade, health, and NUTS regional data via MCP. STDIO or Streamable HTTP.

6 Tools (up to 9 with the dataframe canvas) • 2 Resources • 1 Skill

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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
eurostat_search_datasets Search the Eurostat catalogue by keyword — returns codes, descriptions, period coverage, and theme breadcrumbs
eurostat_browse_themes Navigate the Eurostat theme hierarchy — list root themes or drill into subthemes and datasets
eurostat_get_dataset_info Fetch dataset metadata: dimensions with sample values, time range, observation count, and last-update date
eurostat_get_dimension_values List all valid codes for one dataset dimension, paged, with a code/label word filter, a code-prefix filter and NUTS hierarchy filtering for geo
eurostat_query_dataset Fetch a bounded preview of decoded observations with dimension filters, NUTS geo-level, and time-range controls
eurostat_download_dataset 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
eurostat_dataframe_describe List the tables staged on a dataframe canvas, with row counts and column types
eurostat_dataframe_query Run a read-only SQL SELECT across staged tables
eurostat_dataframe_drop Remove one staged table from a dataframe canvas, leaving its other tables in place (opt-in)
Resources
Resource Description
eurostat://dataset/{dataset_code} Dataset metadata (dimensions, time range, observation count, last-updated) by URI
skill://eurostat-guide/SKILL.md 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.

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; datasets and tables add their period, obsCount and lastUpdated (dd.mm.yyyy, as eurostat_search_datasets reports it) when Eurostat reports them, 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. On a dataset that lists no country values (tgs00010 is NUTS 2 only), omitting geo_level with canvas_id still stages every level it lists over an empty page, and the notice names the levels with their rows; without staging the call fails as no_results

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 extraction_too_big for a query too large to serve, a retryable async_response while Eurostat prepares a large extraction (repeat the call in a few minutes), 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, except that a time or time_period key is rejected (the period is set with since_period / until_period): 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 (a time or time_period filter key is answered with the since_period/until_period to set instead), invalid_period, filter_arity, a retryable async_queued (Eurostat is still preparing the extraction: repeat the call in a few minutes, or narrow it), a non-retryable extraction_too_big, no_results, upstream_fault (retryable when the SDMX endpoint is down), retry_deadline_exceeded when the call's time budget ends before the first row arrives or a filtered download's structure read outlasts the request deadline, or canvas_not_found
  • Two budgets bound the transfer: the EUROSTAT_BULK_MAX_BYTES budget (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 returns budgetExceeded: true; the notice names which budget stopped it. A byte 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 byte 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, 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, 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 extraction_too_big errors that name the dimensions left to filter. An extraction Eurostat is still preparing comes back as a retryable async_response (query) or async_queued (download), whose hint offers the repeat in a few minutes beside the same narrowing
  • 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

Variable Description Default
EUROSTAT_BASE_URL Eurostat API base URL. https://ec.europa.eu/eurostat/api/dissemination
EUROSTAT_COMEXT_BASE_URL Comext dissemination host, which serves every DS-* dataset code (detailed trade and PRODCOM). https://ec.europa.eu/eurostat/api/comext/dissemination
EUROSTAT_REQUEST_TIMEOUT_MS Total allowance for one request, including retries, backoff and body reads, in ms. 30000
EUROSTAT_METADATA_TIMEOUT_MS Total allowance for one dataset's SDMX dataflow structure, including retries, backoff and body reads, in ms. 120000 (2 min)
EUROSTAT_TOC_CACHE_TTL_MS Catalogue TOC cache lifetime, in ms. 43200000 (12 h)
EUROSTAT_BULK_TIMEOUT_MS Time budget for one eurostat_download_dataset call, counted from its start (structure read, attempts, backoff, body and staging), in ms. Ending the transfer after rows have streamed keeps them as a prefix with budgetExceeded; before the first row the call fails as retry_deadline_exceeded. Under the 60 s MCP SDK client timeout. 55000
EUROSTAT_BULK_MAX_BYTES Byte budget for one bulk download. 52428800 (50 MiB)
CANVAS_PROVIDER_TYPE Dataframe canvas backend; none disables the canvas and its tools. The .mcpb bundle sets none. duckdb
CANVAS_TTL_MS Sliding lifetime of a staged canvas, in ms. 86400000 (24 h)
CANVAS_DEFAULT_ROW_LIMIT Max complete rows one eurostat_dataframe_query returns before reporting truncated. 10000
EUROSTAT_CLAMP_LIMITS Clamp positive integer preview/search/dimension limits to 500/100/1,000 with a notice. false restores schemas rejecting over-cap inputs; zero, negatives, fractions and nonnumeric inputs are always rejected. Each clamp logs once and increments eurostat.limit_clamps, labelled by tool. true
EUROSTAT_DATAFRAME_DROP_ENABLED true lists eurostat_dataframe_drop; no effect with CANVAS_PROVIDER_TYPE=none. false
MCP_TRANSPORT_TYPE Transport: stdio or http. stdio
MCP_HTTP_PORT HTTP server port. 3010
MCP_SESSION_MODE HTTP session mode: stateless, stateful, or auto. The server declares stateless; a set value overrides it. stateless
MCP_AUTH_MODE Authentication: none, jwt, or oauth. none
MCP_LOG_LEVEL Log level (debug, info, warning, error, etc.). The Docker image sets info. debug
LOGS_DIR Directory for log files (Node.js only). <project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted. false
STORAGE_PROVIDER_TYPE Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1. in-memory
OTEL_ENABLED Enable OpenTelemetry. false

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

Directory Purpose
src/index.ts createApp() entry point — registers tools and the resource, inits services, gates the dataframe tools on the canvas and the drop tool on its own flag.
src/mcp-server/tools Tool definitions (*.tool.ts). Six discovery and data tools, plus three canvas-gated dataframe tools, one of them opt-in.
src/mcp-server/resources Resource definitions. Dataset metadata resource.
src/services/eurostat-catalogue 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.
src/services/eurostat-data Statistics API service — SDMX metadata parsing with a per-dataset cache, JSON-stat 2.0 decoding, async-response detection, canvas row source.
src/services/eurostat-bulk SDMX 2.1 TSV bulk service — streaming download, byte and time budgets, SOAP fault mapping, canvas row source.
src/services/eurostat-codelists.ts OBS_FLAG and CONF_STATUS codelists, the measure column names both stagers write, and the text-value decoder.
src/services/eurostat-hosts.ts Which host serves a dataset code: DS-* to the Comext host, everything else to the main one.
src/services/canvas-accessor.ts Accessor for the optional DataCanvas and the acquire helper canvas-touching tools share.
src/services/shared-load.ts Lets concurrent callers await one shared download, so one caller's cancellation releases only that caller.
src/config Server-specific environment variable parsing and validation with Zod.
skills/ Published eurostat-guide and SQL reference, served over MCP and included in installation packages.
tests/ Unit and integration tests, mirroring the src/ 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.

Facts

Kind
MCP server
Repo
cyanheads/eurostat-mcp-server
Group
Uncategorized
Stars
10
License
Apache-2.0
Language
TypeScript
Last push
2026-11-15
MCP Registry
io.github.cyanheads/eurostat-mcp-server
Homepage
www.npmjs.com/package/@cyanheads/eurostat-mcp-server
Topics
bun, demography, economy, eu, eurostat, gdp, mcp, mcp-server, model-context-protocol, nuts, open-data, statistics, trade, typescript, cyanheads

From the same owner

  1. 372Obsidian Mcp Servercyanheads/obsidian-mcp-serverRead, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.706
  2. 470ATLAS: Task Management Systemcyanheads/atlas-mcp-serverA Model Context Protocol (MCP) server for ATLAS, a Neo4j-powered task management system for LLM Agents - implementing a three-tier architecture (Projects, Tasks, Knowledge) to manage complex workflows. Now with Deep Research.480
  3. 643Model Context Protocol Resources & Guidescyanheads/model-context-protocol-resourcesExploring the Model Context Protocol (MCP) through practical guides, clients, and servers I've built while learning about this new protocol.295
  4. 906Git Mcp Servercyanheads/git-mcp-server245
  5. 1091Pubmed Mcp Servercyanheads/pubmed-mcp-server168
  6. 1138Mcp Ts Corecyanheads/mcp-ts-core154