PH Civic Data

ph-civic-data-mcp

面向 Agent 的菲律宾公民数据工具。涵盖 PSA OpenSTAT 的完整统计目录、PSGC 地点代码、基础设施支出问责、地震、天气、台风、采购、贫困、太阳辐射、空气质量、卫星植被数据和宏观指标。人口数据可细化至 barangay 级别。41 个工具，无需 API 密钥。

菲律宾的公民数据门户以不同格式发布开放数据：抓取而来的 HTML 表格、PXWeb JSON 和未公开文档的 API。没有任何工具将它们整合起来供 Agent 使用。本服务通过 stdio 提供整合功能，无需托管成本或 API 密钥。它可以回答诸如某个 barangay 有多少人口、某地是否靠近活动断层或火山、某个城市在防洪方面花费了多少，以及一个地点与另一个地点相比如何等问题。

所有数据均来自公开记录。启发式指标仅用于统计。具体指控需要独立调查和第二个来源佐证。

安装

以下每个客户端都通过 stdio 运行同一个软件包 uvx ph-civic-data-mcp。

Claude Desktop。 将以下内容添加到 claude_desktop_config.json。在 macOS 上，该文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "ph-civic-data": {
      "command": "uvx",
      "args": ["ph-civic-data-mcp"]
    }
  }
}

Claude Code。

claude mcp add ph-civic-data -- uvx ph-civic-data-mcp

Codex。 已于 2026-09-03 确认正常运行。

codex mcp add ph-civic-data -- uvx ph-civic-data-mcp

Cursor。 将以下内容添加到 mcp.json：

{
  "mcpServers": {
    "ph-civic-data": {
      "command": "uvx",
      "args": ["ph-civic-data-mcp"]
    }
  }
}

VS Code。 将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "ph-civic-data": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ph-civic-data-mcp"]
    }
  }
}

Docker。 构建一次，然后使用 -i 以 stdio 模式运行：

docker build -t ph-civic-data-mcp .

镜像以非 root 用户身份运行，并附带健康检查。

该录屏由 vhs docs/demo_setup.tape 生成。它使用 --mcp-config 指向本服务启动 Claude Code；Claude 随后调用 get_weather_forecast 和 get_population_stats，并对结果进行关联分析。气温和人口数据均为录制时实时来源返回的结果。关于人口的回答基于 2024 年人口普查（NCR：截至 2024 年 7 月 1 日为 14,001,751 人）。

我可以问些什么？

ph-civic-data-mcp 通过 19 个公共数据源提供 41 个工具。对于任何与地点有关的问题，都可以从 get_area_profile 开始。它会先将地点名称解析为 PSGC 代码，然后在一次调用中整合人口统计、经济、采购、灾害风险和未来 3 天的天气预报，并将基础设施通知统一换算为每 100,000 名居民的数据。

快速了解某个地点

• “介绍一下塔克洛班。” get_area_profile
• “QC 的 PSGC 代码是什么？” resolve_ph_location
• “三宝颜市有多少人口？” get_population_stats
• “东米沙鄢的贫困率是多少？” get_poverty_stats
• “阿尔拜现在安全吗？” assess_area_risk
• “列出宿务省的各个城市。” list_admin_units
• “显示该描笼涯所属的完整行政层级。” get_location_hierarchy

比较两个或更多地点

• “比较宿务市和达沃市的人口与贫困情况。” compare_areas
• “三宝颜的就业率与卡加延德奥罗相比如何？” compare_areas
• “将五个城市的对比结果导出为 CSV 文件。” compare_areas

查看某个地点附近的灾害

• “过去一天黎牙实比附近发生过地震吗？” get_latest_earthquakes
• “读取该次地震的完整 PHIVOLCS 公报。” get_earthquake_bulletin
• “马荣火山当前的警戒级别是多少？” get_volcano_status
• “菲律宾区域现在有台风活动吗？” get_active_typhoons
• “将该次地震与 USGS 全球数据流进行交叉核查。” get_usgs_earthquakes_ph
• “本周卡加延德奥罗的河流洪水预报是什么？” get_flood_forecast
• “自 1990 年以来，哪些台风经过萨马岛附近？” get_historical_typhoons_ph

搜索采购和支出信息

• “搜索所有 PhilGEPS 道路维修公告。” search_procurement
• “在 PhilGEPS 上搜索邦板牙的防洪项目。” search_infra_projects
• “总结比科尔地区 2025 年的基础设施支出。” summarize_infra_spending
• “第七区的采购活动规模有多大？” get_procurement_summary
• “标记宿务值得进一步审查的 PhilGEPS 公告。” flag_infra_anomalies
• “获取一个已标记项目的完整公告。” get_infra_project

