Govdata Mcp

GovData MCP

AI エージェントが各国政府のデータポータルからオープンデータセットを検索、調査、取得できる Model Context Protocol（MCP）サーバーです。米国、英国、カナダ、オーストラリアを横断する統一されたツールインターフェースを提供し、各ポータル特有の仕様（API の移行、認証の制約、バイリンガルのメタデータ、古い DataStore フラグ）は共通のアダプターレイヤーで吸収します。

一般的なエージェントのワークフローに合わせて設計されています。「X に関する政府のデータセットはありますか？」→候補を見つける→ファイルを確認する→行をプレビューするかダウンロードリンクを取得して次へ進む。

主な機能

• 4 つの国別ポータルを 1 つのインターフェースで利用できます。 米国（data.gov v4 / DCAT）、英国（data.gov.uk / CKAN）、カナダ（open.canada.ca / CKAN）、オーストラリア（data.gov.au / CKAN + DataStore）。
• トークンの使用量を抑える設計です。 説明文は HTML を除去して長さを制限し、検索結果は簡潔な概要にまとめ、大きなファイルを誤ってインライン表示しないようにしています。
• 行レベルでプレビューできます。 利用可能な場合は CKAN DataStore（オーストラリア）を使用し、それ以外のポータルでは CSV/TSV ファイルの先頭を読み取る方式に透過的にフォールバックします。
• エージェントに適したエラー処理です。 エラーは実行可能な対処法を含むテキスト（「代わりに get_download_link を使用してください」「dataset_id を指定して再試行してください」「利用可能なポータル：…」）で返し、生のトレースバックは返しません。
• 拡張可能なレジストリです。 CKAN ベースのポータルは設定項目を 1 つ追加するだけで対応でき、CKAN 以外のポータルは小規模なアダプタークラスで接続できます。
• 2 種類のトランスポートに対応します。 ローカルクライアント（Claude Desktop など）には stdio、サーバーレス環境へのデプロイにはステートレスな streamable-http を使用できます（Google Cloud Run）。

対応ポータル

要件

• Python 3.11+
• 米国のポータルには api.data.gov API キーが必要です（無料。他のポータルには認証情報は不要です）

インストール

git clone https://github.com/YOUR_ORG/Gov-Stat-MCP-Server.git
cd Gov-Stat-MCP-Server

# pip
pip install -e ".[dev]"

# or conda
conda env create -f environment.yml
conda activate opendata-mcp

.env.example を .env にコピーし、キーを設定します。

DATAGOV_API_KEY=your-api-data-gov-key

はじめに

ほとんどの MCP クライアント向けの標準設定です（stdio トランスポート）。

{
  "mcpServers": {
    "govdata": {
      "command": "govdata-mcp",
      "env": {
        "DATAGOV_API_KEY": "your-api-data-gov-key"
      }
    }
  }
}

claude mcp add govdata -e DATAGOV_API_KEY=your-key -- govdata-mcp

MCP_TRANSPORT=http govdata-mcp

{
  "mcpServers": {
    "govdata": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

想定されるエージェントのフロー：list_portals → search_datasets → get_dataset → preview_resource / fetch_resource / get_download_link。

設定

すべての設定は環境変数（またはローカルの .env ファイル）で指定します。

Docker

make docker-build          # build image
make docker-run            # run on :8080, exactly as Cloud Run would

このイメージはステートレスモードで HTTP トランスポートを実行し、サーバーレスプラットフォームに対応しています（Google Cloud Run のデプロイスクリプトが deploy/ に含まれています）。

開発

make run          # stdio mode
make run-http     # HTTP mode on :8080
make inspect      # MCP Inspector interactive UI (requires Node.js)
make test         # offline unit tests
make test-live    # live end-to-end tests against all four real portals
make lint         # ruff check + format check

ライブテストスイート（pytest -m live）では、国ごとの検索 → 詳細確認 → プレビュー → 取得の一連の処理に加え、ポータル固有の動作（カナダのバイリンガル正規化、英国のデータセット単位のリソース検索、オーストラリアの DataStore パス）を検証します。デプロイ前に実行してください。政府のポータルは予告なく変更されることがあります。

アーキテクチャ

src/govdata_mcp/
├── server.py            # FastMCP instance + tool registration
├── config.py            # env-driven settings
├── ckan/                # generic async CKAN client, models, typed errors
├── portals/
│   ├── registry.py      # portal registry — single source of truth
│   ├── base.py          # Portal config + default (vanilla CKAN) adapter
│   ├── us.py            # data.gov v4 DCAT adapter (auth, cursor paging)
│   ├── uk.py            # dataset-scoped resource lookup
│   └── ca.py            # bilingual metadata normalization
├── tools/               # MCP tools: search, explore, fetch
└── utils/               # formatting (token economy), CSV-head preview

ポータルの追加： 標準的な CKAN ポータルの場合は、portals/registry.py に Portal(...) エントリーを 1 つ追加すれば完了です。独自の仕様があるポータルでは、PortalAdapter をサブクラス化し、限定的なフック（normalize_dataset、build_search_params）をオーバーライドします。CKAN 以外の API の場合は、操作メソッド自体をオーバーライドします（カスタムアダプター全体の例は us.py を参照してください）。

TODO / ロードマップ

• 🇨🇳 中国のポータル対応 — 全国統一のオープンデータ API がないため、国家統計局のデータを対象としたカスタムアダプターを、既存の統計パッケージ経由で実装する予定です。適切に機能を縮退させます。
• 🇯🇵 日本のポータル対応 — e-Gov データポータル（data.e-gov.go.jp）は CKAN 互換で、既存のレジストリに追加できる見込みです。より充実した e-Stat 統計 API（アプリ ID 認証、日本語のメタデータ）は、専用アダプターとして実装する予定です。
• CI 向けにポータルのフィクスチャを記録したオフラインの単体テストスイート（respx）
• Google Cloud Run のデプロイ手順（サービスはコンテナー対応済み。スクリプトは deploy/ にあります）
• 米国 v4 の発行元／形式検索フィルター（API ドキュメント待ち）
• CKAN ポータルの追加（ニュージーランドの data.govt.nz はほぼ手間なく追加できます）
• 誤った形式ラベルが付いたリソースを救済するためのコンテンツタイプ判定

セキュリティに関する注意事項

• このサーバーからポータルへの操作は読み取り専用です。作成、変更、削除を行うツールはありません。
• fetch_resource と preview_resource は、ポータルのメタデータに含まれる URL からダウンロードします。コンテンツはサイズ制限とバイナリチェックを適用してからモデルに返しますが、取得したコンテンツは信頼できない入力として扱ってください。
• サーバー自体に認証機能はありません。リモートにデプロイする場合は、認証プロキシまたはプラットフォームレベルの認証の背後に配置してください（例：--no-allow-unauthenticated を指定した Cloud Run）。
• DATAGOV_API_KEY は .env またはシークレットマネージャーで管理し、絶対にコミットしないでください。

ライセンス

MIT