{ "markdown": "# ph-civic-data-mcp\n\n\n\n> Philippine civic data as agent-callable tools. The full PSA OpenSTAT\n> statistical catalog, PSGC location codes, infra-spending accountability,\n> earthquakes, weather, typhoons, procurement, poverty, solar radiation, air\n> quality, satellite vegetation, and macro indicators. Population figures\n> reach barangay level. 41 tools, no API keys.\n\n[![PyPI](https://img.shields.io/pypi/v/ph-civic-data-mcp.svg)](https://pypi.org/project/ph-civic-data-mcp/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Glama AAA](https://glama.ai/mcp/servers/xmpuspus/ph-civic-data-mcp/badges/score.svg)](https://glama.ai/mcp/servers/xmpuspus/ph-civic-data-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.xmpuspus%2Fph--civic--data--mcp-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=ph-civic-data-mcp)\n\nPhilippine civic-data portals publish open data in different shapes: scraped\nHTML tables, PXWeb JSON, and undocumented APIs. Nothing ties them together for\nan agent to use. This server does, over stdio, with zero hosting cost and no\nAPI key needed. It answers questions such as how many people live in a\nbarangay, whether a place sits near an active fault or volcano, what a city\nspent on flood control, and how one place compares against another.\n\nAll data comes from public records. Heuristic indicators are statistical\nonly. A specific allegation needs independent investigation and a second\nsource.\n\n## Install\n\nEvery client below runs the same package, `uvx ph-civic-data-mcp`, over\nstdio.\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=ph-civic-data&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJwaC1jaXZpYy1kYXRhLW1jcCJdfQ==)\n[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=ph-civic-data&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22ph-civic-data-mcp%22%5D%7D)\n[![Install via Smithery](https://img.shields.io/badge/Install%20via-Smithery-blueviolet)](https://smithery.ai/server/ph-civic-data-mcp)\n[![Add via Claude Code](https://img.shields.io/badge/Add%20via-Claude%20Code-D97757?logo=anthropic)](https://code.claude.com/docs/en/mcp)\n\n**Claude Desktop.** Add this to `claude_desktop_config.json`, which sits at\n`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:\n\n```json\n{\n \"mcpServers\": {\n \"ph-civic-data\": {\n \"command\": \"uvx\",\n \"args\": [\"ph-civic-data-mcp\"]\n }\n }\n}\n```\n\n**Claude Code.**\n\n```bash\nclaude mcp add ph-civic-data -- uvx ph-civic-data-mcp\n```\n\n**Codex.** Confirmed live on 2026-09-03.\n\n```bash\ncodex mcp add ph-civic-data -- uvx ph-civic-data-mcp\n```\n\n**Cursor.** Add this to `mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ph-civic-data\": {\n \"command\": \"uvx\",\n \"args\": [\"ph-civic-data-mcp\"]\n }\n }\n}\n```\n\n**VS Code.** Add this to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"ph-civic-data\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"ph-civic-data-mcp\"]\n }\n }\n}\n```\n\n**Docker.** Build once, then run with `-i` for stdio:\n\n```bash\ndocker build -t ph-civic-data-mcp .\n```\n\nThe image runs as a non-root user and ships a healthcheck.\n\n![setup](docs/demo_setup.gif)\n\nThat recording is `vhs docs/demo_setup.tape`. It spawns Claude Code with\n`--mcp-config` pointed at this server, and Claude fans out to\n`get_weather_forecast` and `get_population_stats`, then correlates them. The\ntemperatures and the population are what the live sources returned while it\nrecorded. The population turn answers from the 2024 Census of Population\n(NCR: 14,001,751 as of 1 July 2024).\n\n## What can I ask?\n\n`ph-civic-data-mcp` exposes 41 tools across 19 public sources. Start with\n`get_area_profile` for any place-based question. It resolves the name to a\nPSGC code once, then composes demographics, economy, procurement, hazards,\nand the 3-day outlook in a single turn, with infra notices already normalized\nper 100,000 residents.\n\n### Get a place at a glance\n\n- \"Give me a profile of Tacloban.\" `get_area_profile`\n- \"What is the PSGC code for QC?\" `resolve_ph_location`\n- \"How many people live in Zamboanga City?\" `get_population_stats`\n- \"What is the poverty rate in Eastern Visayas?\" `get_poverty_stats`\n- \"Is it safe in Albay right now?\" `assess_area_risk`\n- \"List the cities in Cebu province.\" `list_admin_units`\n- \"Show the full admin hierarchy above this barangay.\" `get_location_hierarchy`\n\n### Compare two or more places\n\n- \"Compare Cebu City and Davao City on population and poverty.\" `compare_areas`\n- \"How does Zamboanga's employment rate compare to Cagayan de Oro's?\" `compare_areas`\n- \"Export a five-city comparison as a CSV file.\" `compare_areas`\n\n### Check hazards near a place\n\n- \"Any earthquakes near Legazpi in the last day?\" `get_latest_earthquakes`\n- \"Read the full PHIVOLCS bulletin for that quake.\" `get_earthquake_bulletin`\n- \"What is Mayon's current alert level?\" `get_volcano_status`\n- \"Is a typhoon active in the Philippine area right now?\" `get_active_typhoons`\n- \"Cross-check that quake against the USGS global feed.\" `get_usgs_earthquakes_ph`\n- \"What is the river flood outlook for Cagayan de Oro this week?\" `get_flood_forecast`\n- \"Which typhoons have passed near Samar since 1990?\" `get_historical_typhoons_ph`\n\n### Search procurement and spending\n\n- \"Search every PhilGEPS notice for road repair.\" `search_procurement`\n- \"Search PhilGEPS for flood control projects in Pampanga.\" `search_infra_projects`\n- \"Summarize infra spending in Bicol for 2025.\" `summarize_infra_spending`\n- \"How much procurement activity is there in Region VII?\" `get_procurement_summary`\n- \"Flag PhilGEPS notices in Cebu that warrant a closer look.\" `flag_infra_anomalies`\n- \"Pull the full notice for one flagged project.\" `get_infra_project`\n\n### Query the PSA statistical catalog\n\n- \"Find PSA tables that mention fertility.\" `search_psa_catalog`\n- \"Walk me through the poverty subject on OpenSTAT.\" `browse_psa_catalog`\n- \"What dimensions does this poverty table have?\" `describe_psa_dataset`\n- \"Pull poverty incidence by island group for 2023.\" `query_psa_dataset`\n- \"What is the current inflation rate?\" `get_inflation_stats`\n- \"What is the national unemployment rate?\" `get_labor_stats`\n- \"Pull PSA health indicators for the latest year.\" `get_health_indicators`\n- \"What PSIC code covers rice farming?\" `search_psic_codes`\n\n`query_psa_dataset` needs an explicit value code for every dimension, refuses\n`\"all\"` and `\"*\"`, and caps a query at 1000 cells. PSA answers a full-cube\nrequest with an HTTP 403, so `describe_psa_dataset` first is the only way in.\n\n### Check weather and environment\n\n- \"What is the 5-day forecast for Iloilo?\" `get_weather_forecast`\n- \"Any weather alerts active in Bicol?\" `get_weather_alerts`\n- \"How much solar radiation does Palawan get?\" `get_solar_and_climate`\n- \"What is today's air quality in Manila?\" `get_air_quality`\n- \"How has Mindanao's vegetation changed this year?\" `get_vegetation_index`\n- \"List the latest PAGASA weather advisories.\" `list_pagasa_advisory_files`\n- \"What is the Philippine GDP per capita trend?\" `get_world_bank_indicator`\n\n### Read the 2025 election results\n\n- \"Walk the election tree down to precincts in Adams, Ilocos Norte.\" `browse_election_results`\n- \"Show me the vote tally for precinct 28010001.\" `get_election_return`\n\nThe archive froze on 2025-05-16, so these two read a fixed public record.\nThe tools retrieve and never interpret.\n\n### Track new laws and find open datasets\n\n- \"What did the Official Gazette publish this week?\" `get_official_gazette_feed`\n- \"Find Philippine flood datasets on HDX.\" `search_hdx_datasets`\n\nEvery HDX dataset carries its own license. Read `license_id` before reuse.\n\n### Start from a prompt instead of a tool\n\nThree MCP prompts pre-write the multi-step work, so a client can offer them\nas slash commands or starting points.\n\n- `area_briefing(location)` composes a full place briefing.\n- `infra_accountability_scan(area)` walks the procurement review path.\n- `psa_data_explorer(topic)` drives the search, describe, query loop.\n\nOne tool answers questions about the server itself. `get_data_freshness`\nreports the running version, the tool count, every source with its cache\nwindow and license, per-host health, and cache ages.\n\nTwo MCP resources carry context a client can read without a tool call.\n\n- `data://ph-civic/source-catalog` is the source, freshness, and license table.\n- `data://ph-civic/civic-framing` is the language rule for accountability output.\n\nFull signatures, arguments, and limits for all 41 tools:\n**[docs/tool-reference.md](docs/tool-reference.md)**.\n\n## Get a full profile for one place\n\n`get_area_profile(\"Tacloban\")` returns the resolved identity, then reports\nTacloban's own population next to the national figure, not the region's.\n\n```json\n{\n \"resolved\": {\n \"name\": \"City of Tacloban\",\n \"psgc_code\": \"083747000\",\n \"level\": \"city\"\n },\n \"demographics\": {\n \"population\": 259353,\n \"population_year\": 2024,\n \"population_census\": \"2024 Census of Population\",\n \"population_reference\": \"PSA 2024 Census of Population, reference date 2024-07-01.\",\n \"population_geography_level\": \"highly_urbanized_city\",\n \"population_psgc_code\": \"0831600000\",\n \"poverty_incidence_pct\": 20.6,\n \"poverty_reference_year\": 2023\n },\n \"national_reference\": {\n \"population\": 112729484,\n \"population_year\": 2024,\n \"poverty_incidence_pct\": 10.9,\n \"poverty_year\": 2023,\n \"population_share_pct\": 0.23,\n \"poverty_gap_pct_points\": 9.7\n },\n \"blocks\": {\n \"resolve\": \"success\",\n \"population\": \"success\",\n \"poverty\": \"success\",\n \"hazard\": \"success\",\n \"weather\": \"success\",\n \"national_population\": \"success\",\n \"national_poverty\": \"success\",\n \"infra\": \"success\"\n },\n \"upstream_error\": false,\n \"caveats\": []\n}\n```\n\nCaptured live on 2026-09-03. Tacloban's own population, 259,353, replaces the\nRegion VIII figure of about 4.6 million that an earlier version reported.\nEvery demographic field names its own census, reference date, and geography\nlevel, so an agent never has to guess which population a number belongs to.\n\n## An outage returns an envelope, never an empty list\n\nA list tool returns a real list on success. On upstream failure it returns an\nenvelope instead:\n\n```json\n{ \"results\": [], \"upstream_error\": true, \"caveats\": [\"ConnectError: ...\"] }\n```\n\nRead that as \"the source was unreachable,\" never as \"no earthquakes\" or \"no\nnotices.\" Failures never enter a cache, so a retry is meaningful, and a\n`caveats` entry carries the real error rather than an exception class name.\n\nEvery single-value tool sets `data_status` to one of five values:\n\n| `data_status` | Meaning |\n|---|---|\n| `success` | The source returned a value, with its provenance. |\n| `empty` | The source answered but has no row for this request. |\n| `unavailable` | The source failed to respond, or sent an unreadable body. |\n| `indeterminate` | The source answered, but the server cannot trust the result. |\n| `invalid_request` | The caller sent a bad argument. Fix the argument named in `caveats`. |\n\n`upstream_error` and `validation_error` derive from `data_status`, so a\ncaller can branch on either field. `get_area_profile` reports one status per\nblock in `blocks` and folds every failed block into `caveats`, so a null\nfigure never sits beside an empty `caveats` list.\n\nEvery response carries `source` and `data_retrieved_at`.\n\n## Sources and freshness\n\nThe table below comes straight from `SOURCE_CATALOG` in `server.py`, through\n`scripts/render_source_matrix.py`, so it cannot drift from what the server\nactually reports.\n\n\n| Source | What it gives | Freshness | Cache TTL | License |\n|---|---|---|---|---|\n| PSGC | Place codes and names, region down to barangay | Updated when PSA publishes new PSGC version (annual or quarterly) | 24 h | Public domain (PSA Philippine Standard Geographic Code) |\n| PHIVOLCS earthquakes | Earthquake events and full bulletins | 5-minute table refresh; bulletins published per event | 5 min | Public, PHIVOLCS public bulletin pages |\n| PHIVOLCS volcanoes | Alert level and bulletin per monitored volcano | Daily bulletins per active volcano | 30 min | Public, PHIVOLCS public bulletin pages |\n| PAGASA forecast | 10-day weather forecast, with an Open-Meteo fallback | Issued twice daily; Open-Meteo updates hourly | 1 h | Open-Meteo CC-BY 4.0 / PAGASA terms |\n| PAGASA typhoons | Active typhoon bulletins and weather alerts | Bulletin every 3-6 hours when storms are active | 10 min | Public, PAGASA bulletin pages |\n| PhilGEPS notices / infra | Procurement notices, the infra subset, spending summaries | Latest ~100 bid notices, refreshed every 6h | 6 h | Public, PhilGEPS open notice listing |\n| PSA OpenSTAT | Population, poverty, CPI, labor, health, and the full statistical catalog | Per-table vintage. Population: 2024 Census of Population (reference date 2024-07-01), with 2010, 2015 and 2020 by year. Poverty: 2023. CPI/inflation: latest published month (lagged). Labor Force Survey: latest published quarter. Health (1D): per-indicator. | 24 h | PSA Open Data terms |\n| Area profile (auto-stitch) | One place profile composed live from every source below | Composed live from PSGC + PSA + PhilGEPS + PHIVOLCS + PAGASA; each block carries its own reference period | 1 h | Public, PSA OpenSTAT, PSGC, PhilGEPS, PHIVOLCS, PAGASA |\n| NASA POWER | Daily solar irradiance and climate at any point | Daily, ~3-day latency | 24 h | Public domain (NASA) |\n| Open-Meteo air quality | PM2.5, PM10, NO2, SO2, O3, CO, and AQI | Hourly | 15 min | Open-Meteo CC-BY 4.0 |\n| Open-Meteo flood forecast | Daily river discharge forecast (GloFAS model) for the nearest river cell | Daily GloFAS model run | 1 h | Open-Meteo CC-BY 4.0 |\n| NASA MODIS NDVI | NDVI and EVI vegetation indices at any point | 16-day composite, ~14-day latency | 24 h | Public domain (NASA / ORNL) |\n| USGS FDSN | Philippine-region earthquakes, cross-checked against PHIVOLCS | Real-time global feed | 10 min | Public domain (USGS) |\n| NOAA IBTrACS | Historical tropical cyclone tracks through the Philippine AOR | Annual update | 24 h | Public domain (NOAA) |\n| World Bank Open Data | Philippine macroeconomic indicators | Annual; lag varies by indicator | 24 h | World Bank Open Data CC-BY 4.0 |\n| HDX | Humanitarian dataset search, with a per-dataset license | Per-dataset metadata_modified; the catalog is searched fresh each query | 6 h | HDX (Humanitarian Data Exchange) CKAN API, per-dataset license |\n| Official Gazette RSS | Proclamations, memorandum circulars, and other government issuances | New issuances posted the same day; feed rebuilds on every request | 20 min | Public, Official Gazette government record, RA 8293 section 176 default |\n| PAGASA public files | Raw advisory, bulletin, and storm surge PDF file listing | weather_advisory updates about every 6 hours; bulletin only while a cyclone is active; stormsurge has not published since 2019-12-02 | 15 min | PAGASA public files (pubfiles.pagasa.dost.gov.ph), government record |\n| PSIC | Industrial classification code lookup, by code prefix or description | PSIC revisions change on the order of years | 24 h | PSA Philippine Standard Industrial Classification (PSIC), CC BY 4.0 |\n| COMELEC 2025 election results | Precinct-level vote tallies, region down to barangay | Archive frozen 2025-05-16 10:00:09 AM; a fixed public record, not a live feed | 24 h | Public, COMELEC 2025 election results archive |\n\n\n`PAGASA_API_TOKEN` is the only environment variable, and it is optional.\nPAGASA gates it behind a formal request. Without it, forecasts use\nOpen-Meteo. Every one of the 41 tools works with no token at all.\n\nThree vintages worth stating plainly:\n\n- **Population reads the 2024 Census of Population by default**, down to\n barangay level by `psgc_code`. PSA moved the census folders on OpenSTAT in\n 2026, so the server discovers them by title on every cold start, and names\n the census, reference date, and geography level in every result. Pass\n `year` for 2010, 2015, or 2020, and `psgc_code` for a city, municipality,\n or barangay.\n- **Poverty is 2023 Full Year.** PSA publishes it every three years.\n- **Procurement is not real time.** The public portal exposes no filterable\n API, so this server reads the latest ~100 notices and filters locally. A\n per-100,000 rate needs at least 500 notices in the sample, so\n `get_area_profile` withholds that figure below the threshold and names the\n reason in `caveats`.\n\nThe OpenSTAT `updated` field is server wall clock, not data vintage. Read the\nvintage from the table's own time dimension, which every response reports.\n\n## A flagged notice is a starting point, never evidence\n\n`flag_infra_anomalies`, `summarize_infra_spending`, and the procurement\nsearch produce starting points for investigation, never evidence of\nwrongdoing. Every flagged item ships with a disclaimer, and the server\ninstructs agents to use defensible language.\n\n`high_cost_no_published_progress` is named for what it actually checks: the\npublic listing publishes no progress data for any notice, so it is a\ncost-threshold transparency flag, not a per-project progress check.\n\n**For an emergency, use [ndrrmc.gov.ph](https://ndrrmc.gov.ph) and the\nofficial PHIVOLCS and PAGASA channels.** This is not a life-safety system but\na research tool.\n\n## Development\n\n```bash\ngit clone https://github.com/xmpuspus/ph-civic-data-mcp\ncd ph-civic-data-mcp\nuv sync --extra dev\n\n# Offline tests, exactly what CI runs\nuv run pytest -m \"not live\"\n\n# Live tests against real upstreams; the weekly workflow runs these every Monday\nuv run pytest -m live\n\n# Lint and format check\nuv run ruff check .\nuv run ruff format --check .\n\n# Build and validate\nuv build\nuvx twine check dist/*\n```\n\nCI runs the offline suite on Python 3.11, 3.12, 3.13, and 3.14, plus Ruff\nlint, Ruff format, a build, and a fresh-process check that a bare import\nexposes all 41 tools. CI action refs are pinned to a commit SHA, not a\nfloating tag.\n\nThe `docker build` step above produces a non-root image with a healthcheck.\nThe server pins `fastmcp>=4.0.0,<5.0.0`, currently 4.0.2 on MCP SDK 2.1.1.\n\n## More\n\n- **[docs/tool-reference.md](docs/tool-reference.md)** for all 41 tools\n- **[CHANGELOG.md](CHANGELOG.md)** for release history\n- **[docs/SUBMISSIONS.md](docs/SUBMISSIONS.md)** for directory listings\n- **[docs/fastmcp-4-evaluation.md](docs/fastmcp-4-evaluation.md)** for the\n FastMCP 4 upgrade decision\n- Issues and pull requests: [github.com/xmpuspus/ph-civic-data-mcp](https://github.com/xmpuspus/ph-civic-data-mcp)\n\nMIT licensed. Built by Xavier Puspus. Not affiliated with PSA, PHIVOLCS,\nPAGASA, PhilGEPS, DPWH, NASA, NOAA, or the World Bank.\n", "bytes": 19079, "sha": "39fb82b162454548827d9c7e812c7e892594ad3967dc46c5233d4804254411d5", "repo_slug": "xmpuspus/ph-civic-data-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_xmpuspus_ph_civic_data_mcp_e4b102d5/readme" }