查询 PSA 统计目录

• “查找提及生育率的 PSA 表格。” search_psa_catalog
• “带我了解 OpenSTAT 上的贫困主题。” browse_psa_catalog
• “这个贫困表格有哪些维度？” describe_psa_dataset
• “获取 2023 年按岛群划分的贫困发生率。” query_psa_dataset
• “当前通胀率是多少？” get_inflation_stats
• “全国失业率是多少？” get_labor_stats
• “获取最新年份的 PSA 健康指标。” get_health_indicators
• “哪个 PSIC 代码对应水稻种植？” search_psic_codes

query_psa_dataset 要求为每个维度明确指定值代码，不接受 "all" 和 "*"，且每次查询最多返回 1000 个单元格。PSA 会对完整立方体请求返回 HTTP 403，因此只能先使用 describe_psa_dataset。

查看天气和环境

• “怡朗未来 5 天的天气预报是什么？” get_weather_forecast
• “比科尔目前有天气警报吗？” get_weather_alerts
• “巴拉望的太阳辐射量是多少？” get_solar_and_climate
• “马尼拉今天的空气质量如何？” get_air_quality
• “棉兰老岛今年的植被发生了怎样的变化？” get_vegetation_index
• “列出最新的 PAGASA 天气公告。” list_pagasa_advisory_files
• “菲律宾人均 GDP 的变化趋势如何？” get_world_bank_indicator

查看 2025 年选举结果

• “逐层浏览选举结果树，查看北伊罗戈省亚当斯市的投票区结果。” browse_election_results
• “显示投票区 28010001 的票数统计。” get_election_return

档案于 2025-05-16 冻结，因此这两个工具读取的是固定的公开记录。 这些工具只检索信息，不进行解读。

跟踪新法律并查找开放数据集

• “《官方公报》本周发布了什么内容？” get_official_gazette_feed
• “在 HDX 上查找菲律宾洪水数据集。” search_hdx_datasets

每个 HDX 数据集都有自己的许可证。重复使用前请先查看 license_id。

从提示词开始，而不是从工具开始

三个 MCP 提示词预先编排了多步骤工作，因此客户端可以将其作为斜杠命令或起点提供。

• area_briefing(location) 汇总完整的地点简报。
• infra_accountability_scan(area) 按流程开展采购审查。
• psa_data_explorer(topic) 驱动搜索、描述和查询循环。

有一个工具可回答有关服务本身的问题。get_data_freshness 会报告运行版本、工具数量、每个数据源的缓存时长和许可证、各主机的运行状况，以及缓存时长。

两个 MCP 资源携带上下文，客户端无需调用工具即可读取。

• data://ph-civic/source-catalog 是数据源、新鲜度和许可证表。
• data://ph-civic/civic-framing 是问责输出的语言规则。

全部 41 个工具的完整签名、参数和限制： docs/tool-reference.md。

获取某个地点的完整档案

get_area_profile("Tacloban") 会返回解析后的身份信息，然后报告 Tacloban 当地的人口，而不是所在地区的人口，并附上全国人口数据。

{
 "resolved": {
  "name": "City of Tacloban",
  "psgc_code": "083747000",
  "level": "city"
 },
 "demographics": {
  "population": 259353,
  "population_year": 2024,
  "population_census": "2024 Census of Population",
  "population_reference": "PSA 2024 Census of Population, reference date 2024-07-01.",
  "population_geography_level": "highly_urbanized_city",
  "population_psgc_code": "0831600000",
  "poverty_incidence_pct": 20.6,
  "poverty_reference_year": 2023
 },
 "national_reference": {
  "population": 112729484,
  "population_year": 2024,
  "poverty_incidence_pct": 10.9,
  "poverty_year": 2023,
  "population_share_pct": 0.23,
  "poverty_gap_pct_points": 9.7
 },
 "blocks": {
  "resolve": "success",
  "population": "success",
  "poverty": "success",
  "hazard": "success",
  "weather": "success",
  "national_population": "success",
  "national_poverty": "success",
  "infra": "success"
 },
 "upstream_error": false,
 "caveats": []
}

于 2026-09-03 实时采集。Tacloban 当地人口为 259,353，取代了 早期版本报告的 Region VIII 约 460 万人口。 每个人口统计字段都会注明对应的普查、参考日期和地理层级，因此 Agent 无需猜测某个数字对应的是哪一级人口。

