Faostat Mcp

FAOSTAT MCP 服务

借助 AI 查询联合国粮食和农业统计数据 — 由 Model Context Protocol 提供支持

一个 MCP（Model Context Protocol）服务，可将完整的 FAOSTAT API 作为工具提供给 AI 助手。连接任何兼容 MCP 的客户端 — Claude、Cursor、Windsurf、Zed 或你自己的 Agent — 即可访问全球最全面的粮食、农业、渔业、林业和营养统计数据库，数据涵盖联合国粮食及农业组织（FAO）的 245 个国家和地区。

关键词： FAOSTAT、MCP 服务、Model Context Protocol、AI 农业数据、FAO 统计数据、粮食安全 AI、农业数据 Python、联合国数据、作物产量统计、Claude、Cursor、Windsurf

---

为什么要使用它？

研究人员、数据记者、政策分析师和开发者可以用自然语言提问，直接获取 FAOSTAT 的答案 — 无需编写任何 API 调用。你的 AI 助手会自动处理领域发现、筛选和解读。

适用对象？

• 农业经济学家和粮食安全研究人员
• 使用 FAO 数据的记者和政策分析师
• 基于 FAOSTAT 构建 AI 流程的开发者
• 希望通过对话探索作物、贸易、营养或排放数据的任何人

---

什么是 FAOSTAT？

FAOSTAT 是联合国粮食及农业组织（FAO）的统计数据库。它是全球最全面的免费粮食和农业数据来源，涵盖：

• 作物和畜牧业生产 — 数百种商品的产量、收获面积和数量
• 贸易 — 国家间的进出口数量和价值
• 粮食安全 — 营养不足发生率、膳食能量供应量和获取指标
• 排放 — 农业、土地利用和粮食系统产生的温室气体排放
• 林业和渔业 — 生产和贸易数据
• 价格、投入和人口 — 生产者价格、化肥使用量和人口统计背景信息

数据覆盖 245 个国家和地区，时间跨度从 1961 年至今，并提供多种语言版本。

什么是 MCP？

Model Context Protocol 是一项开放标准，支持 AI 助手在运行时调用外部工具。此服务将所有 FAOSTAT API 端点注册为可发现的工具 — 当你提出问题时，AI 助手会自动选择并串联合适的调用。

---

功能

• 23 个 MCP 工具，涵盖 FAOSTAT 的所有端点（数据、元数据、排名、批量下载、报告）
• 245 个国家和地区，覆盖数十个领域：农作物、畜牧业、贸易、粮食安全、排放、林业、渔业等
• 内置速率限制（2 req/s）——开箱即用，适用于 FAOSTAT 生产 API
• 针对临时网络错误，采用自动重试和指数退避
• 丰富的工具描述，让 AI 准确了解何时以及如何调用每个工具
• 三层混合缓存——内存（20 min）→ SQLite 磁盘（24 h，跨会话）→ Redis（可选，30 min）
• 通过 faostat_setup 免配置身份验证——只需存储一次凭据，无需再修改配置文件
• 通过 faostat_search_codes 消除歧义——Agent 会先询问，再猜测有歧义的代码
• 适用于 Claude Desktop、Claude Code、Cursor、Windsurf、Zed 以及任何兼容 MCP 的客户端

---

快速开始

先决条件

• Python 3.10+
• 任意兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Zed 或自定义 Agent）

选项 A——通过 MCP Registry 安装（推荐）

已收录于官方 MCP Registry——可直接从 Claude Desktop、Cursor 和任何兼容 MCP 的客户端中发现。

# Install with pip or uvx (no virtual env needed):
pip install faostat-mcp
uvx faostat-mcp

**更新：**当 AI 客户端重启服务时，uvx faostat-mcp 会获取新版本；如果仍看到旧版本，请运行一次 uvx faostat-mcp@latest。pip 和 uv tool install 不会自行升级：请运行 pip install -U faostat-mcp 或 uv tool upgrade faostat-mcp，然后重启客户端。服务还会在每个会话中检查一次 PyPI，并在存在更新版本时向 stderr 输出通知（设置 FAOSTAT_NO_UPDATE_CHECK=1 可选择退出）。

