PSGC MCP Server

PSGC MCP サーバー

LLM にフィリピン標準地理コード（PSGC）データを提供するモデルコンテキストプロトコルサーバーです。Cloudflare Workers と KV ストレージを使用して構築されています。

公開されており、読み取り専用で、認証は不要です。データはフィリピン統計局が四半期ごとに公開する PSGC データを直接取得しています。信頼性と世界各地からの低遅延アクセスを実現するため、Cloudflare KV にキャッシュされています。

ツール

ツール	説明
lookup	10 桁の PSGC コードで地理エンティティを取得します
search	名前でエンティティを検索します。レベルによる絞り込みと厳密モードを任意で指定できます
get_hierarchy	完全な行政階層（バランガイから地域まで）を取得します
list_children	親エンティティの直接の子を一覧表示します
list_by_type	指定された地理レベルのすべてのエンティティを一覧表示します
batch_lookup	1 回の呼び出しで複数のエンティティを検索します（コードは最大 50 件）
query_by_population	人口範囲でエンティティを検索し、並べ替えや絞り込みを行います

地理レベル

レベル	説明	件数
Reg	地域	18
Prov	州	82
Dist	地区（NCR のみ）	4
City	市	149
Mun	自治体	1,493
SubMun	区（マニラのみ）	16
SGU	特別地理単位（BARMM）	約 8
Bgy	バランガイ	約 42,000

応答形式

すべてのデータ応答は、標準的なエンベロープでラップされます。

{
  "_meta": {
    "dataset_version": "PSGC Q4 2025",
    "dataset_date": "2025-12-31",
    "last_synced": "2026-03-02",
    "source": "Philippine Statistics Authority (PSA)",
    "source_url": "https://psa.gov.ph/classification/psgc/"
  },
  "data": { ... }
}

エラー応答（isError: true）と情報メッセージ（例：「子が見つかりません」）は、ラップせずにプレーンテキストで返されます。

エンティティスキーマ

lookup、get_hierarchy、list_children、list_by_type、batch_lookup、query_by_population が返すエンティティオブジェクトでは、スネークケースのフィールド名が使用されます。

フィールド	型	説明
psgc_code	string	10 桁の PSGC コード
name	string	公式の地名
level	string	地理レベル（Reg、Prov、Dist、City、Mun、SubMun、SGU、Bgy）
old_name	string | null	名称変更前の名前。変更されている場合に設定されます
city_class	string | null	市の分類：HUC、ICC、CC、または null
income_class	string | null	所得分類（第 1 級から第 6 級）
urban_rural	string | null	都市部／農村部の分類（バランガイのみ）
population	number | null	2024 年国勢調査の人口
parent_code	string | null	親エンティティの PSGC コード

すべてのフィールドは常に含まれます。データのないフィールドは省略されず、null になります。

検索結果

search ツールは、より簡潔な結果オブジェクトを返します。

フィールド	型	説明
psgc_code	string	10 桁の PSGC コード
name	string	公式の地名
level	string	地理レベル

厳密検索

search ツールでは、任意のブール値パラメーター strict を指定できます。strict: true の場合、正規化後に名前が完全一致した結果のみが返されます。部分一致や部分文字列による一致は除外されます。地名が正確に分かっており、曖昧な結果を避けたい場合に便利です。

一括検索

batch_lookup ツールは、1～50 件の PSGC コードの配列を受け取り、入力と同じ順序で結果を返します。見つからなかったコードの位置には null が返されます。

フィールド	型	説明
results	(Entity | null)[]	入力順のエンティティ。見つからなかった場合は null
found	number	解決できたコードの数
not_found	number	null を返したコードの数
total	number	要求されたコードの合計数

人口によるクエリ

query_by_population ツールは、人口範囲内のエンティティを検索し、人口順に並べます。「Region III の最大の都市」や「人口 50,000 人未満の自治体」といった質問に役立ちます。

パラメーター	型	必須	説明
level	string	はい	クエリ対象の地理的レベル
parent_code	string	Bgy のみ	親エンティティを指定して結果を絞り込みます（前方一致）。バランガイでは必須です。
min_population	number	いいえ	最小人口（この値を含む）
max_population	number	いいえ	最大人口（この値を含む）
sort	asc | desc	いいえ	並べ替え順（デフォルト：desc）
limit	number	いいえ	最大結果数、1～100（デフォルト：10）

レスポンスには results（エンティティ配列）、total_matching（上限適用前の合計数）、returned（実際に返された件数）が含まれます。人口が null のエンティティは除外されます。

接続

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "psgc": {
      "url": "https://psgc.godmode.ph/mcp"
    }
  }
}

クイックテスト

curl -X POST https://psgc.godmode.ph/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "query": "Carmona", "level": "Mun" }
    }
  }'

PSGC コード形式