服务中断时返回封装对象，而不是空列表

列表工具成功时会返回真实列表。上游故障时则会返回封装对象：

{ "results": [], "upstream_error": true, "caveats": ["ConnectError: ..."] }

应将其理解为“无法访问数据源”，绝不能理解为“没有地震”或“没有 通知”。失败不会进入缓存，因此重试才有意义；caveats 条目会提供实际错误，而不是异常类名称。

每个返回单一值的工具都会将 data_status 设为以下五个值之一：

data_status	含义
success	数据源返回了一个值，并附带其来源信息。
empty	数据源已响应，但没有符合此请求的记录。
unavailable	数据源未能响应，或返回了无法读取的内容。
indeterminate	数据源已响应，但服务端无法信任结果。
invalid_request	调用方发送了错误参数。请修正 caveats 中指出的参数。

upstream_error 和 validation_error 根据 data_status 派生，因此调用方可以根据任一字段进行分支处理。get_area_profile 会在 blocks 中报告每个区块的状态，并将所有失败的区块汇总到 caveats 中，确保空值不会与空的 caveats 列表并列出现。

每个响应都包含 source 和 data_retrieved_at。

数据源与新鲜度

下表直接取自 server.py 中的 SOURCE_CATALOG，并经由 scripts/render_source_matrix.py 生成，因此会始终与服务实际报告的内容一致。

来源	提供内容	更新频率	缓存 TTL	许可证
PSGC	地点代码和名称，覆盖从地区到 barangay 的层级	PSA 发布新版 PSGC 时更新（每年或每季度）	24 h	公共领域（PSA Philippine Standard Geographic Code）
PHIVOLCS earthquakes	地震事件和完整公告	表格每 5 分钟刷新；公告按事件发布	5 min	公开，PHIVOLCS 公开公告页面
PHIVOLCS volcanoes	各受监测火山的警戒级别和公告	每座活跃火山每天发布公告	30 min	公开，PHIVOLCS 公开公告页面
PAGASA forecast	10 天天气预报，并提供 Open-Meteo 备用数据	每天发布两次；Open-Meteo 每小时更新	1 h	Open-Meteo CC-BY 4.0 / PAGASA 条款
PAGASA typhoons	活跃台风公告和天气警报	风暴活跃期间每 3-6 小时发布公告	10 min	公开，PAGASA 公告页面
PhilGEPS notices / infra	采购公告、基础设施子集、支出摘要	最新约 100 条招标公告，每 6 小时刷新	6 h	公开，PhilGEPS 开放公告列表
PSA OpenSTAT	人口、贫困、CPI、劳动力、健康及完整统计目录	按表格的统计期而异。人口：2024 年人口普查（参考日期为 2024-07-01），并按年份提供 2010、2015 和 2020 年数据。贫困：2023 年。CPI/通胀：最近发布的月份（有滞后）。劳动力调查：最近发布的季度。健康（1D）：按指标而异。	24 h	PSA 开放数据条款
Area profile (auto-stitch)	由下方各来源实时整合而成的单个地点档案	由 PSGC + PSA + PhilGEPS + PHIVOLCS + PAGASA 实时整合；每个数据块均标注自身参考期	1 h	公开，PSA OpenSTAT、PSGC、PhilGEPS、PHIVOLCS、PAGASA
NASA POWER	任意地点的每日太阳辐照度和气候数据	每日更新，约有 3 天延迟	24 h	公共领域（NASA）
Open-Meteo air quality	PM2.5、PM10、NO2、SO2、O3、CO 和 AQI	每小时	15 min	Open-Meteo CC-BY 4.0
Open-Meteo flood forecast	最近河段网格的每日河流流量预报（GloFAS 模型）	GloFAS 模型每日运行	1 h	Open-Meteo CC-BY 4.0
NASA MODIS NDVI	任意地点的 NDVI 和 EVI 植被指数	16 天合成，约有 14 天延迟	24 h	公共领域（NASA / ORNL）
USGS FDSN	菲律宾区域地震数据，并与 PHIVOLCS 数据交叉核对	全球实时数据流	10 min	公共领域（USGS）
NOAA IBTrACS	穿越菲律宾责任区的历史热带气旋路径	每年更新	24 h	公共领域（NOAA）
World Bank Open Data	菲律宾宏观经济指标	每年更新；滞后时间因指标而异	24 h	World Bank Open Data CC-BY 4.0
HDX	人道主义数据集搜索，许可证按数据集而异	按数据集的 metadata_modified 字段更新；每次查询都会实时搜索目录	6 h	HDX (Humanitarian Data Exchange) CKAN API，许可证按数据集而异
Official Gazette RSS	总统公告、备忘录通函及其他政府文件	新文件在发布当天上线；每次请求都会重建 feed	20 min	公开，Official Gazette 政府记录，适用 RA 8293 第 176 条默认规定
PAGASA public files	原始天气预警、公告和风暴潮 PDF 文件列表	weather_advisory 约每 6 小时更新；只有气旋活跃期间才发布 bulletin；stormsurge 自 2019-12-02 起未发布	15 min	PAGASA 公共文件（pubfiles.pagasa.dost.gov.ph），政府记录
PSIC	按代码前缀或说明查询工业分类代码	PSIC 修订周期为数年	24 h	PSA Philippine Standard Industrial Classification (PSIC)，CC BY 4.0
COMELEC 2025 election results	精确到投票区的票数统计，覆盖从地区到 barangay 的层级	档案冻结于 2025-05-16 10:00:09 AM；这是固定的公开记录，并非实时数据流	24 h	公开，COMELEC 2025 election results archive
PAGASA_API_TOKEN 是唯一的环境变量，且为可选项。
PAGASA 要求通过正式申请获取该令牌。没有令牌时，预报使用
Open-Meteo。全部 41 个工具都无需令牌即可使用。

