ph-civic-data-mcp

ph-civic-data-mcp

The first MCP server for Philippine government data — earthquakes, weather, typhoons, procurement, population, and air quality — in your AI agent.

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

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 8 tools across all 5 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.

Zero prior art on GitHub or PyPI as of April 2026. Closest: panukatan/lindol (R, PHIVOLCS only), pagasa-parser (JS, PAGASA only).

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"],
      "env": {
        "AQICN_TOKEN": "your_free_token_from_aqicn.org",
        "PAGASA_API_TOKEN": "optional_pagasa_token"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json:

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

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 and pass AQICN_TOKEN as env.

What you can ask

After setup, ask your agent:

• "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?"
• "What is the air quality in Manila right now?"
• "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)

AQICN — real-time air quality

Cross-source — parallel multi-hazard risk profile

How the demos are produced

docs/live_demo.py + 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

All tools

Environment variables

Note: the AQICN demo token only returns data for Shanghai and will not work for Philippine cities. You must register for a real token (free, <1 minute).

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.
• AQICN token is required. Free but must be requested.
• 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

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

Neither is Python, multi-source, or MCP. This project credits both.

License

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

Contributing

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