ph-civic-data-mcp

第一个用于菲律宾政府数据的 MCP 服务器——地震、天气、台风、采购、人口和空气质量——集成在你的 AI 代理中。

ph-civic-data-mcp 是一个零成本、基于 stdio 传输的 MCP 服务器，它将来自 PHIVOLCS（菲律宾火山地震研究所）、PAGASA（菲律宾大气地球物理和天文服务管理局）、PhilGEPS（菲律宾政府电子采购系统）、PSA（菲律宾统计局）和 AQICN/EMB 的实时数据作为工具公开，供 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的客户端直接调用。

演示

下方的每个 GIF 都是 docs/live_demo.py 的真实 VHS 录制——它从该 PyPI 版本启动 uvx ph-civic-data-mcp，并通过真实的 MCP stdio 协议调用每个工具。你看到的面板包含了服务器返回的实际 JSON。没有任何预设。

一次会话中涵盖所有 5 个来源的 8 个工具的全面演示：

以下是各来源的详细演示。要在本地重现其中任何一个：uv run python docs/live_demo_single.py <suite>。

为什么存在这个项目

菲律宾公民数据门户发布了开放数据，但每个门户都有自己的模式——抓取的 HTML 表格、PXWeb JSON、无文档的 API。没有任何东西能将它们整合在一起供 AI 代理使用。这个服务器做到了。

截至 2026 年 4 月，GitHub 或 PyPI 上尚无先例。最接近的项目：panukatan/lindol (R 语言，仅限 PHIVOLCS)，pagasa-parser (JS，仅限 PAGASA)。

安装

uvx ph-civic-data-mcp

或者通过 pip 安装：

pip install ph-civic-data-mcp

设置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "ph-civic-data": {
      "command": "uvx",
      "args": ["ph-civic-data-mcp"],
      "env": {
        "AQICN_TOKEN": "your_free_token_from_aqicn.org",
        "PAGASA_API_TOKEN": "optional_pagasa_token"
      }
    }
  }
}

Claude Code

添加到 .claude/settings.json：

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

或者通过 Claude Code CLI 安装：

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

Cursor、Zed 及其他 MCP 客户端

任何支持 stdio MCP 传输的客户端都可以使用。将命令指向 uvx ph-civic-data-mcp 并将 AQICN_TOKEN 作为环境变量传递。

你可以询问什么

设置完成后，询问你的代理：

• “过去 24 小时内菲律宾发生了哪些地震？”

• “塔尔火山现在活跃吗？”

• “奎松市未来 3 天的天气预报是什么？”

• “菲律宾现在有活跃的台风吗？”

• “在 PhilGEPS 中搜索防洪合同。”

• “根据 PSA，第七大区的人口是多少？”

• “比科尔大区的贫困发生率是多少？”

• “马尼拉现在的空气质量如何？”

• “给我一份莱特岛的多灾种风险概况。”

各来源演示

PHIVOLCS — 地震 + 火山警戒级别

PAGASA — 天气预报 + 台风追踪

PhilGEPS — 采购搜索 + 汇总

PSA — 人口（2020 年普查）+ 贫困（2023 年全年）

AQICN — 实时空气质量

跨来源 — 并行多灾种风险概况

演示是如何制作的

docs/live_demo.py + docs/live_demo_single.py 打开一个指向 uvx ph-civic-data-mcp（解析为该 PyPI 版本）的 MCP StdioTransport，调用工具，并使用 Rich 渲染响应（面板、表格、语法高亮的 JSON、实时加载动画）。vhs 驱动真实的终端并录制会话。磁带文件提交在 docs/*.tape 下。

数据源

所有工具

环境变量

注意：AQICN 的 demo token 仅返回上海的数据，不适用于菲律宾城市。你必须注册一个真实的 token（免费，<1 分钟）。

数据新鲜度警告

• 人口： 2020 年普查。目前尚无更新的全国数据。

• 贫困： 2023 年全年贫困统计数据（PSA 最新发布）。

• 采购： PhilGEPS 开放数据不提供外部可过滤的搜索。此服务器抓取最新的约 100 条招标公告并在客户端进行过滤。缓存 6 小时。

• 紧急情况： 对于实时灾难响应，请务必查看 ndrrmc.gov.ph 和官方 PHIVOLCS/PAGASA 渠道。此服务器仅用于研究，不用于生命安全决策。

架构

• Python 3.11+, fastmcp>=3.0.0,<4.0.0

• 两个 HTTP 客户端：标准客户端 + PHIVOLCS_CLIENT（设置 verify=False，因为 PHIVOLCS 的 SSL 证书链损坏）。SSL 验证绝不会全局禁用。

• 每个来源的内存 TTL 缓存；无磁盘写入。

• 仅 stdio 传输（零托管成本）。

• PSA 表格路径通过 PXWeb 浏览 API 发现，从不硬编码。

开发

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

# MCP Inspector
fastmcp dev src/ph_civic_data_mcp/server.py

# Tests (run against live APIs)
uv run pytest tests/ -v

# Build
uv run python -m build
uv run twine check dist/*

局限性

• PAGASA token 受限。 非政府用户可能会被拒绝。Open-Meteo 回退消除了对此的硬依赖。

• 需要 AQICN token。 免费但必须申请。

• PhilGEPS 不是实时的。 公共门户不提供可过滤的 API；此服务器基于最新的约 100 条公告进行客户端过滤。

• 紧急情况： 请引导用户使用官方渠道；这是一个研究工具。

路线图 (v0.2.0)

• 通过 NDRRMC 监控仪表板实现 get_active_disasters / get_situational_report

• 通过 HazardHunterPH ArcGIS REST API 实现 assess_hazard(lat, lng) — 基于坐标的洪水/地震/滑坡风险评估

先前工作

• panukatan/lindol — 用于 PHIVOLCS 地震的 R 包

• pagasa-parser — 用于 PAGASA 数据解析的 JS 组织

两者都不是 Python、多源或 MCP 项目。本项目向两者致敬。

许可证

MIT。Xavier Puspus。与 PHIVOLCS、PAGASA、PhilGEPS、PSA 或 EMB 无关联。

贡献

欢迎在 github.com/xmpuspus/ph-civic-data-mcp 提交问题和 PR。