io.github.cyanheads/faostat-mcp-server

Official6 toolsLive

by cyanheads · TypeScript

UN FAOSTAT global food & agriculture statistics over a local SQLite mirror, via MCP.

io.github.cyanheads/faostat-mcp-server (MCP Server)

This MCP server exposes UN FAOSTAT global food and agriculture statistics from a local SQLite mirror built from the FAOSTAT bulk-download corpus. It provides a DataCanvas SQL surface and serves over MCP using STDIO and Streamable HTTP. The package is written in TypeScript and includes 6 tools.

🛠️ Key Features

Local SQLite mirror of FAOSTAT bulk-download data
DataCanvas SQL surface for querying
MCP transport via STDIO and Streamable HTTP
6 tools exposed by the server

🚀 Use Cases

Accessing global food-security and agriculture statistics via SQL queries
Integrating FAOSTAT open data into AI agents using MCP
Building developer workflows around structured FAOSTAT statistics

⚡ Developer Benefits

Developer-friendly integration through Model Context Protocol (MCP)
Querying through a DataCanvas SQL interface
Works with common storage and analytics tooling (SQLite, DuckDB mentioned in topics)

⚠️ Limitations

Only described at a high level; no specific tool names or query schemas provided in the provided source excerpt.

Topics

agriculturebuncyanheadsduckdbfaofaostatfood-securitymcpmcp-servermodel-context-protocolopen-datasqlitestatisticstypescriptai-agentsfood

Captured live from the server via tools/list.

faostat_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.

Parameters5

code	string	optional	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.
topic	string	optional	Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog.
indexed_only	boolean	optional	When true, return only domains indexed in the local mirror (queryable now).
limit	integer	optional	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.
offset	integer	optional	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).

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "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.",
      "type": "string"
    },
    "topic": {
      "description": "Case-insensitive substring filter over domain code, name, and topic (e.g. \"trade\", \"emissions\", \"QCL\"). Omit to list the full catalog.",
      "type": "string"
    },
    "indexed_only": {
      "default": false,
      "description": "When true, return only domains indexed in the local mirror (queryable now).",
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 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).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

faostat_resolve_codes

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.

Parameters7

domain	string	required	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.
dimension	string	required	Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics).
query	string	optional	Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked.
name_contains	string	optional	Case-insensitive substring filter over the label. Used only when `query` is omitted.
code	integer	optional	Exact code lookup. Takes precedence over `query`/`name_contains` when provided.
limit	integer	optional	Maximum matches to return (max 200).
offset	integer	optional	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).

Raw schema

