# io.github.cyanheads/faostat-mcp-server (remote · faostat.caseyjhand.com)

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

- Trust score: 68/100 (medium)
- Change this week: +6
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `faostat.caseyjhand.com`: 68/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat.md), [page](https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat)
- npm · `@cyanheads/faostat-mcp-server`: 35/100, [markdown](https://verifymcp.io/servers/cyanheads-faostat-mcp-server/cyanheads-faostat-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-faostat-mcp-server/cyanheads-faostat-mcp-server)

## Channel facts

- Endpoint: `https://faostat.caseyjhand.com/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.2.2`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 66/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 6 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC is configured correctly; the domain's records validate against the full chain to the root.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 61/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2480 tokens (~413/item across 6 items; 6 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http cyanheads-faostat-mcp-server https://faostat.caseyjhand.com/mcp
```

### Codex

```toml
[mcp_servers.cyanheads-faostat-mcp-server]
url = "https://faostat.caseyjhand.com/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-faostat-mcp-server": {
      "type": "remote",
      "url": "https://faostat.caseyjhand.com/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-faostat-mcp-server --url https://faostat.caseyjhand.com/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  cyanheads-faostat-mcp-server:
    url: "https://faostat.caseyjhand.com/mcp"
```

### Other

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

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-01 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 66, +2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 64, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 64, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 63, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 62, +1)

- [security] Tool “faostat_commodity_profile” rewrote its description, which is the text the model reads
- [functional regression] Schema quality: 355 → 413
- [functional improvement] Stability: unverified → 0.03
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server
- [functional] Server version: 0.2.1 → 0.2.2
- [functional] Server version: 0.1.11 → 0.2.1
- [cosmetic] “faostat_query_observations” reworded the description of “limit”
- [cosmetic] “faostat_commodity_profile” reworded the description of “item_query”

### 2026-07-26 (score 61)

First indexed and scored.

## MCP tools (6)

### `faostat_list_domains` (~392 tokens)

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.

Input parameters:

- `code` (string): Exact domain code lookup (e.g. "RL"), case-insensitive. Returns that one domain's full record on a single page. Takes precedence over `topic` / `indexed_only` when provided.
- `indexed_only` (boolean): When true, return only domains indexed in the local mirror (queryable now).
- `limit` (integer): Maximum domains to return on this page (max 200 — above the catalog size, so raise it to fetch everything at once). Domain descriptions are long; the default keeps a browse call small.
- `offset` (integer): Zero-based pagination offset into the matching domains (code-sorted). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (al…
- `topic` (string): Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog.

Output parameters:

- `domains` (array): Matching domains, sorted by code.
- `indexedCount` (number): Domains currently indexed in the local mirror.
- `nextOffset` (integer): 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.
- `notice` (string): Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet.
- `totalCount` (number): Total domains in the FAOSTAT catalog, independent of any filter.
- `totalMatches` (number): Domains matching the current filters, before the page limit is applied.
- `truncated` (boolean): True when more matches remain beyond the returned page — fetch them with nextOffset.

### `faostat_resolve_codes` (~475 tokens)

faostat-mcp-server: 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.

Input parameters:

- `code` (integer): Exact code lookup. Takes precedence over `query`/`name_contains` when provided.
- `dimension` (string, required): Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics).
- `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.
- `limit` (integer): Maximum matches to return (max 200).
- `name_contains` (string): Case-insensitive substring filter over the label. Used only when `query` is omitted.
- `offset` (integer): Zero-based pagination offset into the match set. When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page).
- `query` (string): Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked.

Output parameters:

- `dimension` (string): The dimension resolved.
- `domain` (string): The domain code echoed back.
- `matches` (array): Matching codes, relevance-ranked for query mode, else by code.
- `nextOffset` (integer): 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.
- `notice` (string): Guidance when nothing matched, more pages remain, or the dimension is not yet indexed.
- `totalMatches` (number): Total matches in this domain before the result cap.
- `truncated` (boolean): True when more matches remain beyond the returned page — fetch them with nextOffset.

### `faostat_query_observations` (~561 tokens)

faostat-mcp-server: 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) for GROUP BY / ranking / time-series analysis via faostat_dataframe_query. 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.

Input parameters:

