faostat-mcp

<!-- mcp-name: io.github.berba-q/faostat-mcp -->
# FAOSTAT MCP Server

> Query UN food and agriculture statistics with AI — powered by the [Model Context Protocol](https://modelcontextprotocol.io)

[![Version](https://img.shields.io/github/v/release/berba-q/faostat-mcp)](https://github.com/berba-q/faostat-mcp/releases/latest)
[![PyPI](https://img.shields.io/pypi/v/faostat-mcp)](https://pypi.org/project/faostat-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-orange)](https://registry.modelcontextprotocol.io/servers/io.github.berba-q/faostat-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An MCP (Model Context Protocol) server that exposes the full [FAOSTAT API](https://www.fao.org/faostat/en/#developer-portal) 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](https://www.fao.org/faostat/en/) 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](https://modelcontextprotocol.io) 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](https://registry.modelcontextprotocol.io/servers/io.github.berba-q/faostat-mcp) — discoverable directly from Claude Desktop, Cursor, and any MCP-compatible client.

```bash
# 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

```bash
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):**

```bash
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](https://www.fao.org/faostat/en/#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:

```bash
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)

```bash
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)

```bash
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.

| Tier | TTL | Scope | Notes |
|------|-----|-------|-------|
| In-memory | 20 min | Current session | Fastest; reset on server restart |
| SQLite disk | 24 h | Cross-session | `~/.cache/faostat-mcp/cache.db`; no extra infra |
| Redis | 30 min | Multi-user shared | Optional; set `REDIS_*` env vars to enable |

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)

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

### Dev / source config

```json
{
  "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](https://docs.cursor.com/context/model-context-protocol) 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:

| Domain | Example Question |
|--------|-----------------|
| Crop production | *"What were the top 10 wheat-producing countries in 2022?"* |
| Food security | *"Show me food security indicators for Ethiopia from 2015 to 2020"* |
| Trade | *"Which countries are most dependent on food imports?"* |
| Yield comparison | *"Compare maize yields between the USA and Brazil over the last decade"* |
| Emissions | *"What are greenhouse gas emissions from agriculture in Sub-Saharan Africa?"* |
| Discovery | *"What agricultural datasets does FAOSTAT have for trade?"* |

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 f