UN FAOSTAT global food & agriculture statistics over a local SQLite mirror, via MCP.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Assemble a global profile for one QCL item in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Supply item_code or item_query; code wins when both are supplied. A query selects a unique normalized exact label, otherwise a unique relevance match; ambiguous queries require an explicit code. Each ranking uses the selected item at each country's own latest year with data, grouped by unit. The trend is returned inline as year/value points. Country-level only (aggregates excluded). QCL is required; unavailable TCL yields a production-only profile with a notice. When the merged observation set is too large to inline, it spills to a DataCanvas table (canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for deeper SQL.
Number of top producers / exporters / importers to return. Max 50.
Inclusive end year for the trend (e.g. 2022).
Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.
Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.
Commodity label or search term (e.g. "Wheat"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as "maize" or "milk" require item_code. Supply this or item_code.
Inclusive start year for the trend (e.g. 1990).
Assemble a global profile for one QCL item in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Supply item_code or item_query; code wins when both are supplied. A query selects a unique normalized exact label, otherwise a unique relevance match; ambiguous queries require an explicit code. Each ranking uses the selected item at each country's own latest year with data, grouped by unit. The trend is returned inline as year/value points. Country-level only (aggregates excluded). QCL is required; unavailable TCL yields a production-only profile with a notice. When the merged observation set is too large to inline, it spills to a DataCanvas table (canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for deeper SQL.
| Argument | Type | Description |
|---|---|---|
| top_n | integer | Number of top producers / exporters / importers to return. Max 50. |
| year_end | integer | Inclusive end year for the trend (e.g. 2022). |
| canvas_id | string | Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one. |
| item_code | integer | Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item. |
| item_query | string | Commodity label or search term (e.g. "Wheat"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as "maize" or "milk" require item_code. Supply this or item_code. |
| year_start | integer | Inclusive start year for the trend (e.g. 1990). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"top_n": {
"type": "integer",
"default": 10,
"maximum": 50,
"minimum": 1,
"description": "Number of top producers / exporters / importers to return. Max 50."
},
"year_end": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Inclusive end year for the trend (e.g. 2022)."
},
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one."
},
"item_code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item."
},
"item_query": {
"type": "string",
"minLength": 1,
"description": "Commodity label or search term (e.g. \"Wheat\"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as \"maize\" or \"milk\" require item_code. Supply this or item_code."
},
"year_start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Inclusive start year for the trend (e.g. 1990)."
}
},
"additionalProperties": false
}List the canvas tables (faostat_xxxxxxxx) staged by faostat_query_observations and faostat_commodity_profile, each with its source tool, the query parameters that produced it, creation/expiry timestamps, row count, and column schema. Call this before faostat_dataframe_query to discover the exact table and column names to reference in SQL. Tables are listed newest-first and paged: pass `name` to describe one table outright, or page with `offset` + `limit` — when the response reports `truncated`, pass the returned `nextOffset` to fetch the rest.
| Argument | Type | Description |
|---|---|---|
| name | string | Optional table name (faostat_xxxxxxxx) to describe a single staged table. Takes precedence over `offset` / `limit`, which are ignored for a name lookup (always single-page). |
| limit | integer | Maximum staged tables to return on this page (max 100). Each entry carries a full column schema, so the default keeps a discovery call small. |
| offset | integer | Zero-based pagination offset into the staged tables (newest first). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for `name` lookups. |
| canvas_id | string | Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to list the tables staged in this session (the common case). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"name": {
"type": "string",
"description": "Optional table name (faostat_xxxxxxxx) to describe a single staged table. Takes precedence over `offset` / `limit`, which are ignored for a name lookup (always single-page)."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1,
"description": "Maximum staged tables to return on this page (max 100). Each entry carries a full column schema, so the default keeps a discovery call small."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based pagination offset into the staged tables (newest first). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for `name` lookups."
},
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to list the tables staged in this session (the common case)."
}
},
"additionalProperties": false
}Run a single-statement SELECT against the canvas tables staged by faostat_query_observations and faostat_commodity_profile (table names look like faostat_xxxxxxxx). Use this for cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set the inline preview only sampled. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all work. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected; system catalogs (information_schema, sqlite_master, duckdb_*) are denied — list staged tables via faostat_dataframe_describe. Every row carries its data-quality `flag` — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — keep it in projections, treat any unrecognized flag as informational, and never assume it is official.
| Argument | Type | Description |
|---|---|---|
| sql* | string | Single-statement read-only SELECT against staged faostat_<id> tables. Columns: area_code, area, item_code, item, element_code, element, year, unit, value, flag — plus domain (QCL or TCL) on tables staged by faostat_commodity_profile. |
| canvas_id | string | Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to query the tables staged in this session (the common case). |
| row_limit | integer | Hard cap on rows in the response. Default 1000, max 10000. |
Discover FAOSTAT statistical domains (production, trade, food balances, food security, land use, agri-emissions, prices, value) with their codes, descriptions, last-update date, upstream row count, and local index status. Every query keys on a domain code from here. The `indexed` flag tells you which domains are queryable right now; un-indexed domains exist in the catalog but must be added to FAOSTAT_DOMAINS and re-synced before faostat_query_observations can read them. The catalog runs to ~69 domains with long descriptions, so responses are paged: narrow with `topic` / `indexed_only`, pass `code` to fetch one domain outright, or page with `offset` + `limit` — when the response reports `truncated`, pass the returned `nextOffset` to fetch the rest.
| Argument | Type | Description |
|---|---|---|
| code | string | Exact domain code lookup (e.g. "RL"), case-insensitive. Returns that one domain's full record on a single page. Takes precedence over `topic` / `indexed_only` when provided. |
| limit | integer | Maximum domains to return on this page (max 200 — above the catalog size, so raise it to fetch everything at once). Domain descriptions are long; the default keeps a browse call small. |
| topic | string | Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog. |
| offset | integer | Zero-based pagination offset into the matching domains (code-sorted). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page). |
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) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for GROUP BY / ranking / time-series analysis. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. Max 1000. |
| domain* | string | FAOSTAT domain code (e.g. "QCL"). Must be indexed locally. |
| year_end | integer | Inclusive end year (e.g. 2022). |
Resolve human terms to the opaque integer codes faostat_query_observations needs, within a dimension: areas (countries/regions), items (commodities), or elements (metrics like production, yield, import quantity). Pass `query` for fuzzy full-text matching ("maize" → item 56), `name_contains` for a substring filter, or `code` for an exact-code lookup; omit all three to list the whole dimension. Item and element results are scoped to the requested domain — only codes present in that domain's cube are returned, so a resolved code is always queryable there (areas are shared across domains). Page large listings with `offset` + `limit`: when the response reports `truncated`, pass the returned `nextOffset` to fetch the next page. Every area match is flagged `country` or `aggregate` — aggregates (World, continents, economic groupings — codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351, which sums mainland + Taiwan + Hong Kong + Macao) double-count if summed with their member countries, so resolve before querying and exclude aggregates unless you want the regional roll-up.
| Argument | Type | Description |
|---|---|---|
| code | integer | Exact code lookup. Takes precedence over `query`/`name_contains` when provided. |
| limit | integer | Maximum matches to return (max 200). |
| query | string | Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked. |
| domain* | string | FAOSTAT domain code (e.g. "QCL"). Item and element resolution is scoped to the codes present in this domain's data; area code lists are shared across all indexed domains. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"description": "Single-statement read-only SELECT against staged faostat_<id> tables. Columns: area_code, area, item_code, item, element_code, element, year, unit, value, flag — plus domain (QCL or TCL) on tables staged by faostat_commodity_profile."
},
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to query the tables staged in this session (the common case)."
},
"row_limit": {
"type": "integer",
"default": 1000,
"maximum": 10000,
"minimum": 1,
"description": "Hard cap on rows in the response. Default 1000, max 10000."
}
},
"additionalProperties": false
}| indexed_only |
| boolean |
| When true, return only domains indexed in the local mirror (queryable now). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"code": {
"type": "string",
"description": "Exact domain code lookup (e.g. \"RL\"), case-insensitive. Returns that one domain's full record on a single page. Takes precedence over `topic` / `indexed_only` when provided."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 200,
"minimum": 1,
"description": "Maximum domains to return on this page (max 200 — above the catalog size, so raise it to fetch everything at once). Domain descriptions are long; the default keeps a browse call small."
},
"topic": {
"type": "string",
"description": "Case-insensitive substring filter over domain code, name, and topic (e.g. \"trade\", \"emissions\", \"QCL\"). Omit to list the full catalog."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based pagination offset into the matching domains (code-sorted). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page)."
},
"indexed_only": {
"type": "boolean",
"default": false,
"description": "When true, return only domains indexed in the local mirror (queryable now)."
}
},
"additionalProperties": false
}| canvas_id |
| string |
| Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one. |
| area_codes | array | Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim. |
| item_codes | array | Item codes from faostat_resolve_codes. |
| year_start | integer | Inclusive start year (e.g. 2000). |
| element_codes | array | Element codes from faostat_resolve_codes (e.g. 5510 Production). |
| include_aggregates | boolean | When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"domain"
],
"properties": {
"limit": {
"type": "integer",
"default": 200,
"maximum": 1000,
"minimum": 1,
"description": "Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. 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",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one."
},
"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 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed."
}
},
"additionalProperties": false
}| offset | integer | Zero-based pagination offset into the match set. When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page). |
| dimension* | string | Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics). |
| name_contains | string | Case-insensitive substring filter over the label. Used only when `query` is omitted. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"domain",
"dimension"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Exact code lookup. Takes precedence over `query`/`name_contains` when provided."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "Maximum matches to return (max 200)."
},
"query": {
"type": "string",
"description": "Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. \"wheat\", \"import quantity\"). Relevance-ranked."
},
"domain": {
"type": "string",
"minLength": 1,
"description": "FAOSTAT domain code (e.g. \"QCL\"). Item and element resolution is scoped to the codes present in this domain's data; area code lists are shared across all indexed domains."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based pagination offset into the match set. When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page)."
},
"dimension": {
"enum": [
"area",
"item",
"element"
],
"type": "string",
"description": "Which dimension to resolve: \"area\" (countries/regions), \"item\" (commodities), or \"element\" (metrics)."
},
"name_contains": {
"type": "string",
"description": "Case-insensitive substring filter over the label. Used only when `query` is omitted."
}
},
"additionalProperties": false
}