ph-civic-data-mcp

<!-- mcp-name: io.github.xmpuspus/ph-civic-data-mcp -->

The first multi-source MCP server for Philippine civic data: earthquakes, weather, typhoons, procurement, population, and poverty, in your AI agent.

ph-civic-data-mcp is a zero-cost, stdio-transport MCP server that exposes live data from PHIVOLCS, PAGASA, PhilGEPS, and PSA as tools that Claude Desktop, Claude Code, Cursor, or any MCP-compatible client can call directly.

This is how easy it is to set up

One JSON file. One claude command. Your agent just correlated live Philippine weather with 2020 Census population data in a single turn.

The recording above isn't scripted. It's vhs docs/demo_setup.tape, which spawns Claude Code with --mcp-config pointing at this server, and Claude fans out in parallel to get_weather_forecast (Open-Meteo) and get_population_stats (PSA PXWeb), then correlates them. The temperatures (30.4 / 30.9 / 31.0 °C max over Apr 19-21) and NCR population (13,484,462) in the streamed answer are what the live sources returned at the moment of the recording.

Works the same way in Claude Desktop, Cursor, Zed, VS Code, or any MCP-compatible client. One "command": "uvx", one "args": ["ph-civic-data-mcp"], done.

Demo

Every GIF below is a real VHS recording of docs/live_demo.py. It spawns uvx ph-civic-data-mcp from this PyPI release and calls each tool over the real MCP stdio protocol. The panels you see contain the actual JSON returned by the server. Nothing is staged.

A grand tour hitting 7 tools across all 4 sources in one session:

Per-source walkthroughs below. To reproduce any of them locally: uv run python docs/live_demo_single.py <suite>.

Why this exists

Philippine civic-data portals publish open data, but each in its own schema — scraped HTML tables, PXWeb JSON, undocumented APIs. Nothing ties them together for an AI agent. This server does.

A handful of other Philippine civic-data MCP servers exist (PSGC administrative geography, holidays, DHSUD license-to-sell, DepEd schools), each covering one dataset. None expose hazard feeds, weather, procurement, or statistical data, and none combine sources. This server does both. See the Prior art section below for the full list.

Install

uvx ph-civic-data-mcp

Or via pip:

pip install ph-civic-data-mcp

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Claude Code

Add to .claude/settings.json:

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

Or install via the Claude Code CLI:

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

Cursor, Zed, other MCP clients

Any client that supports the stdio MCP transport works. Point the command at uvx ph-civic-data-mcp. No API keys required for the default configuration.

What you can ask

After setup, ask your agent:

• "How hot is Metro Manila this week and how many people are affected?"
• "What earthquakes happened in the Philippines in the last 24 hours?"
• "Is Taal volcano active right now?"
• "What's the 3-day weather forecast for Quezon City?"
• "Are there active typhoons in the Philippines right now?"
• "Search PhilGEPS for flood control contracts."
• "What is the population of Region VII based on the PSA?"
• "What is the poverty incidence in the Bicol Region?"
• "Give me a multi-hazard risk profile for Leyte."

Per-source demos

PHIVOLCS — earthquakes + volcano alert levels

PAGASA — weather forecast + typhoon tracking

PhilGEPS — procurement search + aggregation

PSA — population (2020 Census) + poverty (2023 Full-Year)

Cross-source — parallel multi-hazard risk profile

How the demos are produced