{
  "type": "object",
  "properties": {
    "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."
    },
    "dimension": {
      "type": "string",
      "enum": [
        "area",
        "item",
        "element"
      ],
      "description": "Which dimension to resolve: \"area\" (countries/regions), \"item\" (commodities), or \"element\" (metrics)."
    },
    "query": {
      "description": "Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. \"wheat\", \"import quantity\"). Relevance-ranked.",
      "type": "string"
    },
    "name_contains": {
      "description": "Case-insensitive substring filter over the label. Used only when `query` is omitted.",
      "type": "string"
    },
    "code": {
      "description": "Exact code lookup. Takes precedence over `query`/`name_contains` when provided.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 50,
      "description": "Maximum matches to return (max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 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).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "domain",
    "dimension"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

faostat_query_observations

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.

Parameters9

domain	string	required	FAOSTAT domain code (e.g. "QCL"). Must be indexed locally.
area_codes	array	optional	Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim.
item_codes	array	optional	Item codes from faostat_resolve_codes.
element_codes	array	optional	Element codes from faostat_resolve_codes (e.g. 5510 Production).
year_start	integer	optional	Inclusive start year (e.g. 2000).
year_end	integer	optional	Inclusive end year (e.g. 2022).
include_aggregates	boolean	optional	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.
limit	integer	optional	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.
canvas_id	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "minLength": 1,
      "description": "FAOSTAT domain code (e.g. \"QCL\"). Must be indexed locally."
    },
    "area_codes": {
      "description": "Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "item_codes": {
      "description": "Item codes from faostat_resolve_codes.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "element_codes": {
      "description": "Element codes from faostat_resolve_codes (e.g. 5510 Production).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "year_start": {
      "description": "Inclusive start year (e.g. 2000).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "year_end": {
      "description": "Inclusive end year (e.g. 2022).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "include_aggregates": {
      "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.",
      "type": "boolean"
    },
    "limit": {
      "default": 200,
      "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "canvas_id": {
      "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.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

faostat_commodity_profile

Assemble a global profile for one commodity in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Accepts a commodity name, resolves it to item codes, then queries the production (QCL) and trade (TCL) domains and merges the results. Each ranking is a per-country sum across the resolved items, taken at that country's own latest year with data and grouped by unit so incomparable quantities are never added. The trend is returned inline as year/value points. Country-level only (aggregates excluded). The production domain (QCL) is required. When the trade domain (TCL) is not indexed locally, returns a production-only profile with a notice naming the gap rather than failing. 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.

Parameters5

item_query	string	required	Commodity name to profile (e.g. "maize", "wheat", "coffee green"). Matched by relevance; the 5 best-matching items are folded into one profile, so a broad name such as "milk" is narrowed — the response discloses how many items matched in total.
year_start	integer	optional	Inclusive start year for the trend (e.g. 1990).
year_end	integer	optional	Inclusive end year for the trend (e.g. 2022).
top_n	integer	optional	Number of top producers / exporters / importers to return. Max 50.
canvas_id	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "item_query": {
      "type": "string",
      "minLength": 1,
      "description": "Commodity name to profile (e.g. \"maize\", \"wheat\", \"coffee green\"). Matched by relevance; the 5 best-matching items are folded into one profile, so a broad name such as \"milk\" is narrowed — the response discloses how many items matched in total."
    },
    "year_start": {
      "description": "Inclusive start year for the trend (e.g. 1990).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "year_end": {
      "description": "Inclusive end year for the trend (e.g. 2022).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "top_n": {
      "default": 10,
      "description": "Number of top producers / exporters / importers to return. Max 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "canvas_id": {
      "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.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "item_query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

faostat_dataframe_query

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.

Parameters3

canvas_id	string	optional	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).
sql	string	required	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.
row_limit	integer	optional	Hard cap on rows in the response. Default 1000, max 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "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).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    },
    "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."
    },
    "row_limit": {
      "default": 1000,
      "description": "Hard cap on rows in the response. Default 1000, max 10000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

faostat_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.

Parameters4

canvas_id	string	optional	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).
name	string	optional	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	optional	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	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "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).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    },
    "name": {
      "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).",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md19 KBView on GitHub

@cyanheads/faostat-mcp-server

Global food & agriculture statistics from the UN FAOSTAT bulk-download corpus, served from a local SQLite mirror with a DataCanvas SQL surface, over MCP. STDIO & Streamable HTTP.

7 Tools • 0 Resources • 0 Prompts

MCP SDK TypeScript

Public Hosted Server: https://faostat.caseyjhand.com/mcp

Overview

Global food and agriculture statistics from the UN FAOSTAT bulk-download corpus — crop and livestock production, agricultural trade, food balances, food security and nutrition, land use, fertilizer use, and agrifood-systems emissions for 245+ countries and territories from 1961 to the present. Discover a domain, resolve area/item/element codes, then query the cube; large or merged result sets spill to a DataCanvas SQL surface for GROUP BY, ranking, and time-series analysis. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`faostat_list_domains`	Discover FAOSTAT statistical domains with codes, descriptions, last-update date, upstream row count, and local index status. The entry point — every query keys on a domain code.
`faostat_resolve_codes`	Resolve human terms to the opaque integer codes a query needs (areas, items, elements), flagging each area as a country or an aggregate region.
`faostat_query_observations`	Query a domain's cube by area(s), item(s), element(s), and year range. Inline preview for small results; large sets spill to a DataCanvas table.
`faostat_commodity_profile`	Workflow: assemble top producers, the production trend, and trade flows for one commodity from the production and trade domains in a single call.
`faostat_dataframe_query`	Run a read-only SQL `SELECT` against the canvas tables staged by the analytical tools.
`faostat_dataframe_describe`	List the canvas tables staged this session, each with provenance, row count, and column schema.
`faostat_dataframe_drop`	Drop one staged canvas table before its 2-hour TTL. Opt-in — callable only with `FAOSTAT_DATAFRAME_DROP_ENABLED=true`.

Capability reference

`faostat_list_domains` _tool

Full FAOSTAT catalog (~69 domains) read live from the bulk manifest, annotated with local mirror status
code for an exact domain lookup; topic substring filter over code/name/topic; indexed_only to list only domains queryable from the local mirror
offset + limit (max 200, default 20) page the catalog — response reports totalMatches, truncated, and nextOffset
Each entry reports indexed / index_ready flags, local row count, and last completed sync

`faostat_resolve_codes` _tool

FTS5 full-text query, substring name_contains, or exact code lookup within a dimension: area, item, or element
Item/element matches are scoped to codes present in the given domain's cube; area codes are shared across domains
Every area match is flagged country or aggregate (codes ≥ 5000, plus curated sub-threshold roll-ups such as China=351)
limit (max 200, default 50) + offset page the match set
Typed errors: unknown_domain, index_not_ready, query_timeout

`faostat_query_observations` _tool

Filters by area_codes / item_codes / element_codes and an inclusive year_start / year_end range
Aggregate regions excluded by default (include_aggregates: false); explicit area_codes bypass the exclusion
limit caps the inline page (default 200, max 1000); a match that exceeds it spills in full to a DataCanvas table (50,000-row staging cap) — faostat_dataframe_describe for its columns, then SQL via faostat_dataframe_query
Every row carries its data-quality flag (A/E/I/B/M/T/X, others per domain) — never dropped
Typed errors: domain_not_indexed, index_not_ready, canvas_disabled, canvas_not_found, invalid_year_range, query_timeout

`faostat_commodity_profile` _tool

Resolves item_query to up to 5 item codes, then ranks top producers/exporters/importers and returns an annual production trend in one call
Rankings are per-country sums grouped by unit, each country at its own latest reporting year; countries only (aggregates excluded)
Returns a partial, production-only profile with a notice — rather than failing — when the trade domain (TCL) isn't indexed or still syncing
top_n caps each ranked list (max 50); when the merged observation set is too large to inline it spills to a DataCanvas table — faostat_dataframe_describe for its columns, then faostat_dataframe_query for further SQL
Every staging outcome is stated in the notice: the staged table, a set that fit inline, a staging failure, or a disabled canvas
Typed errors: no_match, domain_not_indexed, index_not_ready, invalid_year_range, canvas_not_found, query_timeout

`faostat_dataframe_query` _tool

Single-statement read-only SELECT over staged faostat_xxxxxxxx tables — joins, aggregates, window functions, and CTEs all work
Writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions, and system catalogs (information_schema, sqlite_master, duckdb_*) are rejected
row_limit caps the response (default 1000, max 10000); truncated means more rows exist, with no exact total computed on this path
Typed errors: canvas_disabled, canvas_not_found, missing_table, system_catalog_access, invalid_sql

`faostat_dataframe_describe` _tool

Lists staged tables with source tool, query params, row count, column schema, and creation/expiry (2-hour sliding TTL)
name describes one table outright; otherwise offset + limit (max 100, default 20) page the listing newest-first
Typed errors: canvas_disabled, canvas_not_found, missing_table

`faostat_dataframe_drop` _tool

Opt-in: registered disabled — listed on the landing page with its enable hint, absent from tools/list — unless FAOSTAT_DATAFRAME_DROP_ENABLED=true
Drops one staged faostat_xxxxxxxx table and its provenance from the session canvas, or from the canvas a canvas_id names
Idempotent: a name not staged on that canvas returns dropped: false with a notice and changes nothing
Typed errors: canvas_disabled, canvas_not_found

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

FAOSTAT-specific:

Persistent local SQLite mirror of the FAOSTAT bulk corpus via the framework MirrorService, with FTS5 over the dimension labels driving code resolution
Streaming bulk-ZIP ingester — skips domains whose upstream update date hasn't advanced, and stream-parses the normalized CSV into SQLite without materializing the full file in memory
Config-driven domain selection (FAOSTAT_DOMAINS) — the indexed set can grow without code changes, and the full catalog stays browsable regardless
DataCanvas SQL surface (DuckDB) for GROUP BY, ranking, and time-series analysis over spilled result sets

Agent-friendly output:

Country-vs-aggregate classification on every area, with aggregates excluded from sums by default — guards against double-counting World/continent rows with their member countries
Data-quality provenance — every observation carries its FAOSTAT flag (A/E/I/B/M/T/X, others per domain), never dropped from output
Graceful partial results — faostat_commodity_profile returns a production-only profile with a notice, rather than failing, when the trade domain isn't indexed
Typed error contracts — index_not_ready, domain_not_indexed, canvas_disabled, and others each carry a concrete recovery hint

Getting started

Public Hosted Instance

A public instance is available at https://faostat.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "faostat-mcp-server": {
      "type": "streamable-http",
      "url": "https://faostat.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. The server runs entirely on a local mirror, so build the mirror once before querying.

json

{
  "mcpServers": {
    "faostat-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/faostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "faostat-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/faostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "faostat-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "faostat-mirror:/usr/src/app/.faostat-mirror",
        "ghcr.io/cyanheads/faostat-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

No API key is required — the FAOSTAT bulk-download service is public and keyless.

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
Disk for the local mirror. The default domain set (QCL,TCL,FBS,FS,RL,GLE,RFN,QV, ∼37M rows) needs a few GB; TCL (∼17M rows) dominates and can be dropped from FAOSTAT_DOMAINS on a constrained host.

Installation

Clone the repository:

git clone https://github.com/cyanheads/faostat-mcp-server.git

Navigate into the directory:

cd faostat-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env to override the default domain set, mirror path, or refresh cron

Building the mirror

The corpus is not bundled. Before the data tools can answer queries, sync the selected domains into the local mirror:

bun run mirror:init      # one-time bootstrap — downloads and indexes the FAOSTAT_DOMAINS set
bun run mirror:refresh   # re-sync domains whose upstream update date has advanced; build missing planner statistics
bun run mirror:verify    # report sync status, local row counts, and sample reads

mirror:init is idempotent and resumable per domain — re-running after an interrupt re-streams only the unfinished domain ZIP. FAOSTAT_DOMAINS selects which domains are indexed; everything else in the catalog shows in faostat_list_domains with indexed: false until added and re-synced. On HTTP transport, set FAOSTAT_REFRESH_CRON to refresh in-process on a schedule; on stdio, run mirror:refresh out-of-band. The read tools return index_not_ready until the first sync completes.

mirror:refresh also builds query-planner statistics (ANALYZE) for any selected domain that has none, even when its data is unchanged upstream — a mirror synced by an older release, or one whose last build failed. Otherwise the server builds them itself, in the background on a worker thread, the first time a data read touches that domain, and keeps answering meanwhile.

Configuration

Variable	Description	Default
`FAOSTAT_DOMAINS`	Comma-separated FAOSTAT domain codes to index into the local mirror. Domains outside this set appear in `faostat_list_domains` but are not queryable until added and re-synced.	`QCL,TCL,FBS,FS,RL,GLE,RFN,QV`
`FAOSTAT_MIRROR_PATH`	Directory holding the per-domain SQLite stores and the shared dimension database. Created if absent.	`./.faostat-mirror`
`FAOSTAT_BULK_BASE_URL`	FAOSTAT bulk-download service base URL (manifest + per-domain ZIPs).	`https://bulks-faostat.fao.org/production`
`FAOSTAT_REFRESH_CRON`	Cron for the in-process incremental refresh (HTTP transport only). Omit to disable and run `mirror:refresh` out-of-band.	—
`CANVAS_PROVIDER_TYPE`	DataCanvas engine. `duckdb` enables the SQL surface; set `none` to disable analytical staging (the `dataframe_*` tools then report `canvas_disabled` and large queries refuse to spill).	`duckdb`
`FAOSTAT_DATAFRAME_DROP_ENABLED`	Set `true` to make `faostat_dataframe_drop` callable. Off, the tool is registered disabled: absent from `tools/list`, shown on the landing page with this hint.	`false`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_SESSION_MODE`	HTTP session mode: `stateless`, `stateful`, or `auto` (resolves to `stateful`). The server declares `stateless` in `src/index.ts` — no tool asks the caller for input mid-handler — and setting this overrides that declaration.	`stateless`
`MCP_HTTP_PORT`	Port for the HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest suite under Bun, then under Node
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t faostat-mcp-server .
docker run --rm -p 3010:3010 -v faostat-mirror:/usr/src/app/.faostat-mirror faostat-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/faostat-mcp-server. A dedicated dependency stage installs the production tree for the target platform (DuckDB's prebuilt native binding included), so the slim runtime image carries no build toolchain and a multi-arch build never runs Bun under emulation. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. Mount a volume at the mirror path to persist the corpus across container recreations, and bootstrap it inside the container:

docker exec <container> bun run mirror:init      # one-time bootstrap
docker exec <container> bun run mirror:verify    # sync status + sample reads
docker exec <container> bun run mirror:refresh   # re-sync updated domains; build missing planner statistics

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers the seven tools (`faostat_dataframe_drop` behind its opt-in flag), wires the mirror and canvas in `setup()`, schedules the HTTP refresh.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools/definitions`	Tool definitions (`*.tool.ts`).
`src/services/faostat-mirror`	The bulk-download mirror service — manifest discovery, streaming ZIP ingester, CSV parsing, dimension store, SQLite-backed `MirrorService` wiring, and the two-worker read pool (`read-pool.ts`, `read-worker.ts`) that runs cube reads and statistics builds off the main thread.
`src/services/canvas-accessor.ts`, `canvas-staging.ts`	DataCanvas accessor and the spill/query/describe/drop staging layer.
`scripts/faostat-mirror-*.ts`	`mirror:init` / `mirror:refresh` / `mirror:verify` CLIs.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools in the createApp() array in src/index.ts
Wrap external data: validate raw → normalize to domain type → return output schema; never fabricate missing fields, and carry the data-quality flag through

Data attribution

Data is sourced from FAOSTAT, the statistics division of the Food and Agriculture Organization of the United Nations (FAO). FAOSTAT data is published under CC BY-4.0; cite FAO as the source in downstream use. This project is not affiliated with or endorsed by the FAO.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (6)

faostat_list_domainsfaostat_resolve_codesfaostat_query_observationsfaostat_commodity_profilefaostat_dataframe_queryfaostat_dataframe_describe

Configuration

Environment variables

FAOSTAT_DOMAINSdefault QCL,TCL,FBS,FS,RL,GLE,RFN,QV

Comma-separated FAOSTAT domain codes to index into the local mirror.

FAOSTAT_MIRROR_PATHdefault ./.faostat-mirror

Directory holding the per-domain SQLite mirror databases and the shared dimension database.

FAOSTAT_BULK_BASE_URLdefault https://bulks-faostat.fao.org/production

FAOSTAT bulk-download service base URL (manifest + per-domain ZIPs).

CANVAS_PROVIDER_TYPEdefault duckdb

Set to 'duckdb' to enable the DataCanvas SQL surface (default), or 'none' to disable analytical staging.

FAOSTAT_DATAFRAME_DROP_ENABLEDdefault false

Set to 'true' to make faostat_dataframe_drop callable, so a staged table can be dropped before its 2-hour TTL. Off by default: the tool is registered disabled.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

FAOSTAT_REFRESH_CRON

Cron expression for the in-process incremental mirror refresh (HTTP transport only). Omit to disable.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "faostat-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/faostat-mcp-server@0.3.0"
      ],
      "env": {
        "FAOSTAT_DOMAINS": "QCL,TCL,FBS,FS,RL,GLE,RFN,QV",
        "FAOSTAT_MIRROR_PATH": "./.faostat-mirror",
        "FAOSTAT_BULK_BASE_URL": "https://bulks-faostat.fao.org/production",
        "CANVAS_PROVIDER_TYPE": "duckdb",
        "FAOSTAT_DATAFRAME_DROP_ENABLED": "false",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

io.github.cyanheads/faostat-mcp-server (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

faostat_list_domains

faostat_resolve_codes

faostat_query_observations

faostat_commodity_profile

faostat_dataframe_query

faostat_dataframe_describe

@cyanheads/faostat-mcp-server

Overview

Tools

Capability reference

faostat_list_domains tool

faostat_resolve_codes tool

faostat_query_observations tool

faostat_commodity_profile tool

faostat_dataframe_query tool

faostat_dataframe_describe tool

faostat_dataframe_drop tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Building the mirror

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Data attribution

Contributing

License

Install

Configuration

Related servers

`faostat_list_domains` _tool

`faostat_resolve_codes` _tool

`faostat_query_observations` _tool

`faostat_commodity_profile` _tool

`faostat_dataframe_query` _tool

`faostat_dataframe_describe` _tool

`faostat_dataframe_drop` _tool