- `area_codes` (array): Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim.
- `canvas_id` (string): Canvas ID from a prior call to stage onto. Omit to start a fresh canvas (a new id is returned).
- `domain` (string, required): FAOSTAT domain code (e.g. "QCL"). Must be indexed locally.
- `element_codes` (array): Element codes from faostat_resolve_codes (e.g. 5510 Production).
- `include_aggregates` (boolean): When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping ro…
- `item_codes` (array): Item codes from faostat_resolve_codes.
- `limit` (integer): Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas ta…
- `year_end` (integer): Inclusive end year (e.g. 2022).
- `year_start` (integer): Inclusive start year (e.g. 2000).

Output parameters:

- `canvas_id` (string): Canvas ID holding the staged result — pass to faostat_dataframe_query / _describe.
- `domain` (string): The domain code echoed back.
- `notice` (string): Guidance on empty results, aggregate exclusion, or how to reach the spilled set.
- `observations` (array): Inline observations (preview when the full set spilled to a canvas table).
- `spilled` (boolean): True when the full result was staged on a DataCanvas table.
- `staged_row_count` (number): 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.
- `table_name` (string): Canvas table name holding the full result set (present when spilled).
- `totalCount` (number): 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 (trunca…
- `truncated` (boolean): 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.

### `faostat_commodity_profile` (~326 tokens)

faostat-mcp-server: 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). When a required domain is not indexed locally, returns a partial profile with a notice naming the gap rather than failing. The full merged observation set spills to a DataCanvas table for deeper SQL via faostat_dataframe_query.

Input parameters:

- `canvas_id` (string): Canvas ID from a prior call to stage onto. Omit to start a fresh canvas.
- `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 respon…
- `top_n` (integer): Number of top producers / exporters / importers to return. Max 50.
- `year_end` (integer): Inclusive end year for the trend (e.g. 2022).
- `year_start` (integer): Inclusive start year for the trend (e.g. 1990).

Output parameters:

- `canvas_id` (string): Canvas ID holding the merged set — pass to faostat_dataframe_query / _describe.
- `item_query` (string): The commodity query echoed back.
- `itemsTruncated` (boolean): True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few.
- `notice` (string): Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context.
- `production_trend` (array): The annual production series for the resolved commodity, summed over countries and items per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected b…
- `resolvedItemCodes` (array): Item codes the commodity query resolved to.
- `resolvedItemMatches` (number): Total items the commodity query matched in QCL, before the 5-item profile cap.
- `resolved_items` (array): Commodities the query resolved to (the profile aggregates across all of them).
- `spilled` (boolean): True when the merged observation set was staged on a canvas table.
- `staged_row_count` (number): Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.
- `table_name` (string): 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 t…
- `top_exporters` (array): Top exporters by summed export quantity (empty when trade is not indexed).
- `top_importers` (array): Top importers by summed import quantity (empty when trade is not indexed).
- `top_producers` (array): Top producers by summed production (countries only).
- `trend_points` (number): Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.
- `truncated` (boolean): 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. T…

### `faostat_dataframe_query` (~346 tokens)

faostat-mcp-server: 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.

Input parameters:

- `canvas_id` (string): Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to query the tables staged in this session (the common case).
- `row_limit` (integer): Hard cap on rows in the response. Default 1000, max 10000.
- `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. CAST(value AS DOUBLE) for arithmetic.

Output parameters:

- `columns` (array): Column names in projection order.
- `notice` (string): Guidance when the query returned no rows or when results were capped.
- `row_count` (number): 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…
- `rows` (array): Materialized result rows, bounded by row_limit.
- `truncated` (boolean): 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.

### `faostat_dataframe_describe` (~153 tokens)

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.

Input parameters:

- `canvas_id` (string): Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to list the tables staged in this session (the common case).
- `name` (string): Optional table name (faostat_xxxxxxxx) to describe a single staged table. Omit to list all.

Output parameters:

- `tables` (array): Active staged tables for this session, newest first. Empty when none are staged.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 67
- 2026-08-01: 67
- 2026-07-31: 66
- 2026-07-30: 64
- 2026-07-29: 64
- 2026-07-28: 63
- 2026-07-27: 62
- 2026-07-26: 61

## Links

- Remote endpoint: https://faostat.caseyjhand.com/mcp
- Repository: https://github.com/cyanheads/faostat-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat/changelog.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-faostat-mcp-server/faostat