docs/live_demo.py and docs/live_demo_single.py open an MCP StdioTransport pointing at uvx ph-civic-data-mcp (which resolves to this PyPI release), call the tools, and render the responses with Rich (panels, tables, syntax-highlighted JSON, live spinners). vhs drives a real terminal and records the session. Tapes are committed under docs/*.tape.

Data sources

Source	Data	Update frequency	Auth
PHIVOLCS	Earthquakes, bulletins, volcano alerts	5 min (earthquakes), 30 min (volcanoes)	None
PAGASA	10-day weather, active typhoons, alerts	Hourly	Optional PAGASA_API_TOKEN
Open-Meteo	Weather fallback when PAGASA token absent	Hourly	None
PhilGEPS	Government procurement notices (latest ~100)	6 h (cached)	None
PSA OpenSTAT	Population (2020 Census), poverty (2023)	Periodic	None

All tools

Tool	Description	Key params
get_latest_earthquakes	Recent PH earthquakes	min_magnitude, limit, region
get_earthquake_bulletin	Full PHIVOLCS bulletin for one event	bulletin_url
get_volcano_status	Alert level per monitored PH volcano	volcano_name
get_weather_forecast	1–10 day forecast (PAGASA or Open-Meteo)	location, days
get_active_typhoons	Active tropical cyclones in/near PAR	—
get_weather_alerts	Active PAGASA warnings	region
search_procurement	Keyword search on PhilGEPS notices	keyword, agency, region, date_from/to, limit
get_procurement_summary	Aggregate procurement stats	agency, region, year
get_population_stats	2020 Census population	region
get_poverty_stats	2023 Full-Year poverty incidence	region
assess_area_risk	Multi-hazard profile (parallel PHIVOLCS + PAGASA)	location

Environment variables

Variable	Required	Notes
PAGASA_API_TOKEN	Optional	Requires formal PAGASA request. Without it, weather auto-falls-back to Open-Meteo.

No mandatory API keys. The server boots and all 11 tools work without any token.

Data freshness warnings

• Population: 2020 Census. No later national data exists yet.
• Poverty: 2023 Full-Year poverty statistics (latest PSA release).
• Procurement: PhilGEPS open data does not expose filterable search externally. This server scrapes the latest ~100 bid notices and filters client-side. Cached 6h.
• Emergencies: for real-time disaster response, always check ndrrmc.gov.ph and official PHIVOLCS/PAGASA channels. This server is for research, not life-safety decisions.

Architecture

• Python 3.11+, fastmcp>=3.0.0,<4.0.0
• Two HTTP clients: standard + PHIVOLCS_CLIENT with verify=False (PHIVOLCS has a broken SSL cert chain). SSL verification is never disabled globally.
• In-memory TTL caches per source; no disk writes.
• stdio transport only (zero hosting cost).
• PSA table paths are discovered via the PXWeb browse API, never hardcoded.

Development

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/*

Limitations

• PAGASA token is gated. Non-government users may be denied. Open-Meteo fallback removes this as a hard dependency.
• PhilGEPS is not real-time. Public portal exposes no filterable API; this server operates on the latest ~100 notices with client-side filtering.
• Emergencies: direct users to official channels; this is a research tool.

Roadmap (v0.2.0)

• get_active_disasters / get_situational_report via NDRRMC monitoring dashboard
• assess_hazard(lat, lng) via HazardHunterPH ArcGIS REST API — per-coordinate flood/earthquake/landslide risk

Prior art

Other Philippine civic-data MCP servers, each single-dataset:

• GodModeArch/psgc-mcp — PSA Philippine Standard Geographic Code (administrative hierarchy)
• GodModeArch/ph-holidays-mcp — Philippine national holidays from the Official Gazette
• GodModeArch/lts-mcp — DHSUD License to Sell registry
• xiaobenyang-com/Philippine-Geocoding — PSGC geocoding
• darwinphi/ph-schools-mcp-server — DepEd schools masterlist

Non-MCP libraries that inspired this project:

• panukatan/lindol — R package for PHIVOLCS earthquakes
• pagasa-parser — JS org for PAGASA data parsing

ph-civic-data-mcp is the first MCP that unifies multiple Philippine civic-data sources (PHIVOLCS, PAGASA, PhilGEPS, PSA) behind one interface, and the first to expose hazards, weather, procurement, and statistical data as MCP tools. Credit to all of the above.

License

MIT. Xavier Puspus. Not affiliated with PHIVOLCS, PAGASA, PhilGEPS, or PSA.

Contributing

Issues and PRs welcome at github.com/xmpuspus/ph-civic-data-mcp.