ph-civic-data-mcp

Philippine civic data as agent-callable tools. The full PSA OpenSTAT statistical catalog, PSGC location codes, infra-spending accountability, earthquakes, weather, typhoons, procurement, poverty, solar radiation, air quality, satellite vegetation, and macro indicators. Population figures reach barangay level. 41 tools, no API keys.

Philippine civic-data portals publish open data in different shapes: scraped HTML tables, PXWeb JSON, and undocumented APIs. Nothing ties them together for an agent to use. This server does, over stdio, with zero hosting cost and no API key needed. It answers questions such as how many people live in a barangay, whether a place sits near an active fault or volcano, what a city spent on flood control, and how one place compares against another.

All data comes from public records. Heuristic indicators are statistical only. A specific allegation needs independent investigation and a second source.

Install

Every client below runs the same package, uvx ph-civic-data-mcp, over stdio.

Claude Desktop. Add this to claude_desktop_config.json, which sits at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "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. Confirmed live on 2026-09-03.

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

Cursor. Add this to mcp.json:

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

VS Code. Add this to .vscode/mcp.json:

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

Docker. Build once, then run with -i for stdio:

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

The image runs as a non-root user and ships a healthcheck.

That recording is vhs docs/demo_setup.tape. It spawns Claude Code with --mcp-config pointed at this server, and Claude fans out to get_weather_forecast and get_population_stats, then correlates them. The temperatures and the population are what the live sources returned while it recorded. The population turn answers from the 2024 Census of Population (NCR: 14,001,751 as of 1 July 2024).

What can I ask?

ph-civic-data-mcp exposes 41 tools across 19 public sources. Start with get_area_profile for any place-based question. It resolves the name to a PSGC code once, then composes demographics, economy, procurement, hazards, and the 3-day outlook in a single turn, with infra notices already normalized per 100,000 residents.

Get a place at a glance

• "Give me a profile of Tacloban." get_area_profile
• "What is the PSGC code for QC?" resolve_ph_location
• "How many people live in Zamboanga City?" get_population_stats
• "What is the poverty rate in Eastern Visayas?" get_poverty_stats
• "Is it safe in Albay right now?" assess_area_risk
• "List the cities in Cebu province." list_admin_units
• "Show the full admin hierarchy above this barangay." get_location_hierarchy

Compare two or more places

• "Compare Cebu City and Davao City on population and poverty." compare_areas
• "How does Zamboanga's employment rate compare to Cagayan de Oro's?" compare_areas
• "Export a five-city comparison as a CSV file." compare_areas

Check hazards near a place

• "Any earthquakes near Legazpi in the last day?" get_latest_earthquakes
• "Read the full PHIVOLCS bulletin for that quake." get_earthquake_bulletin
• "What is Mayon's current alert level?" get_volcano_status
• "Is a typhoon active in the Philippine area right now?" get_active_typhoons
• "Cross-check that quake against the USGS global feed." get_usgs_earthquakes_ph
• "What is the river flood outlook for Cagayan de Oro this week?" get_flood_forecast
• "Which typhoons have passed near Samar since 1990?" get_historical_typhoons_ph

Search procurement and spending

• "Search every PhilGEPS notice for road repair." search_procurement
• "Search PhilGEPS for flood control projects in Pampanga." search_infra_projects
• "Summarize infra spending in Bicol for 2025." summarize_infra_spending
• "How much procurement activity is there in Region VII?" get_procurement_summary
• "Flag PhilGEPS notices in Cebu that warrant a closer look." flag_infra_anomalies
• "Pull the full notice for one flagged project." get_infra_project

Query the PSA statistical catalog

• "Find PSA tables that mention fertility." search_psa_catalog
• "Walk me through the poverty subject on OpenSTAT." browse_psa_catalog
• "What dimensions does this poverty table have?" describe_psa_dataset
• "Pull poverty incidence by island group for 2023." query_psa_dataset
• "What is the current inflation rate?" get_inflation_stats
• "What is the national unemployment rate?" get_labor_stats
• "Pull PSA health indicators for the latest year." get_health_indicators
• "What PSIC code covers rice farming?" search_psic_codes

query_psa_dataset needs an explicit value code for every dimension, refuses "all" and "*", and caps a query at 1000 cells. PSA answers a full-cube request with an HTTP 403, so describe_psa_dataset first is the only way in.

Check weather and environment

• "What is the 5-day forecast for Iloilo?" get_weather_forecast
• "Any weather alerts active in Bicol?" get_weather_alerts
• "How much solar radiation does Palawan get?" get_solar_and_climate
• "What is today's air quality in Manila?" get_air_quality
• "How has Mindanao's vegetation changed this year?" get_vegetation_index
• "List the latest PAGASA weather advisories." list_pagasa_advisory_files
• "What is the Philippine GDP per capita trend?" get_world_bank_indicator