选项 B——从源代码安装

git clone https://github.com/berba-q/faostat-mcp.git
cd faostat-mcp
pip install -e .

配置凭据

最简单的方法——使用 faostat_setup 工具（无需配置文件）：

服务运行并连接到 AI 客户端后，请让助手：

“使用我的 FAOSTAT 用户名和密码调用 faostat_setup。”

该工具会通过 API 验证凭据，然后将其安全地存储在系统钥匙串（macOS/Windows）或 ~/.config/faostat-mcp/credentials.json（Linux/Docker）中。之后的所有会话都会自动进行身份验证——无需环境变量或 .env 文件。

替代方案——环境变量（CI/CD、Docker、高级用法）：

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

请在 FAOSTAT Developer Portal 免费注册 FAOSTAT API 账号。

可选——Redis 缓存（多用户／高流量部署）

服务无需 Redis 即可运行（此时会改用 SQLite 磁盘缓存）。对于共享或高流量环境，可通过 Docker 启动 Redis：

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

然后在 .env 中设置 REDIS_HOST_IP_ADDRESS、REDIS_HOST_PORT_NUMBER 和 REDIS_DATABASE。

---

运行服务

开发模式（交互式 MCP Inspector UI）

mcp dev faostat_mcp/server.py

此命令会在 http://localhost:5173 打开浏览器 UI，供你交互式浏览和测试全部 23 个工具。

生产模式（stdio 传输，用于 Claude Desktop）

python -m faostat_mcp.server
# or, using the installed script:
faostat-mcp

---

缓存

服务使用三层缓存，尽可能减少重复的 API 调用。FAOSTAT 数据每天最多更新一次，因此大多数重复查询都能即时返回。

层级	TTL	范围	备注
内存	20 min	当前会话	速度最快；服务重启时重置
SQLite 磁盘	24 h	跨会话	~/.cache/faostat-mcp/cache.db；无需额外基础设施
Redis	30 min	多用户共享	可选；设置 REDIS_* 环境变量以启用

缓存查询顺序：内存 → 磁盘 → Redis → API 调用。命中磁盘或 Redis 后，该值会提升至内存缓存，供本会话后续使用。

如需禁用磁盘缓存（例如在只读文件系统上），请设置 FAOSTAT_DISK_CACHE=false。

---

MCP 客户端集成

服务通过 stdio 使用标准 MCP，因此适用于任何兼容客户端。

推荐配置（通过 PyPI 安装）

