FAOSTAT MCP

FAOSTAT MCP Server

Query UN food and agriculture statistics with AI — powered by the Model Context Protocol

An MCP (Model Context Protocol) server that exposes the full FAOSTAT API as tools for AI assistants. Connect any MCP-compatible client — Claude, Cursor, Windsurf, Zed, or your own agent — to the world's most comprehensive database of food, agriculture, fisheries, forestry, and nutrition statistics, covering 245 countries and territories from the United Nations Food and Agriculture Organization (FAO).

Keywords: FAOSTAT, MCP server, Model Context Protocol, AI agriculture data, FAO statistics, food security AI, agricultural data Python, UN data, crop production statistics, Claude, Cursor, Windsurf

Why Use This?

Researchers, data journalists, policy analysts, and developers can ask natural-language questions and get answers directly from FAOSTAT — without writing a single API call. Your AI assistant handles domain discovery, filtering, and interpretation automatically.

Who is this for?

• Agricultural economists and food security researchers
• Journalists and policy analysts working with FAO data
• Developers building AI pipelines on top of FAOSTAT
• Anyone who wants to explore crop, trade, nutrition, or emissions data conversationally

What is FAOSTAT?

FAOSTAT is the statistical database of the United Nations Food and Agriculture Organization (FAO). It is the world's most comprehensive freely available source of data on food and agriculture, covering:

• Crop and livestock production — yields, harvested area, and quantities for hundreds of commodities
• Trade — import/export volumes and values between countries
• Food security — prevalence of undernourishment, dietary energy supply, and access indicators
• Emissions — greenhouse gas emissions from agriculture, land use, and food systems
• Forestry and fisheries — production and trade data
• Prices, inputs, and population — producer prices, fertilizer use, and demographic context

Data spans from 1961 to the present, across 245 countries and territories, in multiple languages.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants call external tools at runtime. This server registers all FAOSTAT API endpoints as discoverable tools — your AI assistant automatically selects and chains the right calls when you ask a question.

Features

• 23 MCP tools covering every FAOSTAT endpoint (data, metadata, rankings, bulk downloads, reports)
• 245 countries and territories across dozens of domains: crops, livestock, trade, food security, emissions, forestry, fisheries, and more
• Built-in rate limiting (2 req/s) — safe for the FAOSTAT production API out of the box
• Auto-retry with exponential backoff on transient network errors
• Rich tool descriptions so the AI knows exactly when and how to call each tool
• 3-tier hybrid caching — in-memory (20 min) → SQLite disk (24 h, cross-session) → Redis (optional, 30 min)
• Zero-config auth via faostat_setup — store credentials once, never touch a config file again
• Disambiguation via faostat_search_codes — agents ask before guessing ambiguous codes
• Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP-compatible client

Quick Start

Prerequisites

• Python 3.10+
• Any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Zed, or a custom agent)

Option A — Install via MCP Registry (recommended)

Listed on the official MCP Registry — discoverable directly from Claude Desktop, Cursor, and any MCP-compatible client.

# Install with pip or uvx (no virtual env needed):

pip install faostat-mcp uvx faostat-mcp

Updating: uvx faostat-mcp picks up new releases when your AI client restarts the server; if you still see an old version, run uvx faostat-mcp@latest once. pip and uv tool install don't upgrade on their own: run pip install -U faostat-mcp or uv tool upgrade faostat-mcp, then restart your client. The server also checks PyPI once per session and logs a notice to stderr when a newer version exists (opt out with FAOSTAT_NO_UPDATE_CHECK=1).

Option B — Install from source

git clone https://github.com/berba-q/faostat-mcp.git

cd faostat-mcp pip install -e .

Configure credentials

Easiest — use the `faostat_setup` tool (no config files needed):

Once the server is running and connected to your AI client, ask your assistant:

"Call faostat_setup with my FAOSTAT username and password."

The tool validates your credentials against the API, then stores them securely in your system keychain (macOS/Windows) or ~/.config/faostat-mcp/credentials.json (Linux/Docker). All subsequent sessions authenticate automatically — no env vars or .env file required.

Alternative — environment variables (CI/CD, Docker, advanced):

cp .env.example .env

Edit .env:

FAOSTAT_USERNAME=your_email ← recommended: tokens refresh automatically

FAOSTAT_PASSWORD=your_password

FAOSTAT_API_TOKEN=your_token_here ← alternative: expires after 1 hour

Register for a free FAOSTAT API account at the FAOSTAT Developer Portal.

Optional — Redis caching (multi-user / high-volume deployments)

The server works without Redis (SQLite disk cache is used instead). For shared or high-volume setups, launch Redis via Docker:

docker run -p 6379:6379 -it redis/redis-stack:latest

Then set REDIS_HOST_IP_ADDRESS, REDIS_HOST_PORT_NUMBER, and REDIS_DATABASE in .env.

Running the Server

Development mode (interactive MCP Inspector UI)

mcp dev faostat_mcp/server.py

Opens a browser UI at http://localhost:5173 where you can browse and test all 23 tools interactively.

Production mode (stdio transport, for Claude Desktop)

python -m faostat_mcp.server

or, using the installed script:

faostat-mcp

Caching

The server uses a 3-tier cache to minimise redundant API calls. FAOSTAT data updates at most daily, so most repeated queries are served instantly.

Cache lookup order: memory → disk → Redis → API call. A disk or Redis hit promotes the value to memory for the rest of the session.

To disable the disk cache (e.g. on a read-only filesystem), set FAOSTAT_DISK_CACHE=false.

MCP Client Integration

The server speaks standard MCP over stdio, so it works with any compatible client.

Recommended config (PyPI install)

{

"mcpServers": { "faostat": { "command": "uvx", "args": ["faostat-mcp"] } } }

Dev / source config

{

"mcpServers": { "faostat": { "command": "python", "args": ["-m", "faostat_mcp.server"], "cwd": "/path/to/faostat-mcp", "env": { "FAOSTAT_USERNAME": "your_email", "FAOSTAT_PASSWORD": "your_password" } } } }

Claude Desktop

Add one of the blocks above to:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop — faostat will appear in the tools panel.

Cursor

Add the block to .cursor/mcp.json in your project root, or to your global Cursor MCP settings. See the Cursor MCP docs for details.

Windsurf / Zed / other clients

Any client that supports MCP stdio servers accepts the same config shape. Consult your client's documentation for the config file location.

Example Queries

Once connected, ask your AI assistant questions like:

Your AI assistant will automatically:

1. Call faostat_list_groups or faostat_groups_and_domains to find the right domain
2. Call faostat_search_codes to look up a code by name — if multiple codes match (e.g. "production" matches both *Production* and *Gross Production Index*), the assistant pauses and asks you to choose before proceeding

• Regions and indicators are checked with faostat_resolve_name — if no matching FAOSTAT definition is found for your request (e.g. *"Global South"*), the assistant tells you so and offers the FAO-defined alternatives (e.g. *"West Africa"* → *Western Africa*) instead of inventing one

1. Call faostat_get_data or faostat_get_rankings with the confirmed codes
2. Interpret and summarize the results in plain language

Available MCP Tools

Discovery & Metadata

Data Retrieval

|