有三项数据年份值得明确说明：

• 人口数据默认读取 2024 年人口普查，并可通过 psgc_code 精确到 barangay 级别。PSA 于 2026 年调整了 OpenSTAT 上的人口普查文件夹位置，因此服务会在每次冷启动时按标题查找这些文件夹，并在每个结果中注明普查名称、参考日期和地理级别。传入 year 可选择 2010、2015 或 2020 年的数据；传入 psgc_code 可指定城市、市镇或 barangay。
• 贫困数据为 2023 全年数据。 PSA 每三年发布一次。
• 采购数据不是实时数据。 公共门户没有提供可筛选的 API，因此本服务会读取最新的约 100 条公告，并在本地进行筛选。计算每 10 万人的比率至少需要样本中有 500 条公告，因此样本量低于此门槛时，get_area_profile 会省略该数值，并在 caveats 中说明原因。

OpenSTAT 的 updated 字段记录的是服务器时钟时间，而非数据年份。请查看表格自身的时间维度；每个响应都会报告该维度。

被标记的公告只是调查起点，绝非证据

flag_infra_anomalies、summarize_infra_spending 和采购搜索结果只是调查起点，绝非不当行为的证据。每个被标记的项目都附有免责声明，且服务会指导 Agent 使用有依据的措辞。

high_cost_no_published_progress 这个名称准确描述了它实际检查的内容：公共列表没有公布任何公告的进度数据，因此这是一项费用门槛透明度标记，而非针对单个项目的进度检查。

如遇紧急情况，请使用 ndrrmc.gov.ph 以及 PHIVOLCS 和 PAGASA 官方渠道。 本项目不是生命安全系统，而是一款研究工具。

开发

git clone https://github.com/xmpuspus/ph-civic-data-mcp
cd ph-civic-data-mcp
uv sync --extra dev

# Offline tests, exactly what CI runs
uv run pytest -m "not live"

# Live tests against real upstreams; the weekly workflow runs these every Monday
uv run pytest -m live

# Lint and format check
uv run ruff check .
uv run ruff format --check .

# Build and validate
uv build
uvx twine check dist/*

CI 会在 Python 3.11、3.12、3.13 和 3.14 上运行离线测试套件，并执行 Ruff lint、Ruff format、构建，以及全新进程检查，以确认裸导入会公开全部 41 个工具。CI 操作引用固定到 commit SHA，而非浮动标签。

上文的 docker build 步骤会生成带有健康检查的非 root 镜像。 服务固定使用 fastmcp>=4.0.0,<5.0.0，当前版本为 MCP SDK 2.1.1 上的 4.0.2。

更多信息

• docs/tool-reference.md：全部 41 个工具
• CHANGELOG.md：版本发布历史
• docs/SUBMISSIONS.md：目录收录信息
• docs/fastmcp-4-evaluation.md：FastMCP 4 升级决策
• 问题和拉取请求：github.com/xmpuspus/ph-civic-data-mcp

采用 MIT 许可证。由 Xavier Puspus 构建。与 PSA、PHIVOLCS、PAGASA、PhilGEPS、DPWH、NASA、NOAA 或世界银行均无关联。