xippios-eurostat-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
xippios-eurostat
Typed Python client, MCP server and FastAPI routes for Eurostat dissemination API, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).
Install
uv add xippios-eurostat # client only
uv add "xippios-eurostat[mcp]" # + MCP server
uv add "xippios-eurostat[http]" # + FastAPI routerNo API key is needed.
Related MCP server: DuckDB Eurostat MCP Server
30-second example
from xippios.eurostat import get_data
milk = get_data("apro_mk_cola", {"geo": "AT", "time": ["2022", "2023"]})
cube = milk.data # the JSON-stat 2.0 dataset, member by member
cube.id # ["freq", "milkitem", "dairyprod", "unit", "geo", "time"]
cube.size # [1, 3, 10, 2, 1, 2]: codes per dimension
cube.value["40"] # 3247.05: cell 40, row-major over size, the last dimension fastest
cube.status["64"] # "|C": confidential, as cube.extension["status"]["label"] names it
first = next(cube.observations()) # one cell with its codes and labels
first.codes # {"freq": "A", "milkitem": "PRD", "dairyprod": "D1110D", "unit": "THS_T", ...}
first.labels["dairyprod"], first.value # "Raw cows' milk delivered to dairies", 3247.05
milk.meta.published_at # 2026-10-05 23:00+02:00: the dataset's last update, `updated`
milk.meta.vintage # "2026-10-05T23:00:00+0200": the same, as Eurostat prints it
milk.meta.request # {"dataset": "apro_mk_cola", "filters": {...}, "lang": "EN"}get_data(dataset, filters=None, *, lang=Lang.EN, since_time_period=None, until_time_period=None, last_time_period=None, geo_level=None) sends one request to the
Statistics API (statistics/1.0/data/{datasetCode}). A DS- dataset, Comext trade or
Prodcom production, is requested on Eurostat's Comext base, every other on the main
base; the call and its answer are the same, and a value is the text Eurostat prints where
a Prodcom indicator is a unit or a flag:
oil = get_data(
"DS-059358", # Prodcom: sold production, exports and imports
{"reporter": "AT", "product": "10411200"}, # fish and marine oils, NACE 10.41
since_time_period="2022",
until_time_period="2023",
)
oil.data.id # ["freq", "reporter", "product", "indicators", "time"]
oil.data.value["6"], oil.data.value["12"] # 349477 (EXPVAL 2022), "KG" (QNTUNIT 2022)filters maps any dimension of the dataset to one code or a list of codes ({"geo": "AT", "milkitem": "PRD"}); a time filter selects periods, and so do since_time_period,
until_time_period and last_time_period. Eurostat accepts one time parameter per query,
the one exception being since_time_period with until_time_period; any other
combination is refused before sending. lang takes Lang.EN, Lang.FR or Lang.DE and
geo_level a GeoLevel (aggregate, country, nuts1, nuts2, nuts3, city), both
in xippios.eurostat.models; a plain string such as "FR" works too. A code that matches
nothing gives an empty cube, size 0 on that dimension. meta.published_at is the cube's
updated with Eurostat's zone; one printed without a zone, never seen, is kept as printed
with meta.published_at_naive set, and meta.vintage holds the text either way. An
unknown dataset, and Eurostat's "No results found", raise NotFoundError; a query
Eurostat refuses or judges too large raises InvalidRequestError with Eurostat's message
and how to narrow it. A query Eurostat would answer asynchronously raises it too: this
package does not poll asynchronous answers, and the Statistics API's own route is to send
the same request again later. Ask for small slices: the cube comes back whole, and over
MCP a result above 64 KB is replaced by a preview and a note.
Slices
from xippios.eurostat import get_cross_section, get_latest_period, get_series
milk = {"milkitem": "PRD", "dairyprod": "D1110D", "unit": "THS_T"}
series = get_series("apro_mk_cola", {**milk, "geo": "AT"}, since="2015", until="2023")
[(o.codes["time"], o.value) for o in series.data] # [("2015", 3102.56), ..., ("2023", 3242.85)]
latest = get_latest_period("apro_mk_cola", {**milk, "geo": "AT"})
latest.data[0].codes["time"], latest.data[0].value # ("2025", 3503.31)
section = get_cross_section("apro_mk_cola", "2023", milk) # every geo code the dataset holds
len(section.data) # 36: the geo codes with a value or a status in 2023
section.meta.request # {"dataset": "apro_mk_cola", "filters": {..., "time": "2023"}, "lang": "EN"}Each slice sends one get_data request and returns the cube's observations as a list
of Observation, with get_data's meta: meta.request names what was sent
(since_time_period, last_time_period, the time filter).
get_series(dataset, filters, *, since=None, until=None, lang=Lang.EN) wants every
dimension but time pinned to one code; an answer that spans more than one series raises
InvalidRequestError naming each dimension still open and its codes.
get_latest_period(dataset, filters=None, *, lang=Lang.EN) asks for lastTimePeriod=1,
the most recent period, and get_cross_section(dataset, period, filters=None, *, lang=Lang.EN) for time=<period>; both return any number of series in cube order. Each
refuses a time filter before sending, since it selects the periods itself, and
get_cross_section an empty period. A code that matches nothing gives an empty list.
Over MCP each slice keeps the family's cap, 200 rows or 64 KB, with a note of its own on
how to see the rest.
Prodcom production
from xippios.eurostat import get_sold_production, get_total_production, list_products
soya = list_products(search="soya") # the PRODCOM products, without a request
soya.data[0] # Code(code="10412100", label="Crude soya-bean oil and its fractions ...")
oil = get_sold_production("10411200", reporters=["AT"], since="2022", until="2023")
values = {(o.codes["indicators"], o.codes["time"]): o.value for o in oil.data}
values["EXPVAL", "2023"], values["QNTUNIT", "2023"] # 415790 (euro), "KG"
oil.meta.request # {"dataset": "DS-059358", "filters": {"reporter": ["AT"], ...}, ...}
manure = get_total_production("20158000", reporters=["AT"], since="2022", until="2023")
[(o.codes["indicators"], o.codes["time"], o.value) for o in manure.data][:2]
# [("APRODQNT", "2022", 84470389), ("APRODQNT", "2023", 14769157)], in QNTUNIT "KG"Eurostat's Prodcom statistics, production of manufactured goods, food and agricultural
inputs among them, are served on the Comext base. get_sold_production(product, reporters=None, since=None, until=None, indicators=None) reads DS-059358, sold
production, exports and imports, and get_total_production(...) DS-059359, total
production, one product at a time: each sends one get_data request and returns the
cube's observations in cube order with get_data's meta. reporters are country codes
(["AT"]), since and until years, and indicators the measures (PRODVAL,
PRODQNT in QNTUNIT, EXPVAL, EXPQNT, IMPVAL, IMPQNT for DS-059358; APRODQNT
in QNTUNIT for DS-059359), None for every one. A value is a number, or the text
Eurostat prints for a unit or a flag ("KG", ":E"). The product is checked against the
dataset's product list packaged with this version, each reporter against CXT_FREE_ISO,
Comext's list of reporters and partners, and each indicator against the whole
CXT_INDICATORS list, before sending: a code they lack raises UnknownCode naming the
closest. CXT_INDICATORS also holds the indicators of the other dataset and of Comext's
trade datasets, so one the dataset lacks (PRODVAL for DS-059359) passes the check and
Eurostat answers it with an empty cube, an empty list. A reporter the list holds and the
dataset lacks is Eurostat's to answer, as the indicator was; no such answer is recorded.
list_products(search=None) lists DS-059358's products (CXT_PRODCOM2_SOLD), eight-digit
codes that start with their NACE class (1041 oils and fats, 2015 fertilisers);
DS-059359 covers a few hundred of them, chiefly chemicals, fertilisers and metals, which
list_codes("cxt_prodcom2_total") lists. Over MCP the production tasks keep the family's
cap, 200 rows or 64 KB, with a note naming reporters, indicators and since, and
eurostat_list_products takes up to 1,000 rows within 64 KB, with a note naming
search.
Comext trade
from xippios.eurostat import get_trade, get_trade_hs, list_cn8, list_hs
list_cn8(search="crude soya-bean oil").data[1]
# Code(code="15071090", label="Crude soya-bean oil, whether or not degummed (excl. for ...")
list_hs(search="soya").data[0] # Code(code="1201", label="Soya beans, whether or not broken")
oil = get_trade("15071090", reporters=["AT"], partners=["DE"], since="2023-01", until="2023-12")
values = {(o.codes["flow"], o.codes["indicators"], o.codes["time"]): o.value for o in oil.data}
values["2", "VALUE_IN_EUROS", "2023-12"] # 305451: Austria's exports to Germany, in euro
values["2", "QUANTITY_IN_100KG", "2023-12"] # 3372.15, in 100 kg
oil.meta.request # {"dataset": "DS-045409", "filters": {"freq": "M", "reporter": ["AT"], ...}, ...}
heading = get_trade_hs("1507", reporters=["AT"], partners=["DE"], since="2023-12", until="2023-12")
[(o.codes["flow"], o.codes["indicators"], o.value) for o in heading.data][:2]
# [("1", "VALUE_EUR", 1222), ("1", "VALUE_NAC", 1222)]: imports of soya-bean oil, HS 1507Eurostat's Comext trade statistics, the EU side of the trade picture, are served on the
Comext base. get_trade(product, reporters=None, partners=None, flow=None, since=None, until=None, freq=Freq.M, indicators=None) reads DS-045409, EU trade since 1988 by HS2-4-6
and CN8, and get_trade_hs(...), with the same parameters, DS-059341, international trade
of EU and non-EU countries since 2002 by HS2-4-6, one product at a time: each sends one
get_data request and returns the cube's observations in cube order (reporter, partner,
flow, indicator, oldest period first) with get_data's meta. product is an
eight-digit CN code ("15071090", crude soya-bean oil) or an HS chapter, heading or
subheading ("15", "1507", "150710"); reporters and partners are country codes of
CXT_FREE_ISO (["AT"], ["DE", "US"]), which holds aggregates too ("EU27_2020_EXTRA",
"WORLD"); flow is "1" for imports and "2" for exports, None for both; freq
"M" for monthly periods (since="2023-01") or "A" for annual ones (since="2023"),
Freq.M and Freq.A in xippios.eurostat.models; indicators the measures,
VALUE_IN_EUROS, QUANTITY_IN_100KG and SUPPLEMENTARY_QUANTITY in DS-045409,
VALUE_EUR, VALUE_NAC and QUANTITY_KG in DS-059341, None for every one. Every code
is checked against the lists packaged with this version before sending, the product
against CXT_NC, the reporters and partners against CXT_FREE_ISO, the flow against
CXT_EU_FLUX and the indicators against CXT_INDICATORS: a code they lack raises
UnknownCode naming the closest. DS-059341's product list is CXT_NC too, so a CN8 code
passes the check for get_trade_hs, and DS-059341 answers one asynchronously (HTTP 413
ASYNCHRONOUS_RESPONSE), which this package does not poll: InvalidRequestError; give it
an HS code.
list_cn8(search=None) and list_hs(search=None) list CXT_NC's codes by length, the
eight-character ones and the two-, four- and six-character ones, without a request
(list_codes("cxt_nc") lists them all, TOTAL with them); a code with letters in it
("1507XXXX", "15SSS421") is Eurostat's position for trade no regular code holds (not
elsewhere specified, confidential), as its label says. Over MCP the trade tasks keep the
family's cap, 200 rows or 64 KB, with a note naming partners, indicators, since and
freq, and eurostat_list_cn8 and eurostat_list_hs take up to 1,000 rows within 64 KB,
with a note naming search.
Datasets and codes
from xippios.eurostat import list_codes, list_datasets
milk = list_datasets(search="milk") # 18 leaves of the table of contents
cola = list_datasets(search="apro_mk_cola").data[0]
cola.code, cola.type # ("apro_mk_cola", "dataset")
cola.title # "Production of main cows' milk products - annual data"
cola.path # "Database by themes > Agriculture, forestry and fisheries > ... > Milk and milk products"
cola.last_update, cola.data_start, cola.data_end # ("05.10.2026", "1968", "2025"), as printed
milk.meta.vintage, milk.meta.published_at # "20261028T1000", 2026-10-28 10:00 without a zone
austria = list_codes("geo", search="austria")
austria.data # [Code(code="AT", label="Austria")]
austria.meta.vintage, austria.meta.published_at # "28.0", 2026-03-25 23:00+01:00
list_codes("unit", search="THS_T").data[0] # Code(code="THS_T", label="Thousand tonnes")Both answer from lists packaged with this version, without a request: meta.retrieved_at
is when the package fetched the list, meta.endpoint the operation it came from.
list_datasets(search=None) reads Eurostat's table of contents (catalogue/toc/xml):
every dataset and pre-defined table of the navigation tree, over 10,000 leaves, one per
listing in the tree, each with its code, type, English title, the folders above it
(path, joined with " > "), its last update and structure change, its first and last
period and its number of values as Eurostat prints them. meta.vintage is the table of
contents' creationDate as printed and meta.published_at the same time, which
Eurostat prints without a zone, so meta.published_at_naive is set.
list_codes(codelist, search=None) reads one of eighteen SDMX codelists
(sdmx/2.1/codelist/ESTAT/<ID>, English labels): FREQ, GEO, UNIT, CROPS, STRUCPRO,
MILKITEM, DAIRYPROD, STATINFO, LEG_FORM, FARMTYPE, SO_EUR and UAAREA, the codelists of
the dimensions of apro_cpnh1, apro_mk_cola and ef_m_farmleg, named as the dimension is
("geo", case-insensitive); and from the Comext base CXT_PRODCOM2_SOLD,
CXT_PRODCOM2_TOTAL and CXT_INDICATORS, the product and indicators codes of the
Prodcom datasets, and CXT_NC, CXT_FREE_ISO and CXT_EU_FLUX, the product, reporter
and partner, and flow codes of the Comext trade datasets, whose meta.endpoint is
the codelist's full URL there. meta.vintage is the codelist's version and
meta.published_at its last update, None for CXT_EU_FLUX, which names none.
Another name raises UnknownCode naming the closest packaged codelists. search keeps
the records whose code or title (label) contains the text, ignoring case. Over MCP
eurostat_list_datasets keeps the family's cap and eurostat_list_codes takes up to
1,000 codes within the family's 64 KB, so every packaged codelist but GEO, the two
PRODCOM product lists and CXT_NC comes whole; both notes name search.
Bulk download
from pathlib import Path
from xippios.eurostat import download_dataset
from xippios.eurostat.parse import parse_sdmx_csv
milk = download_dataset(
"apro_mk_cola", "A...THS_T.AT", since="2022", until="2023", dest=Path("milk.csv.gz")
)
milk.data.path # PosixPath("milk.csv.gz"): the gzip-compressed SDMX-CSV file
milk.data.bytes # 335
milk.data.filename # "estat_apro_mk_cola_filtered_en.csv.gz", Eurostat's name for it
milk.meta.vintage # "05/10/26 23:00:00": LAST UPDATE as printed, day first
milk.meta.published_at # 2026-10-05 23:00 without a zone, meta.published_at_naive set
rows = parse_sdmx_csv(milk.data.path) # one SdmxCsvRow per observation, read lazily
first = next(rows)
first.dimensions # {"freq": "A", "milkitem": "PRD", "dairyprod": "D1110D", ...}
first.time_period, first.obs_value # ("2022", Decimal("3247.05"))download_dataset(dataset, key="", *, since=None, until=None, last_n_observations=None, dest) sends one SDMX 2.1 data query (dataQuery, sdmx/2.1/data/{flowRef}/{key}) with
format=SDMX-CSV and compressed=true and streams the answer to dest, never holding
it in memory or caching it; it returns core's Downloaded (path, size, content type,
Eurostat's file name, retrieval time). It is a bulk task: Python only, so the MCP server
and the router skip it and no agent is handed a file path. key is Eurostat's series
key, the dimensions but time in the dataset's order, dot-separated, empty for every code
of a dimension, + between codes ("A...THS_T.AT+DE"); "" downloads the whole
dataset.
since, until and last_n_observations are Eurostat's startPeriod, endPeriod and
lastNObservations. meta.vintage is the file's LAST UPDATE as printed and
meta.published_at the same time, which Eurostat prints without a zone; both are None
for a file without a row. A query Eurostat would answer asynchronously, or refuses as
too large, raises InvalidRequestError naming how to narrow it. parse_sdmx_csv(path)
reads the file, gzip-compressed or plain, row by row: each SdmxCsvRow has the
dataflow, the last_update, the dimensions in column order, the time_period, the
obs_value as a Decimal, or as the text printed where it is no number (Prodcom's
"KG", ":E"), None when empty, obs_flag, conf_status and any other attributes
of the dataset, as Eurostat prints them. A DS- dataset is downloaded from the Comext
base, key in its own dimensions' order ("A.AT.10411200." for DS-059358); a Comext
trade dataset is served filtered only, a Prodcom dataset whole as well.
from xippios.eurostat import download_trade
oil = download_trade(
"15071090", reporters=["AT"], since="2023-01", until="2023-12", dest=Path("oil.csv.gz")
)
oil.meta.request["key"] # "M.AT..15071090..": every partner, both flows, every indicatordownload_trade(product=None, reporters=None, partners=None, flow=None, since=None, until=None, freq=Freq.M, indicators=None, *, dest) is the second bulk task, Python only as
well: it builds DS-045409's series key from get_trade's arguments in the dataset's
order, freq.reporter.partner.product.flow.indicators, + between codes and an empty
position for an argument left None, checks every code as get_trade does, and
downloads the file as download_dataset does; meta.request records the arguments and
the key sent. product or reporters is required, since Eurostat serves no Comext trade
dataset whole; a query too large for Eurostat to answer at once (500,000 cells, the
product of the codes each position matches) raises InvalidRequestError naming how to
narrow it. download_dataset("DS-045409", key) takes a key of your own.
MCP
{
"mcpServers": {
"eurostat": {
"command": "uvx",
"args": ["--from", "xippios-eurostat[mcp]", "xippios-eurostat-mcp"]
}
}
}Tools are read-only and named eurostat_<verb>_<noun>. Results are capped, at
200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest.
--http serves streamable HTTP instead of stdio.
Status
Upstream operation | Task function | MCP tool | Status |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
| none: a bulk task, Python only, which the adapters skip | alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
| none: a bulk task, Python only, which the adapters skip | alpha |
Five of these fifteen tasks choose the base URL by the dataset's code: get_data, the
three slices and download_dataset request a dataset whose code starts with DS-,
Eurostat's Comext and Prodcom datasets, on
https://ec.europa.eu/eurostat/api/comext/dissemination, and every other on the main base
URL, https://ec.europa.eu/eurostat/api/dissemination. The two production tasks,
get_sold_production and get_total_production, and the three trade tasks, get_trade,
get_trade_hs and download_trade, always request the Comext base, which serves
Prodcom's DS-059358 and DS-059359 and Comext's DS-045409 and DS-059341. list_codes
lists eighteen packaged codelists, twelve of the main base and six of the Comext base;
list_products lists the Comext base's list of sold-production products,
CXT_PRODCOM2_SOLD, and list_cn8 and list_hs the trade datasets' products, CXT_NC.
list_datasets lists the main base's table of contents only, and does not list the
Comext or Prodcom datasets: the Comext base answers catalogue/toc/xml with HTTP 404
(probed 2026-10-28), though its WADL lists it. Not covered: polling an asynchronous
answer, which is refused with how to narrow the query; SDMX-ML and TSV; codelists other
than the eighteen packaged ones, which list_codes refuses naming the closest.
Upstream terms and attribution
Data comes from Eurostat dissemination API (https://ec.europa.eu/eurostat/web/main/data/database) under its own terms of use;
this package adds no rights to it. Documentation snapshot and its attribution,
Eurostat's reuse and citation lines among them: docs/upstream/FETCHED.md.
Documents
sdk-core: docs/conventions.md — the conventions every xippios source package follows: its layout, names, results, tests and releases.
sdk-core: docs/adr.md — the index of the family's architecture decisions, which the conventions cite.
sdk-core: docs/definition-of-done.md — what a change satisfies before its pull request is opened.
sdk-core: docs/review-checklist.md — what the review of a pull request checks, in order.
sdk-eurostat: docs/adr.md — the index of this package's own decisions, generated from the records in
docs/adr/.sdk-eurostat: docs/upstream/FETCHED.md — the snapshot of the upstream documentation, the reference for names, parameters and semantics.
Licence
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Read-only cited financial datasets, bounded research queries and source diagnostics.
Search and query the Eurostat catalogue — EU economy, demography, trade, and NUTS regional data.
Experimental MCP providing read-only population statistics from Eurostat.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes the Eurostat Statistics API, enabling LLMs to discover, explore, and retrieve official EU statistical data through search, dimension inspection, and data retrieval tools.3-
- AlicenseNot gradedqualityDmaintenanceEnables querying Eurostat data using natural language, powered by DuckDB for optimized performance.MIT
- AlicenseNot gradedqualityBmaintenanceEnables querying Eurostat statistical data through natural language or direct MCP tools, wrapping the Eurostat API without authentication.146 npmMIT
- AlicenseAqualityBmaintenanceEnables querying Eurostat data via four narrow tools for dataset search, structure retrieval, code lookup, and data queries, with server-side validation and compact responses.7AGPL 3.0