# xmpuspus/ph-civic-data-mcp [Health: Active]

**Category:** 🔬 Research  
**Repository:** https://github.com/xmpuspus/ph-civic-data-mcp  
**GitHub Stars:** 5  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/xmpuspus-ph-civic-data-mcp

## Description
Philippine government data as agent-callable tools: PHIVOLCS earthquakes + volcano alerts, PAGASA weather + typhoons, PhilGEPS procurement, PSA 2020 Census population + poverty, AQICN air quality. Install: uvx ph-civic-data-mcp.

## Tools
Capabilities this server exposes over MCP:

- **get_data_freshness** — Server health + data-source catalog probe.

Doubles as the canonical version/health endpoint: returns server_version
so agents can confirm which release they are talking to. Also returns the
full upstream-source catalog with cache TTLs, freshness expectations, and
licenses — useful when deciding whether a stale cached response is OK or
a re-fetch is needed.

Returns: server_version, server_name, transport, tool_count, asof,
sources (list of {source, source_url, freshness, cache_ttl_seconds,
license}), note.
- **get_latest_earthquakes** — Get the latest earthquake events from PHIVOLCS.
- **get_earthquake_bulletin** — Get the full bulletin for a PHIVOLCS earthquake event.
- **get_volcano_status** — Get current alert level for Philippine volcanoes.
- **get_weather_forecast** — Get weather forecast for a Philippine location.

Uses PAGASA TenDay API when PAGASA_API_TOKEN is set, Open-Meteo otherwise.
- **get_active_typhoons** — Get active tropical cyclones in/near the Philippine Area of Responsibility (PAR).

Returns empty list if none active. If the PAGASA bulletin page is
unreachable, returns {results: [], upstream_error: true, caveats} instead,
so an outage is never read as "no active typhoons".
- **get_weather_alerts** — Get active PAGASA weather alerts and advisories.

The PAGASA homepage embeds alert names ("Heavy Rainfall Warning",
"Flood Advisory") in its navigation menu and breadcrumbs as well as
in actual active-warning sections. We can reliably detect the
"No Active Warnings" state but cannot yet isolate active warnings
from chrome text. To avoid fabricated advisories, this tool returns
`[]` with a caveat when the page is reachable but the state is
ambiguous, and `[]` with the explicit "no active warnings" signal
when the homepage says so. For real-time advisories, call
`bagong.pagasa.dost.gov.ph` directly.
- **search_procurement** — Search PH government procurement from PhilGEPS open data.

Note: the PhilGEPS public portal does not expose server-side search for
external clients, so this tool fetches the latest ~100 bid notices and
filters them in-memory. Data is cached 6 hours. Keyword/agency/region
filters are applied client-side (case-insensitive substring match).
- **get_procurement_summary** — Aggregate procurement statistics over the latest notices cached from PhilGEPS.
- **get_population_stats** — Philippine population from PSA OpenSTAT (2020 Census).
- **get_poverty_stats** — Poverty incidence from PSA (latest: 2023 Full-Year).
- **get_inflation_stats** — Headline consumer-price inflation (year-on-year, all items) from PSA.

Source: PSA OpenSTAT Consumer Price Index, 2018-based. The tool discovers
the current CPI series by text (never a hardcoded table id) and returns the
most recently published month's year-on-year change. Reports the exact
reference period — PSA publishes with a lag, so this is the latest available
figure, not necessarily the current month.
- **get_labor_stats** — Key labor-force indicators from the PSA Labor Force Survey.

Returns labor-force participation, employment, unemployment, and
underemployment rates for the latest published reference period. The PSA
key-indicator series is national; a `region` argument is recorded as a
caveat because this table has no regional breakdown.
- **get_health_indicators** — National health indicators from PSA OpenSTAT (subject 1D).

With no argument, returns the curated national headline set (maternal
mortality ratio and total fertility rate). Pass a free-text `indicator` to
fuzzy-match any table published under the Health subject — the available
list is browse-discovered, never hardcoded.
- **resolve_ph_location** — Fuzzy-resolve a Philippine place name to its canonical PSGC record.
- **list_admin_units** — Browse children of a PSGC node, or top-level regions when parent_code is None.
- **get_location_hierarchy** — Return the full chain region -> province -> city/municipality -> barangay
for one PSGC code.
- **search_infra_projects** — Search Philippine government infrastructure projects.

