xippios-faostat-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-faostat
Typed Python client, MCP server and FastAPI routes for FAOSTAT, 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-faostat # client only
uv add "xippios-faostat[mcp]" # + MCP server
uv add "xippios-faostat[http]" # + FastAPI routerA FAO account is needed: FAOSTAT_USERNAME (the account's e-mail) and
FAOSTAT_PASSWORD in the environment. The client logs in with them on its first request
(POST /auth/login, FAOSTAT's auth_login), once per process, sends the access token
with every request to the API, and logs in again when the token lapses (after an hour) or a request
is refused with HTTP 401 or 403. Neither the credentials nor a token is logged, and the
tasks return neither. The bulk downloads need none.
Related MCP server: usda-nass
30-second example
from xippios.faostat import get_data, get_series, list_domains, list_elements
wheat = get_data("QCL", area="231", element="2510", item="15", year=range(2015, 2022))
row = wheat.data[0] # wheat production in the United States of America, 2015
row.area, row.item, row.year # ("United States of America", "Wheat", "2015")
row.element_code, row.element # ("5510", "Production"): the answer's code, not the 2510 sent
row.value, row.unit, row.flag_description # (Decimal("55839540"), "t", "Official value")
wheat.meta.vintage # "2025-12-31": QCL's last update, as list_domains prints it
wheat.meta.request # {"lang": "en", "domain_code": "QCL", "area": "231", ...}
series = get_series("QCL", "231", "15", "2510", since=2015, until=2021) # the same seven rows
series.meta.request["year"], series.meta.request["since"] # ("2015,2016,...,2021", 2015)
list_domains(search="prices").data # PP, CP, PD, PE (group Prices) and PA, an archive
list_elements("QCL", search="production").data[0] # code "2510", "Production Quantity"
get_data("QCL", area="231", element="5510") # UnknownCode: did you mean 2510 (Production Quantity)?get_data(domain, *, area, item, element, year, area_cs, item_cs, page_size, page_number) sends one request to FAOSTAT's data endpoint (get_data, GET /{lang}/data/{domain_code}), in English, with the output options the portal sends (codes,
units, flags and notes shown); each filter is a code or a list of codes. At least one of
area, item, element and year is needed: FAOSTAT refuses a query without a filter,
and so does get_data, before sending. Without page_size every matching row comes in
one answer; with page_size and page_number, one page. A query filters by the element
codes of the domain's element list (2510, Production Quantity), and the rows print other
codes (5510, Production). FAOSTAT answers a code it does not know with no rows, so for
the five domains whose code tables ship with the package, QCL, TCL, FBS, PP and RL,
get_data checks every area, element and item code before sending and refuses one the
domain's table lacks with UnknownCode, naming the table, its fetch date and the
closest codes; another domain's codes are sent unchecked, and a code that matches nothing
there gives an empty list. An unknown domain raises NotFoundError. meta.vintage is
the domain's date_update from list_domains (groupsanddomains); meta.published_at
stays None, since a date is no release time.
get_series(domain, area, item, element, *, since, until) is one get_data request
for a yearly series: since and until become the year filter, the years from one to
the other as upstream's comma list, or no year filter when both are left out, which
answers every year the domain holds; one without the other is refused before sending.
The rows come in upstream's order, area, item, year ascending in the recorded answers,
and a year the domain does not hold has no row. The codes are checked as get_data checks them, and meta is
get_data's, with since and until added to meta.request.
list_areas(domain, *, search), list_elements(domain, *, search) and
list_items(domain, *, search) list the codes those filters take, for the same five
domains, from the package's copies of FAOSTAT's code lists (getCodeList,
codes/<dimension>/<domain>, src/xippios/faostat/reference/), without a request;
search keeps the codes whose code or label contains the text. The element lists hold
the filter codes, not the codes the rows print. meta.retrieved_at is when the package
fetched the list.
Bulk downloads
from pathlib import Path
from xippios.faostat import download_dataset, list_bulk_datasets
from xippios.faostat.parse import parse_bulk_csv
list_bulk_datasets(search="land use").data[0] # dataset_code "RL", file_size "2902KB", ...
land = download_dataset("RL", Path("RL.zip")) # 3 MB; TCL's ZIP is 267 MB
land.data.path # PosixPath("RL.zip"): the ZIP as FAOSTAT serves it
land.meta.vintage # "2026-10-02T00:00:00": the catalogue's DateUpdate as printed
land.meta.published_at # 2026-10-02 00:00 without a zone, meta.published_at_naive set
rows = parse_bulk_csv(land.data.path) # one BulkRecord per row of its table, read lazily
first = next(rows)
first.area, first.area_code_m49, first.item, first.year # ("Afghanistan", "'004", ...)
first.value, first.unit # (Decimal("65286.000000"), "1000 ha")list_bulk_datasets(*, search) lists the datasets FAOSTAT publishes as files, 69 on
2026-10-29, from the bulk downloads' catalogue (production/datasets_E.json on
bulks-faostat.fao.org), fetched without the account: each with its code, the domain
code get_data takes, its name, last update, the ZIP's size and URL and the rows of its
table; search keeps the datasets whose code or name contains the text.
download_dataset(domain, dest) looks the dataset up in the catalogue and streams its
ZIP to dest, without the account, never holding it in memory or caching it; it returns
core's Downloaded (path, size, content type, ETag, Last-Modified, 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. The files run from 12 KB (MDDW) to 410 MB (TM); TCL's is 267 MB.
meta.vintage is the catalogue's DateUpdate as printed and meta.published_at the
same time, which the catalogue prints without a zone. parse_bulk_csv(path) reads the
ZIP's normalized table, the member <Name>_E_All_Data_(Normalized).csv, row by row,
straight from the archive: each BulkRecord has the columns of the production files
(area_code, area_code_m49 as printed with its apostrophe, area, item_code,
item_code_cpc, item, element_code, element, year_code, year, unit,
value as a Decimal, flag, note), None where a dataset does not print one, and
every other column of a dataset under its header in columns, as MDDW's surveys and
food groups.
MCP
{
"mcpServers": {
"faostat": {
"command": "uvx",
"args": ["--from", "xippios-faostat[mcp]", "xippios-faostat-mcp"]
}
}
}Tools are read-only and named faostat_<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 |
The catalogue's |
| none: a bulk task, Python only, which the adapters skip | alpha |
Every request to the API logs in first where the process has no current token
(auth_login, POST /auth/login); the login is the client's, no task's. The bulk
downloads' catalogue and files are fetched without it.
Upstream terms and attribution
Data comes from FAOSTAT (https://www.fao.org/faostat/) under the FAO Statistical Database Terms of Use: unless their metadata or webpage say otherwise, the datasets FAO's corporate statistical databases disseminate, FAOSTAT among them (the terms' Annex 1), are licensed under the Creative Commons Attribution-4.0 International licence (CC BY 4.0), as complemented by those terms. The terms ask for this citation:
FAO. [YYYY (year of last update)]. [Name of database: Name of dataset OR Name of database]. [Accessed on [DD Month YYYY]]. [URL] Licence: CC-BY-4.0.
This package adds no rights to the data. Documentation snapshot and its attribution:
docs/upstream/FETCHED.md.
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
Read-only cited financial datasets, bounded research queries and source diagnostics.
Search and query 1,500+ OECD statistical datasets via SDMX. Keyless.
Query official statistics through MCP, with periods, places and citable sources in every answer.
Search ILOSTAT labour indicators, query and compare series, build country profiles, run SQL.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables users to query UN international trade statistics and row counts through read-only MCP tools, with validated parameters and safeguards for large queries.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes read-only tools for querying USDA NASS Quick Stats, covering reported counts, filtered data pulls, parameter values, crop progress and condition, county yield and production, acreage and forecasts, and prices received. Results are capped with guidance on narrowing queries.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes read-only tools for querying USDA FAS PSD Online commodity supply and distribution data, with every response carrying release metadata such as source, endpoint, retrieval time and vintage. Results are capped by row count and size, with guidance returned on how to narrow a query.45 PyPIApache 2.0
- AlicenseNot gradedqualityBmaintenanceRead-only MCP tools for querying USDA FAS Global Agricultural Trade System census export and import records by partner country, year, month and HS10 code prefix, plus the release-date lists for each flow. Results are capped with notes on omitted rows, and responses carry release vintages and retrieval metadata.Apache 2.0