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 - Remote
https://eurostat.caseyjhand.com/mcpStreamable HTTP
From the server's entry in the official MCP Registry.
Configuration
| Name | Set as | What it is |
|---|---|---|
EUROSTAT_CLAMP_LIMITSOptional | Env var | Clamp positive integer preview/search/dimension limits to 500/100/1000 with a notice. False restores schemas rejecting over-cap inputs. |
MCP_LOG_LEVELOptional | Env var | Sets the minimum log level for output (e.g., 'debug', 'info', 'warn'). |
EUROSTAT_BASE_URLOptional | Env var | Eurostat API base URL. Override when using a mirror or proxy. |
EUROSTAT_COMEXT_BASE_URLOptional | Env var | Base 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_MSOptional | Env var | Total allowance for one Eurostat request across retries, backoff and body consumption, in milliseconds. |
EUROSTAT_METADATA_TIMEOUT_MSOptional | Env var | Total 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_MSOptional | Env var | How long a fetched catalogue TOC stays usable before the next catalogue call refreshes it, in milliseconds. Defaults to 12 hours. |
EUROSTAT_BULK_TIMEOUT_MSOptional | Env var | Time 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_BYTESOptional | Env var | Byte 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_TYPEOptional | Env var | Dataframe 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_PATHOptional | Env var | Parent 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_MSOptional | Env var | Sliding lifetime of a staged dataframe canvas in milliseconds; every call against it extends the window. Defaults to 24 hours. |
CANVAS_DEFAULT_ROW_LIMITOptional | Env var | Maximum complete rows a single eurostat_dataframe_query returns before reporting truncated. |
EUROSTAT_DATAFRAME_DROP_ENABLEDOptional | Env var | Set 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_TYPEOptional | Env var | Selects the HTTP transport. |
MCP_HTTP_HOSTOptional | Env var | The hostname for the HTTP server. |
MCP_HTTP_PORTOptional | Env var | The port to run the HTTP server on. |
MCP_HTTP_ENDPOINT_PATHOptional | Env var | The endpoint path for the MCP server. |
MCP_PUBLIC_URLOptional | Env var | Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com). |
MCP_AUTH_MODEOptional | Env var | Authentication mode to use: 'none', 'jwt', or 'oauth'. |
Files
@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 SkillPublic 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
querywords are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code, ignoring spacing beside punctuation (Rev.2findsRev. 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 (pharmacistfindsPharmacists,med_spec=PHARM).limitis a positive integer (default 20), clamped to 100 with a notice. Page by passingnextCursorback ascursor; cursor calls ignorelimit- Results carry
code,label,type(dataset/table), period coverage,obsCount,lastUpdated, andthemePath, withtotalMatchesacross every page. A row found through dimension value labels carriesmatchedValues(dimension,code,label; the code is the filtereurostat_query_datasettakes) and the response carries anotice. Fails asno_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 retryableupstream_faultwhen no catalogue is loaded and Eurostat's table of contents is unreachable - If the Comext dataflow list cannot be loaded, results carry
comextListMissingand anotice; a catalogue that could not be refreshed carriescatalogueLoadedAt
eurostat_browse_themes tool
- Omit
theme_codefor the top-level theme folders; pass a folder code for its immediate children. Codes resolve exact-first, then case-insensitively. The Comext collections sit underext_go_detail(detailed trade, inext_go) andprom(PRODCOM, inicts) - Items carry
code,label,type(folder/dataset/table), andhasChildren; datasets and tables add their period,obsCountandlastUpdated(dd.mm.yyyy, aseurostat_search_datasetsreports it) when Eurostat reports them, with aparentPathbreadcrumb andotherPlacementsfor a folder filed in several branches; fails asnot_foundfor an unknown code,not_a_folderfor a dataset or table code, or a retryableupstream_faultwhen no catalogue is loaded and Eurostat's table of contents is unreachable - If the Comext dataflow list cannot be loaded,
ext_goandictscarrycomextListMissingand anotice; a catalogue that could not be refreshed carriescatalogueLoadedAt
eurostat_get_dataset_info tool
- One
dataset_code; returns every dimension withvaluesCountand up to 10sampleValues, plustimeRange,obsCount,lastUpdated, and the ESMSmetadataUrl - Fails as
not_foundfor an unknown dataset, orupstream_faultwhen Eurostat returns a structure the server cannot read (retryable when the endpoint is down)
eurostat_get_dimension_values tool
dataset_codeplusdimension, resolved exact-first then case-insensitively (TIME_PERIODaliasestime); returned value codes and labels stay unchanged. Forgeo,geo_levelpicks a NUTS level (aggregate,countryby default,nuts1,nuts2,nuts3).filterkeeps values whose code and label contain every word given, ignoring case and accents (palma frankfurtfindsDE_EDDF_ES_LEPA);code_prefixkeeps values whose code starts with the text, ignoring case (geo_levelnuts2withDElists the German NUTS 2 regions). Both apply before paging and are counted inmatchCountlimitdefaults to 25 and clamps to 1,000 with a notice. Pages contain that many values, fewer at the end, withtotalCountfor the full list; a page with more after it carriestruncated,nextCursor(pass back ascursor), and anotice. Continuations retain the effective count and ignore a newlimit; older cursors above 1,000 normalize to 1,000 with disclosure. Fails asnot_found,no_results,conflicting_params,invalid_cursor,upstream_fault(retryable when the endpoint is down), orcanvas_not_foundcanvas_idstages the dimension's whole list on that canvas as acode/labeltable (canvasId/tableName/stagedRowCount), whateverfilter,code_prefixorlimitsay, that labels a download's code columns through a join; it never starts a canvas of its own. Ageotable adds alevelcolumn (NULL for a code with no NUTS level) and, withoutgeo_level, holds every level, aggregates and regions overlapping the countries they contain: filterlevelbefore joining or aggregating. On a dataset that lists no country values (tgs00010is NUTS 2 only), omittinggeo_levelwithcanvas_idstill stages every level it lists over an empty page, and thenoticenames the levels with their rows; without staging the call fails asno_results
eurostat_query_dataset tool
dataset_codeplusfilters({dimension_code: [values]}),geo_level, and eithersince_period/until_period(2020,2020-Q1,2020-01, down toYYYY-WnnandYYYY-Dnnn) orlast_n_periods;preview_limitis a positive integer (default 25), clamped to 500 with a notice;langisEN,FR, orDE- 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, andemptyValuesnames it stage: truestages the whole match on an available canvas, regardless of size; reusecanvas_idor omit it to create one. Without it, automatic staging starts above 5,000 observations.truncatedstill describes that threshold;tableNameidentifies a staged result. Canvas-disabled deployments disclose an explicit staging request as unavailablelast_n_periodscounts 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 asince_period–until_periodrange 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 astime=<date>, because Eurostat ignores one-day bounds - Each observation carries code/label pairs per dimension, a nullable
value,status(OBS_FLAG), andconfStatus(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), andtimeRangecover the whole match. A notice names periods outside that span.truncatedis true above 5,000 observations,unmatchedValuesnames filter values that matched nothing, andemptyValuesnames values the dataset has but this match carries no cell for (undergeo_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, orgeo_levelas 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-retryableextraction_too_bigfor a query too large to serve, a retryableasync_responsewhile Eurostat prepares a large extraction (repeat the call in a few minutes),retry_deadline_exceededwhen the Statistics API does not complete the query within the request deadline,canvas_not_found, or a retryableupstream_faultwhen the Statistics API is down
eurostat_download_dataset tool
dataset_codeplus the samefiltersmap andsince_period/until_period(nolast_n_periods: the TSV keeps a column per period unless a range drops it);preview_limitis 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_valueand 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 filtersfollow the query tool's rules, except that atimeortime_periodkey is rejected (the period is set withsince_period/until_period): a value holding+is split into separate values (OR), and one holding.is rejected asinvalid_dimensionbefore any request, since no Eurostat code contains one. A valid value with no observation in the selected periods adds no rows, andemptyValuesnames it (omitted whenbudgetExceededis true)- Returns
rowCount(echoed astotalCount),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), andbytesReadfor the whole download; fails asnot_found,invalid_dimension(atimeortime_periodfilter key is answered with thesince_period/until_periodto set instead),invalid_period,filter_arity, a retryableasync_queued(Eurostat is still preparing the extraction: repeat the call in a few minutes, or narrow it), a non-retryableextraction_too_big,no_results,upstream_fault(retryable when the SDMX endpoint is down),retry_deadline_exceededwhen the call's time budget ends before the first row arrives or a filtered download's structure read outlasts the request deadline, orcanvas_not_found - Two budgets bound the transfer: the
EUROSTAT_BULK_MAX_BYTESbudget (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 returnsbudgetExceeded: true; thenoticenames which budget stopped it. A byte budget too small for a complete header and usable row fails asbyte_budget_exceeded, with the configured limit and narrowing guidance.bytesReadcounts accepted decoded bytes, never more than the byte budget; incomplete trailing rows are discarded.
eurostat_dataframe_describe tool
canvas_idfrom a staging response; lists each table'sname,rowCount, typed columns, andexpiresAt(slidingCANVAS_TTL_MS, default 24h); fails ascanvas_not_foundorcanvas_disabled- Columns depend on the staging tool:
eurostat_query_datasetwrites a code and a_labelcolumn per dimension,eurostat_download_datasetcodes only plustime(both share theobs_*andconf_status*measures), andeurostat_get_dimension_valueswritescodeandlabel(pluslevelforgeo)
eurostat_dataframe_query tool
- One read-only
SELECTper call; chained statements, other verbs, and functions that read files or external data are rejected - Returns
columns,rows,rowCount, and required booleantruncated. Every row supplied by the canvas is returned intact, up toCANVAS_DEFAULT_ROW_LIMIT(default 10,000). Cells render as lossless JSON, including nesting and quoted strings; 64-bit integers arrive as strings. Fails asmissing_table,canvas_not_found, orcanvas_disabled - A cut sets
truncated: trueand adds a notice. Page an unchanged deterministic SELECT with a totalORDER BY(tie-breakers required),LIMITandOFFSET; advance by actualrowCount. 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_idplustable_name, exactly aseurostat_dataframe_describelists it; removes that one table and leaves the canvas and its other tables in place. Listed only whenEUROSTAT_DATAFRAME_DROP_ENABLED=trueis set beside the canvas- Returns
canvasId,tableName,dropped, andexpiresAt;droppedisfalse, with anotice, when nothing by that name was staged, so repeating a drop is safe. Fails ascanvas_not_found,identifier_reserved, orcanvas_disabled
eurostat://dataset/{dataset_code} resource
- Same payload as
eurostat_get_dataset_info, returned asapplication/json; a failed read carries the samereasonand a recovery hint, andretryableon an outage dataset_codecomes fromeurostat_search_datasetsoreurostat_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,freqincluded, since trade flows mix annual and monthly series; aggregates such asTOTAL,EU27_2020, andEXT_EU27_2020double-count when summed with their members. PRODCOM text values arrive invalueText/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_bigerrors that name the dimensions left to filter. An extraction Eurostat is still preparing comes back as a retryableasync_response(query) orasync_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.mcpbbundle strips the native DuckDB binding and runs withCANVAS_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
reasonand arecovery.hintnaming the next tool to call - Next-step hints:
eurostat_search_datasetsandeurostat_browse_themesreturn anextSteppointing 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:
appliedFiltersoneurostat_query_datasetandappliedQuery(with the SDMXurl) oneurostat_download_dataset, plus anoticewhen 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/catchin tool logic - Use
ctx.logfor logging,ctx.statefor storage - Register new tools and resources in the
createApp()arrays insrc/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
- Group
- Uncategorized
- Stars
- 10
- License
- Apache-2.0
- Language
- TypeScript
- Last push
- 2026-11-15
- MCP Registry
- io.github.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
- 372Obsidian Mcp Servercyanheads/obsidian-mcp-serverRead, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.706
- 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
- 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
- 906Git Mcp Servercyanheads/git-mcp-server245
- 1091Pubmed Mcp Servercyanheads/pubmed-mcp-server168
- 1138Mcp Ts Corecyanheads/mcp-ts-core154