Backed by PhilGEPS open notice listing filtered for infra-related work
(construction / road / bridge / flood control / drainage / school
building / civil works). Source: https://www.philgeps.gov.ph/. Approved
budget amounts are not published in the open notice listing, so cost_php
is null in most records. The DPWH transparency portal API is currently
blocked by Cloudflare and not used.
- **get_infra_project** — Return the full record for one infrastructure project by project_id.
- **summarize_infra_spending** — Aggregate infrastructure procurement statistics over the latest PhilGEPS window.
- **assess_area_risk** — Multi-hazard risk assessment combining PHIVOLCS + PAGASA.

Makes parallel upstream calls to PHIVOLCS (earthquakes, volcano alert
levels) and PAGASA (active typhoons, weather alerts). Expect 3-6 second
response time.
- **flag_infra_anomalies** — Flag PhilGEPS infrastructure projects that warrant further review by
cross-referencing PHIVOLCS earthquakes and PAGASA typhoon footprints.

This tool emits heuristic anomaly indicators, not accusations. Every
flagged item ships with the rule that fired and a disclaimer noting that
patterns may have legitimate explanations.

Heuristic rules:
- duplicate_titles_same_agency: same agency files multiple notices with
  effectively identical titles (case-insensitive) within the window
- high_cost_no_published_progress: cost_php exceeds min_cost_php. The
  PhilGEPS open listing publishes no progress data for ANY notice, so
  this is a cost-threshold transparency flag, not a project-specific
  "progress is missing" finding.
- hazard_overlap: project location keywords overlap with a recent
  PHIVOLCS earthquake (>=M4.0 in last 30d) or an active PAGASA typhoon
  footprint, suggesting urgency or post-disaster reconstruction context
- **get_area_profile** — One-call correlated civic profile for a Philippine location.

Resolves the place once to its PSA Standard Geographic Code, then composes
demographics (population, poverty), economy (regional inflation, national
labor), procurement activity, multi-hazard risk, and the short-range
weather outlook — in a single agent turn instead of eight. Adds derived
cross-source context (e.g. infrastructure notices per 100k residents) so
the caller does not have to normalize raw counts itself.
- **get_solar_and_climate** — Daily solar irradiance + climate variables from NASA POWER for any coordinate.

Returns daily all-sky surface shortwave irradiance (kWh/m²/day), 2m temperature (°C),
corrected precipitation (mm/day), and 2m wind speed (m/s). Useful for solar energy
siting, agricultural planning, and historical climate analysis.
- **get_air_quality** — Real-time air quality for a Philippine city via Open-Meteo (no API key).

Returns PM2.5, PM10, CO, NO2, SO2, O3 plus European AQI and US AQI with
category interpretation. Covers ~80 major PH cities via local coordinate
table. For unlisted locations, caller can pass coordinates directly via
the latitude/longitude form in a future version.
- **get_vegetation_index** — NASA MODIS MOD13Q1 NDVI + EVI vegetation index at any coordinate.

NDVI (Normalized Difference Vegetation Index) ranges -1..1. Higher values
indicate denser healthy vegetation. EVI is more sensitive in high-biomass
areas. Composite period is 16 days at 250m resolution. Useful for
agricultural monitoring, deforestation tracking, drought stress indicators.
- **get_usgs_earthquakes_ph** — Philippine-region earthquakes from USGS, cross-reference to PHIVOLCS.

Returns events inside the PH bounding box (lat 4..22, lng 115..130) that
USGS has catalogued, including international-standard Mww/Mwc magnitudes
and depth solutions. Complements PHIVOLCS with global-network analysis.
- **get_historical_typhoons_ph** — Historical tropical cyclone tracks that passed through the Philippine AOR.

Sourced from NOAA IBTrACS (International Best Track Archive) — the
authoritative global archive for tropical cyclone tracks. Filtered to the
Western Pacific basin + coordinates inside the Philippine Area of
Responsibility, aggregated per storm. Returns peak intensity, minimum
pressure, and track period.
- **get_world_bank_indicator** — World Bank macroeconomic/social indicator for the Philippines.

Accepts a World Bank indicator code (e.g. 'NY.GDP.MKTP.CD') or a friendly
alias (e.g. 'gdp', 'poverty_ratio', 'inflation', 'urban_population_pct').
- **browse_psa_catalog** — List one level of the PSA OpenSTAT statistical catalog.

OpenSTAT publishes roughly 2,900 tables across 27 subjects. This walks that
tree one level at a time so an agent can find a dataset without guessing a
table id.
- **describe_psa_dataset** — Read the dimensions and valid value codes of one PSA OpenSTAT dataset.

