ph-civic-data-mcp

Der erste MCP-Server für philippinische Regierungsdaten — Erdbeben, Wetter, Taifune, Beschaffungswesen, Bevölkerung und Luftqualität — in Ihrem KI-Agenten.

ph-civic-data-mcp ist ein kostenloser MCP-Server mit stdio-Transport, der Live-Daten von PHIVOLCS, PAGASA, PhilGEPS, PSA und AQICN/EMB als Tools bereitstellt, die von Claude Desktop, Claude Code, Cursor oder jedem anderen MCP-kompatiblen Client direkt aufgerufen werden können.

Demo

Jedes GIF unten ist eine echte VHS-Aufnahme von docs/live_demo.py — es startet uvx ph-civic-data-mcp aus diesem PyPI-Release und ruft jedes Tool über das echte MCP-stdio-Protokoll auf. Die Panels, die Sie sehen, enthalten die tatsächlichen JSON-Daten, die vom Server zurückgegeben werden. Nichts ist gestellt.

Ein Rundgang durch 8 Tools aus allen 5 Quellen in einer Sitzung:

Durchgänge pro Quelle finden Sie unten. Um sie lokal zu reproduzieren: uv run python docs/live_demo_single.py <suite>.

Warum gibt es dieses Projekt?

Philippinische Portale für Bürgerdaten veröffentlichen offene Daten, aber jedes in seinem eigenen Schema — gescrapte HTML-Tabellen, PXWeb-JSON, undokumentierte APIs. Nichts verbindet sie für einen KI-Agenten. Dieser Server tut es.

Keine Vorkenntnisse auf GitHub oder PyPI bis April 2026. Am nächsten kommen dem: panukatan/lindol (R, nur PHIVOLCS), pagasa-parser (JS, nur PAGASA).

Installation

uvx ph-civic-data-mcp

Oder via pip:

pip install ph-civic-data-mcp

Einrichtung

Claude Desktop

Hinzufügen zu ~/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

Hinzufügen zu .claude/settings.json:

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

Oder installieren via Claude Code CLI:

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

Cursor, Zed, andere MCP-Clients

Jeder Client, der den stdio-MCP-Transport unterstützt, funktioniert. Richten Sie den Befehl auf uvx ph-civic-data-mcp und übergeben Sie AQICN_TOKEN als Umgebungsvariable.

Was Sie fragen können

Fragen Sie nach der Einrichtung Ihren Agenten:

• "Welche Erdbeben haben sich in den letzten 24 Stunden auf den Philippinen ereignet?"

• "Ist der Vulkan Taal gerade aktiv?"

• "Wie ist die 3-Tage-Wettervorhersage für Quezon City?"

• "Gibt es derzeit aktive Taifune auf den Philippinen?"

• "Suche auf PhilGEPS nach Verträgen für Hochwasserschutz."

• "Wie hoch ist die Bevölkerung der Region VII laut PSA?"

• "Wie hoch ist die Armutsquote in der Region Bicol?"

• "Wie ist die Luftqualität in Manila gerade?"

• "Erstelle ein Multi-Gefahren-Risikoprofil für Leyte."

Demos pro Quelle

PHIVOLCS — Erdbeben + Vulkan-Alarmstufen

PAGASA — Wettervorhersage + Taifun-Tracking

PhilGEPS — Beschaffungssuche + Aggregation

PSA — Bevölkerung (Volkszählung 2020) + Armut (Gesamtjahr 2023)

AQICN — Echtzeit-Luftqualität

Quellenübergreifend — paralleles Multi-Gefahren-Risikoprofil

Wie die Demos erstellt werden

docs/live_demo.py + docs/live_demo_single.py öffnen einen MCP StdioTransport, der auf uvx ph-civic-data-mcp zeigt (was zu diesem PyPI-Release auflöst), rufen die Tools auf und rendern die Antworten mit Rich (Panels, Tabellen, syntax-hervorgehobenes JSON, Live-Spinner). vhs steuert ein echtes Terminal und zeichnet die Sitzung auf. Tapes sind unter docs/*.tape committet.

Datenquellen

Alle Tools

Umgebungsvariablen

Hinweis: Das AQICN demo-Token gibt nur Daten für Shanghai zurück und funktioniert nicht für philippinische Städte. Sie müssen sich für ein echtes Token registrieren (kostenlos, <1 Minute).

Warnungen zur Datenaktualität

• Bevölkerung: Volkszählung 2020. Es gibt noch keine neueren nationalen Daten.

• Armut: Armutsstatistik für das Gesamtjahr 2023 (letzte PSA-Veröffentlichung).

• Beschaffung: Die offenen Daten von PhilGEPS bieten keine extern filterbare Suche. Dieser Server scrapt die letzten ~100 Ausschreibungen und filtert clientseitig. 6 Std. gecached.

• Notfälle: Für Katastrophenhilfe in Echtzeit prüfen Sie immer ndrrmc.gov.ph und offizielle PHIVOLCS/PAGASA-Kanäle. Dieser Server dient der Forschung, nicht lebenswichtigen Entscheidungen.

Architektur

• Python 3.11+, fastmcp>=3.0.0,<4.0.0

• Zwei HTTP-Clients: Standard + PHIVOLCS_CLIENT mit verify=False (PHIVOLCS hat eine defekte SSL-Zertifikatskette). Die SSL-Verifizierung wird niemals global deaktiviert.

• In-Memory-TTL-Caches pro Quelle; keine Festplattenschreibvorgänge.

• Nur stdio-Transport (keine Hosting-Kosten).

• PSA-Tabellenpfade werden über die PXWeb-Browse-API ermittelt, niemals hartcodiert.

Entwicklung

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

Einschränkungen

• PAGASA-Token ist beschränkt. Nicht-Regierungsnutzern kann der Zugriff verweigert werden. Open-Meteo-Fallback entfernt dies als harte Abhängigkeit.

• AQICN-Token ist erforderlich. Kostenlos, muss aber angefordert werden.

• PhilGEPS ist nicht in Echtzeit. Das öffentliche Portal bietet keine filterbare API; dieser Server arbeitet mit den letzten ~100 Bekanntmachungen mit clientseitiger Filterung.

• Notfälle: Verweisen Sie Benutzer auf offizielle Kanäle; dies ist ein Forschungstool.

Roadmap (v0.2.0)

• get_active_disasters / get_situational_report via NDRRMC-Monitoring-Dashboard

• assess_hazard(lat, lng) via HazardHunterPH ArcGIS REST API — Hochwasser-/Erdbeben-/Erdrutschrisiko pro Koordinate

Frühere Arbeiten

• panukatan/lindol — R-Paket für PHIVOLCS-Erdbeben

• pagasa-parser — JS-Organisation für PAGASA-Datenparsing

Keines davon ist Python, quellenübergreifend oder MCP. Dieses Projekt würdigt beide.

Lizenz

MIT. Xavier Puspus. Nicht verbunden mit PHIVOLCS, PAGASA, PhilGEPS, PSA oder EMB.

Mitwirken

Issues und PRs sind willkommen unter github.com/xmpuspus/ph-civic-data-mcp.