PSGC コードはスペースを含まない 10 桁の数字です。各セグメントは地理的階層全体を表します：

1 4 0 2 1 0 0 0 0 0
│ │ └─┬─┘ └─┬─┘ └─┬─┘
│ │   │     │     └── Barangay (last 3 digits)
│ │   │     └──────── Municipality/City (3 digits)
│ │   └────────────── Province (2 digits)
│ └────────────────── Island Group modifier
└──────────────────── Region (1 digit)

先頭のゼロには意味があります。014021000000 と 14021000000 は異なるコードです。必ず 10 桁の文字列を使用してください。

既知の例外：

• NCR では州ではなく地区（Dist レベル）が使われます
• Cotabato City は行政上は BARMM に属しますが、地理的には Region XII に位置しています。Prov コード 124700000（Maguindanao del Norte）の下に表示されます
• BARMM の特別地理単位（SGU）は標準的な階層に従わず、州の親を持ちません

データソース

ソース	時点	説明
PSA PSGC Publication	2025 年第 4 四半期（2026 年 1 月 13 日）	地理コード、名称、レベル、分類
2024 Census of Population	Proclamation No. 973	エンティティごとの人口数
PSA PSGC Old Names column	2025 年第 4 四半期	過去または旧地名
PSA PSGC Urban/Rural column	2025 年第 4 四半期	バランガイの都市部・農村部の分類

最終同期日：2026 年 3 月 2 日。

破壊的変更（v1.1.0 以降）

• すべてのデータレスポンスが { _meta, data } でラップされるようになりました。利用側ではレスポンスから data を取り出す必要があります。
• エンティティのフィールド名が snake_case に変更されました。code は psgc_code に、parent は parent_code に、cityClass は city_class になるなどの変更があります。
• 検索結果では code の代わりに psgc_code が使われます。
• すべてのエンティティフィールドが常に含まれるようになりました。以前は省略可能だったフィールドも、省略されずに null として表示されます。
• 内部フィールドの regionCode と provinceCode は API レスポンスで公開されなくなりました。

関連プロジェクト

フィリピンの公開データを扱う MCP サーバー群の一部です：

• PSGC MCP（このリポジトリ）
• LTS MCP - DHSUD の販売許可確認
• PH Holidays MCP -> 近日公開
• BSP Bank Directory MCP -> 近日公開

すべてのサーバーは無料で、一般公開されており、読み取り専用です。データはフィリピン政府の公式情報源から取得しています。

コントリビューションと問題報告

データの誤りや未対応の例外を見つけた場合は、issue を作成してください。上記の例外セクションでは最も一般的なものを説明していますが、PSGC データには数十年にわたる LGU の再分類に伴う不整合が蓄積されており、問題の追跡には issue リストが最適です。

PSA は四半期ごとに更新を公開しています。データが古いと思われる場合は issue を作成してください。次回の定期同期を待たずに更新します。

データパイプライン

PSGC データは PSA の Excel 公開資料から解析され、Cloudflare KV に保存されます。更新するには：

1. PSGC Excel ファイルをダウンロードする

PSA PSGC から最新の公開資料を入手し、scripts/data/ に配置します。

2. 差分を確認する（任意）

npm run diff-psgc -- "scripts/data/Q3 2025/PSGC-3Q-2025-Publication-Datafile.xlsx" "scripts/data/PSGC-4Q-2025-Publication-Datafile (1).xlsx"

2 つの四半期分の Excel ファイルを比較し、追加、削除、名称変更、フィールド変更を報告します。全体を解析する前に実行し、PSA の変更履歴を確認してください。

3. 解析する

npm run parse-psgc

Excel ファイルを読み込み、親子関係を導出して、チャンク化された JSON ファイルを scripts/data/output/ に書き込みます。

4. KV にアップロードする

npm run upload-kv

wrangler を介して、すべての JSON チャンクを Cloudflare KV に一括アップロードします。

5. デプロイする

npm run deploy

開発

npm install
npm run dev

開発サーバーは http://localhost:8787 で起動します。MCP クライアントを http://localhost:8787/mcp に接続してください。

セットアップ

初回デプロイの前に、KV 名前空間を作成します：

npx wrangler kv namespace create PSGC_KV

返された名前空間 ID で wrangler.jsonc を更新します。

制作者

Aaron Zara - Godmode Digital のフラクショナル CTO

以前に REN.PH を構築しました。これはフィリピン全土のすべてのバランガイ、市、市町、州を網羅する、60,000 件以上の構造化された地理情報ページを備えたプログラマティック不動産プラットフォームです。PSGC MCP は、AI エージェント向けの信頼できる検索可能なフィリピンの地理データが必要になったものの、要件に合うものが見つからなかったことから生まれました。

エンタープライズ SLA、カスタム統合、その他のフィリピンのデータソースについて： → godmode.ph

ライセンス

MIT