Faostat Mcp

FAOSTAT MCP サーバー

AI を使って国連の食料・農業統計を検索 — Model Context Protocol を活用

FAOSTAT API の全機能を AI アシスタント向けのツールとして提供する MCP（Model Context Protocol）サーバーです。FAOSTAT API に、MCP 対応クライアント（Claude、Cursor、Windsurf、Zed、自作のエージェントなど）を接続すると、国連食糧農業機関（FAO）が提供する、食料、農業、漁業、林業、栄養に関する世界で最も包括的なデータベースを利用できます。245 の国と地域を対象としています。

キーワード： FAOSTAT、MCP サーバー、Model Context Protocol、AI 農業データ、FAO 統計、AI 食料安全保障、農業データ Python、国連データ、作物生産統計、Claude、Cursor、Windsurf

---

どのような場合に役立ちますか？

研究者、データジャーナリスト、政策アナリスト、開発者は、自然言語で質問するだけで、FAOSTAT から直接回答を得られます。API 呼び出しを一度も書く必要はありません。AI アシスタントが、データ領域の特定、フィルタリング、解釈を自動的に行います。

対象となる方

• 農業経済学者、食料安全保障の研究者
• FAO データを扱うジャーナリスト、政策アナリスト
• FAOSTAT を活用した AI パイプラインを構築する開発者
• 作物、貿易、栄養、排出量のデータを会話形式で調べたい方

---

FAOSTAT とは？

FAOSTAT は、国連食糧農業機関（FAO）の統計データベースです。食料と農業に関するデータを無料で利用できる、世界で最も包括的な情報源であり、次の情報を提供しています。

• 作物・畜産物の生産 — 数百種類の品目に関する収量、収穫面積、生産量
• 貿易 — 国ごとの輸入・輸出量と金額
• 食料安全保障 — 栄養不足人口の割合、食事エネルギー供給量、アクセス指標
• 排出量 — 農業、土地利用、食料システムからの温室効果ガス排出量
• 林業・漁業 — 生産・貿易データ
• 価格、投入財、人口 — 生産者価格、肥料の使用量、人口統計の背景情報

データは 1961 年から現在までを対象とし、245 の国と地域について、複数の言語で提供されています。

MCP とは？

Model Context Protocol は、AI アシスタントが実行時に外部ツールを呼び出せるようにするオープン標準です。このサーバーは、FAOSTAT API のすべてのエンドポイントを検出可能なツールとして登録します。質問すると、AI アシスタントが適切な呼び出しを自動的に選択し、連携させます。

---

機能

• すべての FAOSTAT エンドポイント（データ、メタデータ、ランキング、一括ダウンロード、レポート）を網羅する 23 個の MCP ツール
• 作物、畜産、貿易、食料安全保障、排出量、林業、漁業など、数十のドメインにまたがる 245 の国と地域
• 組み込みの レート制限（2 リクエスト/秒）— FAOSTAT の本番 API で、すぐに安全に使用できます
• 一時的なネットワークエラーに対する指数バックオフ付きの 自動再試行
• AI が各ツールをいつ、どのように呼び出すべきかを正確に把握できる、詳細なツールの説明
• 3 層ハイブリッドキャッシュ — メモリ内（20 分）→ SQLite ディスク（24 時間、セッション間で共有）→ Redis（任意、30 分）
• faostat_setup による 認証設定不要 — 認証情報を一度保存するだけで、設定ファイルに触れる必要はありません
• faostat_search_codes による 曖昧さの解消 — エージェントは、曖昧なコードを推測する前に確認します
• Claude Desktop、Claude Code、Cursor、Windsurf、Zed および MCP 互換クライアントで動作します

---

クイックスタート

前提条件

• Python 3.10+
• 任意の MCP 互換クライアント（Claude Desktop、Cursor、Windsurf、Zed、またはカスタムエージェント）

オプション 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

ブラウザー UI が http://localhost:5173 で開き、23 個のツールをすべて対話的に確認、テストできます。

本番モード（stdio トランスポート、Claude Desktop 向け）

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

---

キャッシュ

このサーバーは、重複する API 呼び出しを最小限に抑えるために 3 層キャッシュ を使用します。FAOSTAT のデータは、1 日に 1 回を超えて更新されることはほとんどないため、ほとんどの繰り返しクエリには即座に応答できます。

層	TTL	範囲	備考
メモリ内	20 分	現在のセッション	最速。サーバーの再起動時にリセットされます
SQLite ディスク	24 時間	セッション間	~/.cache/faostat-mcp/cache.db。追加のインフラは不要です
Redis	30 分	複数ユーザーで共有	任意。有効にするには REDIS_* 環境変数を設定します

キャッシュの検索順序：メモリ → ディスク → Redis → API 呼び出し。ディスクまたは Redis から取得した値は、セッションの残りの間、メモリに昇格されます。

ディスクキャッシュを無効にするには（読み取り専用のファイルシステムの場合など）、FAOSTAT_DISK_CACHE=false を設定します。

---

MCP クライアントとの連携

このサーバーは標準の MCP over stdio を使用するため、あらゆる互換クライアントで動作します。

推奨設定（PyPI インストール）

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

開発／ソース設定

{
  "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 定義（例：「West Africa」 → 「Western 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 を返し、先に進む前にエージェントがユーザーに確認するよう求めます
faostat_get_definitions	ドメインの定義
faostat_get_definitions_by_type	ドメイン内の種類別定義
faostat_definition_types	すべての定義の種類
faostat_get_definition_type	1つの種類に関する 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 では、2 種類のコード体系（クエリパラメーターで使う フィルターコード と、レスポンスデータや一括 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 リクエスト。トークンバケット方式で自動的に適用されます。
• API 呼び出しを減らすため、レスポンスは 3 層（メモリ → SQLite ディスク → Redis）でキャッシュされます。TTL とサイズの設定については .env.example を参照してください。
• SQLite ディスクキャッシュは ~/.cache/faostat-mcp/cache.db にあり、デフォルトでは TTL が 24 時間、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 — 国連食糧農業機関（FAO）の公式統計ポータル
• FAOSTAT API Docs — 開発者向けリファレンス
• Claude Desktop — このサーバーが対応する AI アシスタントの 1 つ
• 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形式にするには"csv"を使用してください。データクエリでは、値の解釈に必要な単位を維持したうえでfieldsを選択します。検索結果のデフォルトは25件です。_truncatedがtrueの場合は、クエリを絞り込んでください。

ドメインがわかっている場合は、faostat_search_codesを直接使用してください。グローバル名解決ツールが返すdefinition_codeは、必ずしもクエリのフィルターコードとは限りません。no_matching_definitionの結果が示すのは、この照会に一致する定義がないことであり、FAOの用語全般に該当する定義がないという意味ではありません。コードの参照、検索、検証ではキャッシュされたテーブルを共有します。繰り返し実行するデータクエリでは、形式、フィールド選択、行数上限が異なっても、未加工の応答が再利用されます。