ph-civic-data-mcp

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

One-click install:

Philippine civic-data portals publish plenty of open data, each in its own
shape: scraped HTML tables, PXWeb JSON, undocumented APIs. Nothing ties them
together for an agent. This server does, over stdio, with zero hosting cost and
no API key needed. Version 0.6.0 opens the entire PSA OpenSTAT catalog, about
2,900 statistical tables, behind three tools with hard safety limits.

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

Install

uvx ph-civic-data-mcp

Add it to any stdio MCP client:

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

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code: claude mcp add ph-civic-data -- uvx ph-civic-data-mcp
• Cursor, Zed, VS Code: the badges above, or the same JSON
• Docker: docker build -t ph-civic-data-mcp . then run with -i (non-root)

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 NCR population of 13,484,462 are what the live sources
returned while it recorded.

Start here

get_area_profile is the one to reach for first on a 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 100k residents.

32 tools across 12 public sources

PSA OpenSTAT, the whole catalog (new in 0.6.0). browse_psa_catalog,
describe_psa_dataset, query_psa_dataset. See the worked example below.

PSA curated statistics. Population (2020 Census), poverty (2023 Full Year),
CPI inflation, Labor Force Survey rates, health indicators.

Locations. PSGC resolution from free text, admin-unit browsing, full
hierarchies. Nicknames and ambiguous names both work.

Hazards. PHIVOLCS earthquakes and bulletins, volcano alert levels, USGS
cross-reference, historical typhoon tracks from NOAA IBTrACS.

Weather. PAGASA forecast with an automatic Open-Meteo fallback, active
typhoons, weather alerts.

Procurement and accountability. PhilGEPS notices, the infra subset,
spending summaries, and heuristic anomaly indicators for further review.

Science and open data. NASA POWER solar and climate, Open-Meteo air
quality, NASA MODIS vegetation indices, World Bank macro indicators.

Composites. get_area_profile and assess_area_risk.

Full signatures, arguments, and limits: docs/tool-reference.md.

Browse, describe, query: a worked example

OpenSTAT holds about 2,900 tables. Rather than guess a table id, walk to it.

browse_psa_catalog()                 -> 27 subjects, one of them {"id": "1F", "title": "Poverty"}
browse_psa_catalog("1F")             -> {"id": "FY", "title": "Full Year Poverty Statistics"}
browse_psa_catalog("1F/FY")          -> 27 datasets
describe_psa_dataset("1F/FY/0241F3DF013.px")
  -> Major Island Group (6 values), Among Families/Population (2), Year (3)
  -> total_cells: 36
query_psa_dataset("1F/FY/0241F3DF013.px", {
    "Major Island Group": ["0", "2", "5"],
    "Among Families/Population": ["0"],
    "Year": ["2"],
})
  -> PHILIPPINES 10.9, NCR 1.1, Mindanao 17.6, reference_period "2023"

Run live on 2026-08-06. The psa_data_explorer prompt drives this sequence for
an agent.

Four limits make a generic query tool safe to hand an agent:

1. The tool rebuilds every path under the OpenSTAT base. A scheme, a host, a
   query string, a fragment, .., or an odd character never reaches the wire.
2. Every dimension needs explicit value codes. PXWeb expands an unnamed
   dimension to all of its values, and PSA answers that with an HTTP 403.
3. The tool refuses "all" and "*" for the same reason.
4. The tool computes the cell product before the request, and caps it at 1000.

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.

The three OpenSTAT catalog tools add validation_error: true for a rejected
argument. Fix the argument the message names; retrying will not help.

Every response carries source and data_retrieved_at.

Data sources and freshness

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 32 tools works with no token at all.

Three vintages worth stating plainly:

• Population is 2020 Census. No later national count exists.
• 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.

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.

Flagged notices are starting points, 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 --locked --extra dev

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

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

# The MCP Inspector, and a static report of the surface
fastmcp dev inspector src/ph_civic_data_mcp/server.py
fastmcp inspect src/ph_civic_data_mcp/server.py

# 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
32 tools.

Architecture notes: Python 3.11+, fastmcp>=3.0.0,<4.0.0, stdio only,
in-memory TTL caches and no disk writes, and two HTTP clients. The second one
exists because PHIVOLCS serves a broken certificate chain. This server never
disables TLS verification globally or for any other host.

Related projects

Other Philippine civic-data MCP servers cover a single dataset each: PSGC
administrative geography, holidays, DHSUD license-to-sell, DepEd schools. None
of them expose hazard feeds, weather, procurement, or statistical data, and
none compose across sources.

More

• docs/tool-reference.md for all 32 tools
• CHANGELOG.md for release history
• docs/SUBMISSIONS.md for directory listings
• 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.