faostat-mcp-server
An MCP server providing access to UN FAOSTAT global food and agriculture statistics. It serves data from a local SQLite mirror, allowing agents to list statistical domains, resolve codes for areas and items, query observations, and run SQL queries against staged dataframes.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
https://faostat.caseyjhand.com/mcpWhat its tools do
6 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Discover FAOSTAT statistical domains and their codes
- Resolve human terms to numeric codes for areas and items
- Query domain cubes by area, item, element, and year range
- Run read-only SQL SELECT statements against staged canvas tables
Source and maintenance
- Maintenance checked
Protocol and capabilities
- Server
- faostat-mcp-server 0.6.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 6 advertised
- Resources
- 1 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
6 advertised
faostat_list_domains — faostat-mcp-server: list domains
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.
{
"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
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domains",
"totalCount",
"totalMatches",
"truncated",
"indexedCount"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet."
},
"domains": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name",
"last_update",
"indexed",
"index_ready"
],
"properties": {
"code": {
"type": "string",
"description": "Domain code — the key for every query (e.g. \"QCL\")."
},
"name": {
"type": "string",
"description": "Human-readable domain name."
},
"topic": {
"type": "string",
"description": "FAOSTAT topic grouping, when provided."
},
"indexed": {
"type": "boolean",
"description": "True when this domain is in the local mirror selection (FAOSTAT_DOMAINS)."
},
"description": {
"type": "string",
"description": "Domain description, when provided."
},
"index_ready": {
"type": "boolean",
"description": "True when the local mirror for this domain has completed an initial sync."
},
"last_update": {
"type": "string",
"description": "Upstream last-update date (ISO 8601) from the manifest."
},
"indexed_last_sync": {
"type": "string",
"description": "ISO 8601 timestamp of the last completed local sync (when synced)."
},
"indexed_row_count": {
"type": "number",
"description": "Rows in the local mirror for this domain (present when indexed and synced)."
},
"file_size_in_bytes": {
"type": "number",
"description": "Compressed ZIP size in bytes, parsed from the manifest size string."
},
"upstream_row_count": {
"type": "number",
"description": "Row count reported by the manifest for the full domain."
}
},
"description": "One FAOSTAT domain with catalog metadata and local mirror status.",
"additionalProperties": false
},
"description": "Matching domains, sorted by code."
},
"truncated": {
"type": "boolean",
"description": "True when more matches remain beyond the returned page — fetch them with nextOffset."
},
"nextOffset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for exact-code lookups."
},
"totalCount": {
"type": "number",
"description": "Total domains in the FAOSTAT catalog, independent of any filter."
},
"indexedCount": {
"type": "number",
"description": "Domains currently indexed in the local mirror."
},
"totalMatches": {
"type": "number",
"description": "Domains matching the current filters, before the page limit is applied."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}faostat_resolve_codes — faostat-mcp-server: resolve codes
Resolve labels to the numeric codes or exact alphanumeric item identities faostat_query_observations needs: areas (countries/regions), items (commodities), and elements (metrics). Use query for full-text matching, name_contains for substring matching, code or code_text for exact identity, or omit them to list. Item and element matches occur in the selected domain; areas use shared vocabulary. For elements, optionally pass item_codes or item_codes_text to discover metrics and distinct units observed for those items; this does not establish area/year/source coverage. Empty item selectors match nothing. Page with offset and limit using nextOffset when truncated. Areas carry country/aggregate classification. Verified domain-specific item groups carry aggregate; null means unclassified, not safe-to-sum. Item groups can overlap their members even with matching units. Area aggregates include codes ≥ 5000 and curated roll-ups such as China=351; exclude overlapping regional and country rows when summing.
{
"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)."
},
"code_text": {
"type": "string",
"pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
"description": "Exact alphanumeric item code. Only for dimension item; mutually exclusive with code. Numeric identities use code."
},
"dimension": {
"enum": [
"area",
"item",
"element"
],
"type": "string",
"description": "Which dimension to resolve: \"area\" (countries/regions), \"item\" (commodities), or \"element\" (metrics)."
},
"item_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "For element resolution only: restrict elements and units to these items. Empty matches nothing; omit for domain-wide elements. Mutually exclusive with item_codes_text."
},
"name_contains": {
"type": "string",
"description": "Case-insensitive substring filter over the label. Used only when `query` is omitted."
},
"item_codes_text": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
"description": "Exact alphanumeric item identity."
},
"description": "For element resolution only: restrict elements and units to these exact text items. Empty matches nothing; mutually exclusive with item_codes."
}
},
"additionalProperties": false
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domain",
"dimension",
"matches",
"totalMatches",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_item_scope",
"invalid_text_selector",
"unknown_domain",
"index_not_ready",
"query_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_item_scope`: Item selectors are combined or supplied outside element resolution. `invalid_text_selector`: code_text is supplied with code or outside the item dimension. `unknown_domain`: The domain code is not a selected (indexed) FAOSTAT domain. `index_not_ready`: The shared dimension tables are empty, or the selected item/element domain requires an initial sync or an ingest upgrade. `query_timeout`: The item or element lookup's mirror read — time queued behind other calls' reads plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"domain": {
"type": "string",
"description": "The domain code echoed back."
},
"notice": {
"type": "string",
"description": "Guidance when nothing matched, more pages remain, or the dimension is not yet indexed."
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"code_text",
"name",
"kind"
],
"properties": {
"code": {
"type": [
"number",
"null"
],
"description": "Numeric code for faostat_query_observations; null for alphanumeric items carried by code_text."
},
"kind": {
"anyOf": [
{
"enum": [
"country",
"aggregate"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For areas: country or aggregate region. For items: aggregate only for verified domain-specific groups; null means unclassified, never safe-to-sum. Null for elements."
},
"name": {
"type": "string",
"description": "Human-readable label."
},
"units": {
"type": "array",
"items": {
"type": "string",
"description": "Observed unit label."
},
"description": "Element matches only: distinct non-null units observed in the selected domain and item scope. Empty means no specified units."
},
"cpc_code": {
"type": "string",
"description": "CPC crosswalk code for items (apostrophe stripped), when available."
},
"code_text": {
"type": [
"string",
"null"
],
"description": "Exact alphanumeric item identity for item_codes_text; null for numeric codes."
}
},
"description": "One resolved code match.",
"additionalProperties": false
},
"description": "Matching codes, relevance-ranked for query mode, else by code."
},
"dimension": {
"type": "string",
"description": "The dimension resolved."
},
"truncated": {
"type": "boolean",
"description": "True when more matches remain beyond the returned page — fetch them with nextOffset."
},
"nextOffset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for exact-code lookups."
},
"totalMatches": {
"type": "number",
"description": "Total matches in this domain before the result cap."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}faostat_query_observations — faostat-mcp-server: query observations
Query a FAOSTAT domain's data cube by area(s), item(s), element(s), sources, and year range, returning values with units and data-quality flags. Resolve numeric codes or exact alphanumeric item identities with faostat_resolve_codes; element resolution accepts item selectors and returns units. Empty queries with explicit items and elements list available elements for those items across the domain, without establishing area/year/source coverage. Aggregate regions are excluded by default; include_aggregates=true returns roll-ups, and explicit area_codes are honored verbatim. Item groups can overlap their members even with matching units; they remain included, and kind=null does not establish safe-to-sum. Keep source methodologies separate. Small results return inline; large ones spill to a DataCanvas table (canvas_id + table_name); call faostat_dataframe_describe for columns, then faostat_dataframe_query for analysis. Honor every row's flag: commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing, T=Unofficial, X=international organization; unrecognized flags never establish official status.
{
"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)."
},
"source_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "Exact source codes, such as 3050 or 3051 in GLE. Omit to return every methodology; choose or group sources before summing."
},
"element_codes": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "Element codes from faostat_resolve_codes (e.g. 5510 Production)."
},
"item_codes_text": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
"description": "Exact alphanumeric item code."
},
"description": "Exact alphanumeric item identities from resolver code_text; mutually exclusive with item_codes. Numeric codes use item_codes."
},
"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
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domain",
"observations",
"spilled",
"truncated",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"conflicting_item_selectors",
"domain_not_indexed",
"index_not_ready",
"canvas_disabled",
"canvas_not_found",
"invalid_year_range",
"query_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `conflicting_item_selectors`: Both numeric item_codes and exact item_codes_text are supplied. `domain_not_indexed`: The domain is not in the local mirror selection (FAOSTAT_DOMAINS) — whether a valid FAOSTAT code or not. `index_not_ready`: The domain mirror requires an initial sync or an ingest upgrade. `canvas_disabled`: The result is too large to inline but DataCanvas is off, so it cannot be staged for SQL. `canvas_not_found`: The result is large enough to stage and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. A result that fits inline stages nothing and never consults canvas_id. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. `query_timeout`: The call's mirror reads — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"domain": {
"type": "string",
"description": "The domain code echoed back."
},
"notice": {
"type": "string",
"description": "Guidance on empty results, aggregate exclusion, or how to reach the spilled set."
},
"spilled": {
"type": "boolean",
"description": "True when the full result was staged on a DataCanvas table."
},
"canvas_id": {
"type": "string",
"description": "Canvas ID holding the staged table (present when spilled) — pass it with table_name to faostat_dataframe_describe for the columns and types, then to faostat_dataframe_query for SQL."
},
"truncated": {
"type": "boolean",
"description": "True when the staged table hit the 50,000-row staging cap — the staged set is a PREFIX of the match, not the complete result. Partition the query by year or code ranges to capture the rest."
},
"table_name": {
"type": "string",
"description": "Canvas table holding the staged result set (present when spilled; a PREFIX of the match when truncated) — pass it as name to faostat_dataframe_describe, then reference it in faostat_dataframe_query SQL."
},
"totalCount": {
"type": "number",
"description": "Observations matched. Exact when the result was returned inline or fully staged. A floor — more matched — in two cases, both named by the notice: the match exceeded the 50,000-row staging cap (truncated is then true), or staging failed and the response fell back to an inline page."
},
"observations": {
"type": "array",
"items": {
"type": "object",
"required": [
"area_code",
"area",
"item_code",
"item_code_text",
"period",
"value_qualifier",
"source_code",
"source",
"item",
"element_code",
"element",
"year",
"value",
"unit",
"flag"
],
"properties": {
"area": {
"type": "string",
"description": "Area name."
},
"flag": {
"type": [
"string",
"null"
],
"description": "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; treat any unrecognized flag as informational, never assume official. Null when unflagged."
},
"item": {
"type": "string",
"description": "Item name."
},
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure; null when unspecified."
},
"year": {
"type": "number",
"description": "Observation year."
},
"value": {
"type": [
"number",
"null"
],
"description": "Observed value; null when the cell is empty."
},
"period": {
"type": [
"string",
"null"
],
"description": "Original multi-year period label; null for annual rows. Year is the integer midpoint."
},
"source": {
"type": [
"string",
"null"
],
"description": "Source methodology label; null when absent."
},
"element": {
"type": "string",
"description": "Element (metric) name."
},
"area_code": {
"type": "number",
"description": "Area code."
},
"item_code": {
"type": [
"number",
"null"
],
"description": "Numeric item code; null for alphanumeric identities."
},
"source_code": {
"type": [
"number",
"null"
],
"description": "Source methodology code; null when the domain has none."
},
"element_code": {
"type": "number",
"description": "Element code."
},
"item_code_text": {
"type": [
"string",
"null"
],
"description": "Exact alphanumeric item code; null for numeric identities."
},
"value_qualifier": {
"type": [
"string",
"null"
],
"description": "Bound operator such as <; value is a bound rather than an exact observation when present."
}
},
"description": "One observation. The flag is load-bearing — never drop or ignore it.",
"additionalProperties": false
},
"description": "Inline observations (preview when the full set spilled to a canvas table)."
},
"staged_row_count": {
"type": "number",
"description": "Rows actually staged on the canvas table (present when spilled). Equals the full match count unless truncated, in which case it is the 50,000-row cap."
},
"available_elements": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name",
"units"
],
"properties": {
"code": {
"type": "number",
"description": "Element code available for the selected items."
},
"name": {
"type": "string",
"description": "Element label."
},
"units": {
"type": "array",
"items": {
"type": "string",
"description": "Observed unit."
},
"description": "Distinct specified units for these items in this domain."
}
},
"description": "An element observed for the selected items.",
"additionalProperties": false
},
"description": "On an empty query with explicit items and elements: all elements available for those items across the domain. Does not establish coverage for requested area/year/source filters."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": false
}faostat_commodity_profile — faostat-mcp-server: commodity profile
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.
{
"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
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"item_query",
"resolved_items",
"top_producers",
"top_exporters",
"top_importers",
"production_trend",
"trend_points",
"spilled",
"truncated",
"resolvedItemCodes",
"resolvedItemMatches",
"itemsTruncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"missing_item",
"ambiguous_item",
"no_match",
"domain_not_indexed",
"index_not_ready",
"invalid_year_range",
"canvas_not_found",
"query_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `missing_item`: Neither item_code nor item_query was supplied. `ambiguous_item`: The query matches more than one QCL item without a unique exact label. `no_match`: The query matched no item, or item_code is absent from QCL. `domain_not_indexed`: The production domain (QCL) is not in the local mirror selection (FAOSTAT_DOMAINS), so there is no production data to profile. `index_not_ready`: The production domain (QCL) is selected, but its mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. `canvas_not_found`: DataCanvas is enabled and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `query_timeout`: The profile's mirror reads (commodity resolution, rankings, trend, staging stream) — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "States where the observation set went — the canvas table, inline result, staging failure, or disabled canvas — plus unavailable trade data, mixed units, or other partial-result context."
},
"spilled": {
"type": "boolean",
"description": "True when the merged observation set was staged on a canvas table."
},
"canvas_id": {
"type": "string",
"description": "Canvas ID this call staged onto. When spilled it holds table_name — pass both to faostat_dataframe_describe (table_name as name) for the columns and types, then canvas_id to faostat_dataframe_query for SQL. Also present when the merged set fit inline and no table was staged; faostat_dataframe_describe with this canvas_id then lists any tables already staged on it. Absent when the canvas is disabled or staging failed."
},
"truncated": {
"type": "boolean",
"description": "True when the STAGED CANVAS TABLE hit the 50,000-row staging cap and is therefore a PREFIX of the merged observation set — re-query faostat_query_observations partitioned by year to stage the rest. The rankings and production_trend above are SQL aggregates over the complete match and stay exact either way."
},
"item_query": {
"type": "string",
"description": "Supplied query echoed back, or the canonical selected label for code-only calls."
},
"table_name": {
"type": "string",
"description": "Canvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds. Pass it as name to faostat_dataframe_describe for its columns (a domain column tags each row QCL or TCL), then reference it in faostat_dataframe_query SQL."
},
"trend_points": {
"type": "number",
"description": "Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page."
},
"top_exporters": {
"type": "array",
"items": {
"type": "object",
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"properties": {
"area": {
"type": "string",
"description": "Country name."
},
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit."
},
"year": {
"type": "number",
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year."
},
"flags": {
"type": [
"string",
"null"
],
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — 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; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities."
},
"value": {
"type": "number",
"description": "Export quantity for the selected item and country in its latest reporting year."
},
"area_code": {
"type": "number",
"description": "Country code."
},
"observations": {
"type": "number",
"description": "Observations summed into value for the selected item and reporting year."
}
},
"description": "One top-exporting country.",
"additionalProperties": false
},
"description": "Top exporters by summed export quantity (empty when trade is not indexed)."
},
"top_importers": {
"type": "array",
"items": {
"type": "object",
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"properties": {
"area": {
"type": "string",
"description": "Country name."
},
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit."
},
"year": {
"type": "number",
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year."
},
"flags": {
"type": [
"string",
"null"
],
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — 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; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities."
},
"value": {
"type": "number",
"description": "Import quantity for the selected item and country in its latest reporting year."
},
"area_code": {
"type": "number",
"description": "Country code."
},
"observations": {
"type": "number",
"description": "Observations summed into value for the selected item and reporting year."
}
},
"description": "One top-importing country.",
"additionalProperties": false
},
"description": "Top importers by summed import quantity (empty when trade is not indexed)."
},
"top_producers": {
"type": "array",
"items": {
"type": "object",
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"properties": {
"area": {
"type": "string",
"description": "Country name."
},
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit."
},
"year": {
"type": "number",
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year."
},
"flags": {
"type": [
"string",
"null"
],
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — 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; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities."
},
"value": {
"type": "number",
"description": "Production for the selected item and country in its latest reporting year."
},
"area_code": {
"type": "number",
"description": "Country code."
},
"observations": {
"type": "number",
"description": "Observations summed into value for the selected item and reporting year."
}
},
"description": "One top-producing country.",
"additionalProperties": false
},
"description": "Top producers by summed production (countries only)."
},
"itemsTruncated": {
"type": "boolean",
"description": "Always false: successful profiles select one item without truncating selection."
},
"resolved_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "number",
"description": "Resolved item code."
},
"name": {
"type": "string",
"description": "Resolved item name."
}
},
"description": "One resolved commodity.",
"additionalProperties": false
},
"description": "The single selected QCL item and its canonical label."
},
"production_trend": {
"type": "array",
"items": {
"type": "object",
"required": [
"year",
"value",
"observations",
"unit",
"flags"
],
"properties": {
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure for value; null when unspecified. Points are grouped by unit, so a year can appear once per unit rather than summing incomparable quantities."
},
"year": {
"type": "number",
"description": "Observation year."
},
"flags": {
"type": [
"string",
"null"
],
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — 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; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities."
},
"value": {
"type": "number",
"description": "Selected item production summed across every country reporting that year."
},
"observations": {
"type": "number",
"description": "Observations summed into value — read it alongside value, since a change in coverage moves the total independently of production."
}
},
"description": "One annual trend point.",
"additionalProperties": false
},
"description": "The annual production series for the selected item, summed over countries per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap."
},
"staged_row_count": {
"type": "number",
"description": "Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated."
},
"resolvedItemCodes": {
"type": "array",
"items": {
"type": "number"
},
"description": "Item codes the commodity query resolved to."
},
"resolvedItemMatches": {
"type": "number",
"description": "Number of selected QCL items; always one for a successful profile."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": false
}faostat_dataframe_query — faostat-mcp-server: dataframe query
Run a single-statement SELECT against canvas tables staged by faostat_query_observations and faostat_commodity_profile (faostat_xxxxxxxx). Use DuckDB joins, aggregates, window functions, and CTEs for rankings and time-series analysis. Item groups can overlap their members even with matching units; do not sum them together, and resolver kind=null does not establish safe-to-sum. Separate source methodologies and respect bounded values and multi-year periods. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file functions are rejected; system catalogs are denied. List tables and columns with faostat_dataframe_describe. Preserve data-quality flags in projections: commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing, T=Unofficial, X=international organization; unrecognized flags never establish official status.
{
"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
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"columns",
"row_count",
"rows",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Materialized result rows, bounded by row_limit."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_disabled",
"canvas_not_found",
"missing_table",
"system_catalog_access",
"invalid_sql"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: The DataCanvas service is not configured for this deployment. `canvas_not_found`: An explicit canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `missing_table`: The SQL references a faostat_<id> table that has expired or was never staged. `system_catalog_access`: The SQL references a denied system catalog (information_schema, sqlite_master, duckdb_*). `invalid_sql`: The SQL has a syntax or execution error, or is not a single read-only SELECT. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance when the query returned no rows or when results were capped."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Column names in projection order."
},
"row_count": {
"type": "number",
"description": "Rows returned in this response — the materialized count, equal to rows.length. When truncated is true this is NOT the full result total (this path computes no exact total); page or aggregate to reach the rest."
},
"truncated": {
"type": "boolean",
"description": "True when row_limit capped the result and more rows exist than were returned. To reach them: page with ORDER BY + SQL LIMIT/OFFSET, raise row_limit (max 10000), or aggregate with GROUP BY."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}faostat_dataframe_describe — faostat-mcp-server: dataframe describe
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.
{
"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
}{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables",
"totalMatches",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_disabled",
"canvas_not_found",
"missing_table"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: The DataCanvas service is not configured for this deployment. `canvas_not_found`: An explicit canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `missing_table`: A name filter was supplied but no staged table on the resolved canvas matches it. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance when nothing is staged yet or more pages remain."
},
"tables": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"source_tool",
"query_params",
"created_at",
"expires_at",
"row_count",
"truncated",
"column_schema"
],
"properties": {
"name": {
"type": "string",
"description": "Canvas table name (faostat_xxxxxxxx)."
},
"row_count": {
"type": "number",
"description": "Rows staged in the table."
},
"truncated": {
"type": "boolean",
"description": "True when the staging cap was hit and the table holds fewer rows than the full result."
},
"created_at": {
"type": "string",
"description": "ISO 8601 creation timestamp."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp recorded when this table was staged."
},
"source_tool": {
"type": "string",
"description": "Tool that staged this table."
},
"query_params": {
"type": "object",
"description": "Input parameters the source tool was called with.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"column_schema": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name."
},
"type": {
"type": "string",
"description": "Canvas column type (VARCHAR, BIGINT, DOUBLE, …)."
}
},
"description": "One column declaration.",
"additionalProperties": false
},
"description": "Resolved column schema for the staged table."
}
},
"description": "Provenance and schema for one staged table.",
"additionalProperties": false
},
"description": "Active staged tables for this session, newest first — one page of them. Empty when none are staged."
},
"truncated": {
"type": "boolean",
"description": "True when more staged tables remain beyond the returned page — fetch them with nextOffset. Always false for a single-table `name` lookup, which is never paged."
},
"nextOffset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for `name` lookups."
},
"totalMatches": {
"type": "number",
"description": "Staged tables on the resolved canvas, before the page limit is applied."
}
},
"additionalProperties": false
}{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
faostat-guide
Analyze food and agriculture statistics with faostat_* tools. Use for cross-country comparisons, production and trade analysis, and SQL across staged results where coverage, reporting years, aggregate areas, units, or incomplete results affect the conclusion.
skill://faostat-guide/SKILL.mdio.modelcontextprotocol/skills
skill://{+path}30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 705 ms
- 95th percentile latency
- 705 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 705 ms · metadata changed · 6 tool(s), 1 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
claude mcp add --transport http faostat-mcp-server-caseyjhand https://faostat.caseyjhand.com/mcpCodex
codex mcp add faostat-mcp-server-caseyjhand --url https://faostat.caseyjhand.com/mcpCursor
{
"mcpServers": {
"faostat-mcp-server-caseyjhand": {
"url": "https://faostat.caseyjhand.com/mcp"
}
}
}Cline
{
"mcpServers": {
"faostat-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://faostat.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
{
"servers": {
"faostat-mcp-server-caseyjhand": {
"type": "http",
"url": "https://faostat.caseyjhand.com/mcp"
}
}
}Gemini CLI
gemini mcp add --transport http faostat-mcp-server-caseyjhand https://faostat.caseyjhand.com/mcpClaude Desktop
https://faostat.caseyjhand.com/mcpWindsurf
{
"mcpServers": {
"faostat-mcp-server-caseyjhand": {
"serverUrl": "https://faostat.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like faostat-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.