faostat_query_observations
ActiveTool of io.github.cyanheads/faostat-mcp-server
Query a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) for GROUP BY / ranking / time-series analysis via faostat_dataframe_query. Every row carries its flag (A=Official, E=Estimated, I=Imputed, B=break, X=external) — honor it; never treat estimated/imputed values as official.
Parameters schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain"
],
"properties": {
"limit": {
"type": "integer",
"default": 200,
"maximum": 1000,
"minimum": 1,
"description": "Max observations returned inline when the result does not spill. Max 1000."
},
"domain": {
"type": "string",
"minLength": 1,
"description": "FAOSTAT domain code (e.g. \"QCL\"). Must be indexed locally."
},
"year_end": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Inclusive end year (e.g. 2022)."
},
"canvas_id": {
"type": "string",
"description": "Canvas ID from a prior call to stage onto. Omit to start a fresh canvas (a new id is returned)."
},
"area_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim."
},
"item_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "Item codes from faostat_resolve_codes."
},
"year_start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Inclusive start year (e.g. 2000)."
},
"element_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "Element codes from faostat_resolve_codes (e.g. 5510 Production)."
},
"include_aggregates": {
"type": "boolean",
"default": false,
"description": "When false (default), exclude aggregate-region rows (codes ≥ 5000) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed."
}
}
}No endpoints wrapped at confidence ≥ 0.70.
Parent server
io.github.cyanheads/faostat-mcp-server
https://github.com/cyanheads/faostat-mcp-server
1/7 registries