PSGC MCP Server

PSGC MCP Server

一个 Model Context Protocol 服务，为大模型提供菲律宾标准地理代码（PSGC）数据。基于 Cloudflare Workers 构建，并使用 KV 存储。

公开、只读，无需身份验证。数据直接来自菲律宾统计局每季度发布的 PSGC 数据。数据缓存在 Cloudflare KV 中，确保可靠性并实现全球低延迟访问。

工具

工具	说明
lookup	根据 10 位 PSGC 代码获取地理实体
search	按名称搜索实体，可选按级别筛选并启用严格模式
get_hierarchy	获取完整的行政层级链（从 barangay 到 region）
list_children	列出某个父实体的直接子实体
list_by_type	列出指定地理级别的所有实体
batch_lookup	一次调用查询多个实体（最多 50 个代码）
query_by_population	按人口范围查询实体，并支持排序和筛选

地理级别

级别	说明	数量
Reg	Region	18
Prov	Province	82
Dist	District（仅限 NCR）	4
City	City	149
Mun	Municipality	1,493
SubMun	Sub-Municipality（仅限 Manila）	16
SGU	Special Geographic Unit（BARMM）	~8
Bgy	Barangay	~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 返回的实体对象使用 snake_case 字段名：

字段	类型	说明
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	城乡分类（仅适用于 barangay）
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。

Field	Type	Description
results	(Entity | null)[]	按输入顺序排列的实体；未找到时为 null
found	number	成功解析的代码数量
not_found	number	返回 null 的代码数量
total	number	请求的代码总数

按人口查询

query_by_population 工具会查找人口处于指定范围内的实体，并按人口排序。适用于“第 III 区最大的城市”或“人口少于 50,000 的市镇”等问题。

Parameter	Type	Required	Description
level	string	Yes	要查询的地理级别
parent_code	string	仅 Bgy	将结果限定在某个上级实体范围内（前缀匹配）。Barangay 必须提供此参数。
min_population	number	No	最低人口（含）
max_population	number	No	最高人口（含）
sort	asc | desc	No	排序顺序（默认：desc）
limit	number	No	最大结果数，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 使用 Districts 代替 Provinces（Dist 级别）
• Cotabato City 在行政上属于 BARMM，但地理上属于 Region XII——它显示在 Prov 代码 124700000（Maguindanao del Norte）下
• BARMM 特殊地理单位（SGU）不遵循标准层级，且没有 Province 上级实体

数据来源

Source	Vintage	Description
PSA PSGC Publication	Q4 2025 (January 13, 2026)	地理代码、名称、级别和分类
2024 Census of Population	Proclamation No. 973	各实体的人口数量
PSA PSGC Old Names column	Q4 2025	历史／旧地名
PSA PSGC Urban/Rural column	Q4 2025	Barangay 城乡分类

上次同步：2026 年 3 月 2 日。

重大变更（v1.1.0+）

• 现在所有数据响应都包装在 { _meta, data } 中。使用方必须从响应中解包 data。
• 实体字段名称已改为 snake_case：code 现为 psgc_code，parent 现为 parent_code，cityClass 现为 city_class，等等。
• 搜索结果现在使用 psgc_code，而非 code。
• 所有实体字段始终都会出现。之前可选的字段现在会显示为 null，而非省略。
• 内部字段 regionCode 和 provinceCode 不再通过 API 响应公开。

相关项目

这是菲律宾公共数据 MCP 服务系列的一部分：

• PSGC MCP（本仓库）
• LTS MCP - DHSUD License to Sell 验证
• PH Holidays MCP -> 即将推出
• BSP Bank Directory MCP -> 即将推出

所有服务均免费、公开且只读。数据取自菲律宾政府官方来源。

贡献与问题反馈

发现数据错误或尚未处理的边界情况？请提交 issue。上方的特殊情况部分涵盖了最常见的问题，但 PSGC 数据在数十年的 LGU 重新分类过程中积累了许多不一致之处，issues 列表是跟踪这些问题的最佳方式。

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"

比较两个季度的 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 多个结构化地理页面，覆盖菲律宾的每个 barangay、城市和省份。PSGC MCP 源于为 AI Agent 寻找可靠、可查询的菲律宾地理数据，却未找到合适数据的需求。

如需企业级 SLA、定制集成或其他菲律宾数据源： → godmode.ph

许可证

MIT