Faostat MCP

FAOSTAT MCP服务器

使用人工智能查询联合国粮食和农业统计数据——由 模型上下文协议

](https://github.com/berba-q/faostat-mcp/releases/latest)     

一个MCP（模型上下文协议）服务器，它公开了完整的 API福斯特 作为人工智能助手的工具。将任何兼容MCP的客户端（Claude、Cursor、Windsurf、Zed或您自己的代理）连接到世界上最全面的粮食、农业、渔业、林业和营养统计数据库，该数据库涵盖了联合国粮食及农业组织（FAO）的245个国家和地区。

关键词： FAOSTAT、MCP服务器、模型上下文协议、人工智能农业数据、粮农组织统计、粮食安全人工智能、农业数据Python、联合国数据、作物生产统计、Claude、Cursor、Windsurf

______________________________________________________________________

为什么使用这个？

研究人员、数据记者、政策分析师和开发人员可以提出自然语言问题，并直接从FAOSTAT获得答案，而无需编写一个API调用。您的AI助手自动处理域发现、过滤和解释。

这是给谁的？

• 农业经济学家和粮食安全研究人员
• 使用粮农组织数据的记者和政策分析师
• 开发人员在FAOSTAT上构建AI管道
• 任何想通过对话探索作物、贸易、营养或排放数据的人

______________________________________________________________________

什么是FAOSTAT？

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

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

数据涵盖了从1961年到现在的245个国家和地区，使用多种语言。

什么是MCP？

这 模型上下文协议 是一个开放标准，允许AI助手在运行时调用外部工具。该服务器将所有FAOSTAT API端点注册为可发现工具-当您提问时，您的人工智能助手会自动选择并链接正确的调用。

______________________________________________________________________

特性

• 21个MCP工具 涵盖FAOSTAT的每个端点（数据、元数据、排名、批量下载、报告）
• 245个国家和地区 跨越数十个领域：作物、牲畜、贸易、粮食安全、排放、林业、渔业等
• 内建 速率限制 （2个需求/秒）-对于FAOSTAT生产API开箱即用安全
• 自动重试 瞬态网络误差的指数退避
• 丰富的工具描述，使AI确切地知道何时以及如何调用每个工具
• 三层混合缓存 --记忆中（20分钟）→ SQLite磁盘（24小时，跨会话）→ Redis（可选，30分钟）
• 零配置身份验证 通过 faostat_setup --存储凭据一次，永远不要再触摸配置文件
• 消歧 通过 faostat_search_codes --特工在猜测模棱两可的代码之前会先问
• 适用于 克劳德桌面，克劳德代码，光标，风帆，Zed，以及任何兼容MCP的客户端

______________________________________________________________________

快速开始

先决条件

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

选项A——通过MCP注册表安装（推荐）

列在 MCP官方注册 --可直接从Claude Desktop、Cursor和任何MCP兼容客户端发现。

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

选项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_API_TOKEN=your_token_here        ← API token, OR
# FAOSTAT_USERNAME=your_email              ← username + password
# FAOSTAT_PASSWORD=your_password

在上注册免费的FAOSTAT API帐户 FAOSTAT开发者门户.

可选--Redis缓存（多用户/高容量部署）

服务器在没有Redis的情况下工作（使用SQLite磁盘缓存代替）。对于共享或大容量设置，请通过Docker启动Redis：

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

然后设置 REDIS_HOST_IP_ADDRESS, REDIS_HOST_PORT_NUMBER，以及 REDIS_DATABASE 在 .env.

______________________________________________________________________

运行服务器

开发模式（交互式MCP检查器UI）

mcp dev faostat_mcp/server.py

在以下位置打开浏览器UI http://localhost:5173 在那里，您可以交互式浏览和测试所有21个工具。

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

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

______________________________________________________________________

缓存

服务器使用 三层缓存 以尽量减少多余的API调用。FAOSTAT数据最多每天更新一次，因此大多数重复查询都会立即得到服务。

缓存查找顺序：内存→ disk → 瑞迪斯→ API调用。磁盘或Redis命中会在会话的其余时间将该值提升到内存中。

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

______________________________________________________________________

MCP客户端集成

服务器通过stdio使用标准MCP，因此它可以与任何兼容的客户端配合使用。

推荐配置（PyPI安装）

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

开发/源代码配置

{
  "mcpServers": {
    "faostat": {
      "command": "python",
      "args": ["-m", "faostat_mcp.server"],
      "cwd": "/path/to/faostat-mcp",
      "env": {
        "FAOSTAT_API_TOKEN": "your_token_here"
      }
    }
  }
}

克劳德桌面版

将上面的一个块添加到：

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

重新启动克劳德桌面-- faostat 将出现在工具面板中。

光标

将块添加到 .cursor/mcp.json 在项目根目录中，或在全局游标MCP设置中。请参阅 光标MCP文档 了解详情。

Windsurf/Zed/其他客户

任何支持MCP stdio服务器的客户端都接受相同的配置形状。有关配置文件的位置，请参阅客户的文档。

______________________________________________________________________

查询示例

连接后，向您的AI助手提出以下问题：

您的AI助手将自动：

1. 呼叫 faostat_list_groups 或 faostat_groups_and_domains 找到正确的域名
2. 呼叫 faostat_search_codes 按名称查找代码——如果多个代码匹配（例如“生产”与两者都匹配 *生产* 和 *总生产指数*)，助理 暂停并要求您做出选择 在继续之前
3. 呼叫 faostat_get_data 或 faostat_get_rankings 已确认的代码
4. 用通俗易懂的语言解释和总结结果