Call this before query_psa_dataset. The query tool needs an explicit value
code for every dimension, and those codes live here.
- **query_psa_dataset** — Run one bounded query against a PSA OpenSTAT dataset.

Every dimension needs an explicit list of value codes from
describe_psa_dataset. That is a hard requirement, not a convention: PXWeb
expands an unselected dimension to all of its values, and PSA answers the
resulting full-cube request with an HTTP 403.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What xmpuspus/ph-civic-data-mcp MCP server does

The xmpuspus/ph-civic-data-mcp MCP server makes Philippine public data available as MCP tools over a local stdio process. Its coverage includes earthquakes, volcano alert levels, weather forecasts, tropical cyclones, PAGASA alerts, procurement notices, infrastructure projects, population, poverty, inflation, labor, health, administrative locations, air quality, climate, vegetation, and macroeconomic indicators.

The server is suited to questions that require combining sources rather than reading one isolated dataset. For example, `get_area_profile` resolves a place to a PSGC code and combines demographic, economic, procurement, hazard, and weather information. `assess_area_risk` combines PHIVOLCS and PAGASA results, while `flag_infra_anomalies` applies explicit heuristics to infrastructure notices and includes disclaimers that the results are review indicators, not accusations.

## How it works

The xmpuspus/ph-civic-data-mcp MCP server retrieves data from public portals and upstream feeds with different formats, including HTML pages, PSA OpenSTAT data, and public APIs. Several results are cached. Procurement searches use roughly the latest 100 PhilGEPS bid notices and filter them in memory; the stated cache period is six hours. The freshness tool reports the running version, source catalog, expected freshness, cache TTLs, licenses, and related metadata.

Location tools support fuzzy place-name resolution, browsing administrative children, and traversing a full region-to-barangay hierarchy. PSA catalog browsing helps an agent discover statistical tables instead of relying only on predefined table identifiers. Environmental tools retrieve NASA POWER climate data, NASA MODIS vegetation indices, and air-quality readings from Open-Meteo.

Some upstream behavior is handled explicitly. Weather forecasting uses the PAGASA TenDay API when `PAGASA_API_TOKEN` is set and otherwise uses Open-Meteo. Active-typhoon results distinguish an empty result from an upstream error. Weather-alert extraction returns a caveat when the PAGASA page is reachable but its warning state cannot be isolated reliably.

## Setup and configuration

Install the package with `uvx ph-civic-data-mcp` and configure the MCP client to run it over stdio. The README provides configurations for Claude Desktop, Cursor, VS Code, Claude Code, Codex, and Docker. No API key is required for the standard installation. Set `PAGASA_API_TOKEN` if the PAGASA-backed forecast path is needed; without it, the forecast tool uses Open-Meteo.

The package is published for Python 3.11 and later versions listed by the project. A Dockerfile is also provided for users who want to build and run the server in a container, using interactive stdin for the stdio transport.

## Tools and capabilities

The xmpuspus/ph-civic-data-mcp MCP server includes capabilities for:

- Reading PHIVOLCS earthquakes, bulletins, and volcano statuses.
- Checking Philippine forecasts, typhoons, and weather-alert states.
- Searching and summarizing PhilGEPS procurement and infrastructure notices.
- Retrieving PSA population, poverty, inflation, labor, and health indicators.
- Resolving PSGC locations and browsing administrative hierarchies.
- Combining local demographics, procurement, hazards, and weather in an area profile.
- Querying solar, climate, air-quality, vegetation, USGS earthquake, historical typhoon, and World Bank data.
- Browsing one level of the PSA OpenSTAT catalog.

## Limitations and notes

The xmpuspus/ph-civic-data-mcp MCP server depends on public upstream sources, so availability, publication schedules, and freshness vary. PSA values may refer to the latest published period rather than the current month. The national labor indicator series does not provide regional breakdowns; a supplied region is recorded as a caveat.

PhilGEPS open notices do not generally publish approved budget amounts or project-progress data. Consequently, `cost_php` is often null, and the high-cost anomaly rule is a threshold-based transparency flag rather than evidence that progress is missing. Hazard-overlap and duplicate-title flags also require independent review. PAGASA weather-alert parsing deliberately avoids fabricating advisories when page content is ambiguous, and the project directs users to the PAGASA site for real-time advisories.

_Full upstream README: https://allmcps.com/mcp/xmpuspus-ph-civic-data-mcp/readme_