{
  "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

将上面的其中一个配置块添加到：

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

重启 Claude Desktop——faostat 将出现在工具面板中。

Cursor

将配置块添加到项目根目录下的 .cursor/mcp.json，或添加到 Cursor 的全局 MCP 设置中。详情请参阅 Cursor MCP 文档。

Windsurf / Zed / 其他客户端

任何支持 MCP stdio 服务的客户端都接受相同的配置格式。请查阅客户端文档，了解配置文件的位置。

---

示例查询

连接后，可以向 AI 助手提出如下问题：

领域	示例问题
作物生产	“2022 年小麦产量排名前 10 的国家有哪些？”
粮食安全	“显示埃塞俄比亚 2015 年至 2020 年的粮食安全指标”
贸易	“哪些国家最依赖粮食进口？”
产量比较	“比较过去 10 年美国和巴西的玉米单产”
排放	“撒哈拉以南非洲的农业温室气体排放情况如何？”
数据发现	“FAOSTAT 有哪些贸易相关的农业数据集？”

AI 助手将自动：

1. 调用 faostat_list_groups 或 faostat_groups_and_domains 来查找合适的领域
2. 调用 faostat_search_codes 按名称查找代码——如果匹配到多个代码（例如，“production”同时匹配 Production 和 Gross Production Index），助手会暂停并询问你选择哪一个，然后再继续
   • 区域和指标会通过 faostat_resolve_name 进行核验——如果请求没有匹配的 FAOSTAT 定义（例如 “Global South”），助手会告知你这一点，并提供 FAO 定义的替代项（例如用 Western Africa 替代 “West Africa”），而不是自行编造
3. 使用已确认的代码调用 faostat_get_data 或 faostat_get_rankings
4. 用通俗易懂的语言解读并总结结果

---

可用的 MCP 工具

发现与元数据

工具	描述
faostat_ping	检查 API 健康状况
faostat_list_groups	列出所有数据组
faostat_groups_and_domains	完整的领域树
faostat_list_domains	列出组内的领域
faostat_get_dimensions	查看领域可用的筛选条件
faostat_get_codes	浏览所有国家／项目／要素筛选代码
faostat_search_codes	按名称搜索代码——有多个代码匹配时返回 requires_confirmation=true，要求 Agent 先询问你再继续
faostat_get_definitions	领域定义
faostat_get_definitions_by_type	按类型查看领域内的定义
faostat_definition_types	所有定义类型
faostat_get_definition_type	某一类型的 FAO 全局定义，无需指定领域（区域／areagroup、国家、指标、项目、单位、标记……），支持 search 和 limit
faostat_resolve_name	根据 FAO 定义核验区域、国家或指标名称——查找不到匹配项时返回 no_matching_definition；定义代码需要通过领域筛选查询
faostat_get_metadata	完整的领域元数据
faostat_get_metadata_print	可打印的元数据

数据获取

工具	描述
faostat_get_data	获取实际统计数据
faostat_get_datasize	获取数据前估算查询结果大小
faostat_get_rankings	国家排名前 N 项
faostat_get_report_data	报告数据
faostat_get_report_headers	报告列标题
faostat_list_bulk_downloads	批量下载文件列表
faostat_list_documents	相关文档

身份验证

工具	说明
faostat_setup	首次设置 — 验证并安全存储凭据；后续会话将自动进行身份验证
faostat_refresh_token	手动刷新 API 访问令牌

---

项目结构

faostat-mcp/
├── pyproject.toml
├── smithery.yaml             ← Smithery MCP registry manifest
├── .env.example
├── mcp_config_example.json   ← AI config snippet
└── faostat_mcp/
    ├── server.py             ← FastMCP server + all 23 tool definitions
    └── client.py             ← HTTP client, rate limiting, 3-tier cache, credential storage

---

重要：筛选代码与显示代码

FAOSTAT API 使用两套不同的代码系统：筛选代码（用于查询参数）和显示代码（显示在响应数据和批量 CSV 中）。调用 faostat_get_data 时，务必使用 faostat_get_codes 返回的筛选代码。

区域、项目和年份代码在两套系统中相同。 只有要素代码不同：

QCL — 作物和畜产品

筛选代码	显示代码	要素
2312	5312	收获面积
2413	5412	单产
2510	5510	产量
2111	5111	库存
2313	5320	生产性动物／屠宰动物

TM — 贸易矩阵

筛选代码	显示代码	要素
2610	—	进口量
2620	—	进口额
2910	—	出口量
2920	—	出口额

FS — 粮食安全

筛选代码	显示代码	要素
6120	—	值
6210	—	置信区间

查询数据前，务必先调用 faostat_get_codes(dimension_id='element', domain_code=...)。 筛选代码因领域而异，无法从显示代码推断得出。

# WRONG — uses display code 5510, returns empty data
faostat_get_data('QCL', area='2', item='515', element='5510', year='2024')

# CORRECT — uses filter code 2510, returns data
faostat_get_data('QCL', area='2', item='515', element='2510', year='2024')

---

限制与说明

• 此服务面向 FAOSTAT 生产环境 API（https://faostatservices.fao.org/api/v1）。
• 速率限制：每秒 2 个请求，通过令牌桶自动执行。
• 响应会缓存在 3 个层级（内存 → SQLite 磁盘 → Redis），以减少 API 调用 — TTL 和大小配置请参阅 .env.example。
• SQLite 磁盘缓存位于 ~/.cache/faostat-mcp/cache.db，默认 TTL 为 24 h，LRU 上限为 1,000 条。设置 FAOSTAT_DISK_CACHE=false 可禁用缓存。
• 对于大型领域（例如贸易矩阵），务必应用区域、项目和年份筛选条件，以控制响应大小。

---

技能

想要使用此服务开展引导式分析工作流？请查看 FAOSTAT Skills — 9 个与平台无关的 AI 技能，适用于国家概况、商品简报、贸易分析、气候评估、数据可视化等场景。支持 Claude Code、OpenAI Codex，以及任何支持 SKILL.md 格式的 AI 助手。

---

相关项目与资源

• FAOSTAT Skills — 基于此 MCP 服务构建的分析技能
• Model Context Protocol — 为此服务提供支持的开放标准
• FAOSTAT — 联合国粮农组织官方统计门户
• FAOSTAT API 文档 — 开发者参考资料
• Claude Desktop — 此服务支持的 AI 助手之一
• Cursor — 支持 MCP 的 AI 代码编辑器
• Windsurf — 支持 MCP 的 AI IDE

---

贡献者

感谢所有为此项目作出贡献的人。

贡献者	贡献内容
berba-q	项目作者 — API 客户端、MCP 工具层、响应格式化
Tohokantche	混合缓存 — 内存（dict + min-heap TTL）和 Redis 层，并支持优雅降级

欢迎贡献 — 贡献指南请参阅 CONTRIBUTING.md。

---

引用

如果您在学术工作或研究中使用此工具，请引用：

纯文本：

Obli-Laryea, G., & Contributors. (2026). FAOSTAT MCP Server: AI-assisted access to FAOSTAT (v1.2.2) [Computer software]. https://github.com/berba-q/faostat-mcp

BibTeX：

@software{faostat_mcp,
  author  = {Obli-Laryea, Griffiths and {Contributors}},
  title   = {FAOSTAT MCP Server: AI-assisted access to UN food and agriculture statistics},
  year    = {2026},
  url     = {https://github.com/berba-q/faostat-mcp},
  version = {1.2.2}
}

作者完整名单请参见贡献者部分。

引用底层 FAOSTAT 数据时，请使用 FAO 推荐的格式，并注明具体领域：

FAO, {year}. FAOSTAT: {Domain Name}, http://www.fao.org/faostat/en/#data/{domain_code}

例如：

FAO, 2026. FAOSTAT: Crops and Livestock Products, http://www.fao.org/faostat/en/#data/QCL

FAO, 2026. FAOSTAT: Emissions Totals, http://www.fao.org/faostat/en/#data/GT

---

更新日志

完整的更新历史请参见 CHANGELOG.md，该文件根据 conventional commits 自动生成。

---

GitHub 主题

如果您复刻或为此仓库点星，建议使用以下主题：mcp、faostat、model-context-protocol、ai-tools、agriculture、food-security、fao、un-data、python、llm、unfao、undata

更精简的工具响应

数据、排名和全局定义默认使用 response_format="compact"（列名仅显示一次，后接行数组）。使用 response_format="objects" 可采用之前的逐行对象格式；数据和排名也可使用 "csv"。在数据查询中选择 fields 时，请保留用于解释数值的单位。搜索结果默认返回 25 条匹配项；如果 _truncated 为 true，请缩小查询范围。

已知领域时，请直接使用 faostat_search_codes。全局名称解析器会返回 definition_code，它不一定是查询筛选代码。no_matching_definition 结果描述的是此次查找，而不是 FAO 的全部术语。代码浏览、搜索和验证共用一个缓存表；重复的数据查询会在不同格式、字段选择和行数限制之间复用原始响应。