______________________________________________________________________

可用的MCP工具

发现和元数据

数据检索

认证

______________________________________________________________________

项目结构

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 21 tool definitions
    └── client.py             ← HTTP client, rate limiting, 3-tier cache, credential storage

______________________________________________________________________

重要提示：过滤代码与显示代码

API使用 两种不同的编码系统: *过滤器代码* （用于查询参数）和 *显示代码* （如响应数据和批量CSV所示）。始终使用来自的筛选代码 faostat_get_codes 通话时 faostat_get_data.

两者的地区、项目和年份代码相同。 仅 元素 代码不同：

QCL--农作物和畜产品

TM——交易矩阵

FS-粮食安全

总是打电话 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')

______________________________________________________________________

限制和注意事项

• 此服务器的目标是 粮农组织生产API (https://faostatservices.fao.org/api/v1).
• 费率限制： 2个请求/秒，通过令牌桶自动执行。
• 响应被缓存在3个层（内存→ SQLite磁盘→ Redis）来减少API调用-请参阅 .env.example 用于TTL和大小配置。
• SQLite磁盘缓存位于 ~/.cache/faostat-mcp/cache.db 默认为24小时TTL，LRU上限为1000个入口。集 FAOSTAT_DISK_CACHE=false 禁用。
• 对于大型域（如交易矩阵），始终应用区域、项目和年份过滤器，以保持响应大小可控。

______________________________________________________________________

技能

想要在此服务器上建立有指导的分析工作流吗？结账 FAOSTAT技能 --9种平台无关的人工智能技能，用于国家概况、商品简报、贸易分析、气候评估、数据可视化等。适用于Claude Code、OpenAI Codex以及任何支持SKILL.md格式的AI助手。

______________________________________________________________________

相关项目和资源

• FAOSTAT技能 --基于此MCP服务器构建的分析技能
• 模型上下文协议 --为该服务器提供动力的开放标准
• FAOSTAT --联合国粮农组织官方统计门户
• API文件 --开发者参考
• 克劳德桌面版 --此服务器使用的人工智能助手之一
• 光标 --支持MCP的AI代码编辑器
• 帆板运动 --支持MCP的AI IDE

______________________________________________________________________

贡献者

感谢所有为这个项目做出贡献的人。

欢迎捐款——见 贡献.md 作为指导方针。

______________________________________________________________________

引用

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

纯文本：

Obli Laryea，G.和贡献者。 (2026).粮农统计数据库MCP服务器：人工智能辅助访问粮农统计数据库（v1.2.2）\[计算机软件\]。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的基础数据时，请使用粮农组织推荐的特定领域格式：

粮农组织，{年}。FAOSTAT:{域名}，http://www.fao.org/faostat/en/#data/｛域名代码｝

例如：

联合国粮农组织，2026年。粮农组织统计数据库：农作物和畜产品，http://www.fao.org/faostat/en/#data/QCL

联合国粮农组织，2026年。FAOSTAT：排放总量，http://www.fao.org/faostat/en/#data/GT

______________________________________________________________________

更新日志

看 更改日志.md 有关更改的完整历史记录，由自动生成 约定式提交.

______________________________________________________________________

GitHub主题

如果你分叉或标记这个仓库，建议主题： mcp, faostat, model-context-protocol, ai-tools, agriculture, food-security, fao, un-data, python, llm, unfao, undata