Read the 2025 election results

• "Walk the election tree down to precincts in Adams, Ilocos Norte." browse_election_results
• "Show me the vote tally for precinct 28010001." get_election_return

The archive froze on 2025-05-16, so these two read a fixed public record. The tools retrieve and never interpret.

Track new laws and find open datasets

• "What did the Official Gazette publish this week?" get_official_gazette_feed
• "Find Philippine flood datasets on HDX." search_hdx_datasets

Every HDX dataset carries its own license. Read license_id before reuse.

Start from a prompt instead of a tool

Three MCP prompts pre-write the multi-step work, so a client can offer them as slash commands or starting points.

• area_briefing(location) composes a full place briefing.
• infra_accountability_scan(area) walks the procurement review path.
• psa_data_explorer(topic) drives the search, describe, query loop.

One tool answers questions about the server itself. get_data_freshness reports the running version, the tool count, every source with its cache window and license, per-host health, and cache ages.

Two MCP resources carry context a client can read without a tool call.

• data://ph-civic/source-catalog is the source, freshness, and license table.
• data://ph-civic/civic-framing is the language rule for accountability output.

Full signatures, arguments, and limits for all 41 tools: docs/tool-reference.md.

Get a full profile for one place

get_area_profile("Tacloban") returns the resolved identity, then reports Tacloban's own population next to the national figure, not the region's.

{
 "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": []
}

Captured live on 2026-09-03. Tacloban's own population, 259,353, replaces the Region VIII figure of about 4.6 million that an earlier version reported. Every demographic field names its own census, reference date, and geography level, so an agent never has to guess which population a number belongs to.

An outage returns an envelope, never an empty list

A list tool returns a real list on success. On upstream failure it returns an envelope instead:

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

Read that as "the source was unreachable," never as "no earthquakes" or "no notices." Failures never enter a cache, so a retry is meaningful, and a caveats entry carries the real error rather than an exception class name.

Every single-value tool sets data_status to one of five values:

upstream_error and validation_error derive from data_status, so a caller can branch on either field. get_area_profile reports one status per block in blocks and folds every failed block into caveats, so a null figure never sits beside an empty caveats list.

Every response carries source and data_retrieved_at.

Sources and freshness

The table below comes straight from SOURCE_CATALOG in server.py, through scripts/render_source_matrix.py, so it cannot drift from what the server actually reports.

PAGASA_API_TOKEN is the only environment variable, and it is optional. PAGASA gates it behind a formal request. Without it, forecasts use Open-Meteo. Every one of the 41 tools works with no token at all.

Three vintages worth stating plainly:

• Population reads the 2024 Census of Population by default, down to barangay level by psgc_code. PSA moved the census folders on OpenSTAT in 2026, so the server discovers them by title on every cold start, and names the census, reference date, and geography level in every result. Pass year for 2010, 2015, or 2020, and psgc_code for a city, municipality, or barangay.
• Poverty is 2023 Full Year. PSA publishes it every three years.
• Procurement is not real time. The public portal exposes no filterable API, so this server reads the latest ~100 notices and filters locally. A per-100,000 rate needs at least 500 notices in the sample, so get_area_profile withholds that figure below the threshold and names the reason in caveats.

The OpenSTAT updated field is server wall clock, not data vintage. Read the vintage from the table's own time dimension, which every response reports.

A flagged notice is a starting point, never evidence

flag_infra_anomalies, summarize_infra_spending, and the procurement search produce starting points for investigation, never evidence of wrongdoing. Every flagged item ships with a disclaimer, and the server instructs agents to use defensible language.

high_cost_no_published_progress is named for what it actually checks: the public listing publishes no progress data for any notice, so it is a cost-threshold transparency flag, not a per-project progress check.

For an emergency, use ndrrmc.gov.ph and the official PHIVOLCS and PAGASA channels. This is not a life-safety system but a research tool.

Development

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 runs the offline suite on Python 3.11, 3.12, 3.13, and 3.14, plus Ruff lint, Ruff format, a build, and a fresh-process check that a bare import exposes all 41 tools. CI action refs are pinned to a commit SHA, not a floating tag.

The docker build step above produces a non-root image with a healthcheck. The server pins fastmcp>=4.0.0,<5.0.0, currently 4.0.2 on MCP SDK 2.1.1.

More

• docs/tool-reference.md for all 41 tools
• CHANGELOG.md for release history
• docs/SUBMISSIONS.md for directory listings
• docs/fastmcp-4-evaluation.md for the FastMCP 4 upgrade decision
• Issues and pull requests: github.com/xmpuspus/ph-civic-data-mcp

MIT licensed. Built by Xavier Puspus. Not affiliated with PSA, PHIVOLCS, PAGASA, PhilGEPS, DPWH, NASA, NOAA, or the World Bank.