ph-civic-data-mcp

El primer servidor MCP para datos del gobierno de Filipinas — terremotos, clima, tifones, adquisiciones, población y calidad del aire — en tu agente de IA.

ph-civic-data-mcp es un servidor MCP de transporte stdio sin costo que expone datos en vivo de PHIVOLCS, PAGASA, PhilGEPS, PSA y AQICN/EMB como herramientas que Claude Desktop, Claude Code, Cursor o cualquier cliente compatible con MCP pueden llamar directamente.

Demo

Cada GIF a continuación es una grabación VHS real de docs/live_demo.py: inicia uvx ph-civic-data-mcp desde esta versión de PyPI y llama a cada herramienta a través del protocolo real MCP stdio. Los paneles que ves contienen el JSON real devuelto por el servidor. Nada está preparado.

Un recorrido completo que utiliza 8 herramientas de las 5 fuentes en una sola sesión:

Tutoriales por fuente a continuación. Para reproducir cualquiera de ellos localmente: uv run python docs/live_demo_single.py <suite>.

Por qué existe esto

Los portales de datos cívicos de Filipinas publican datos abiertos, pero cada uno con su propio esquema: tablas HTML extraídas, JSON de PXWeb, APIs sin documentar. Nada los une para un agente de IA. Este servidor lo hace.

Cero antecedentes en GitHub o PyPI hasta abril de 2026. Lo más cercano: panukatan/lindol (R, solo PHIVOLCS), pagasa-parser (JS, solo PAGASA).

Instalación

uvx ph-civic-data-mcp

O mediante pip:

pip install ph-civic-data-mcp

Configuración

Claude Desktop

Añadir a ~/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

Añadir a .claude/settings.json:

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

O instalar mediante la CLI de Claude Code:

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

Cursor, Zed, otros clientes MCP

Cualquier cliente que admita el transporte MCP stdio funciona. Apunta el comando a uvx ph-civic-data-mcp y pasa AQICN_TOKEN como variable de entorno.

Qué puedes preguntar

Después de la configuración, pregúntale a tu agente:

• "¿Qué terremotos ocurrieron en Filipinas en las últimas 24 horas?"

• "¿Está activo el volcán Taal en este momento?"

• "¿Cuál es el pronóstico del tiempo para 3 días en Quezon City?"

• "¿Hay tifones activos en Filipinas en este momento?"

• "Busca en PhilGEPS contratos de control de inundaciones."

• "¿Cuál es la población de la Región VII según la PSA?"

• "¿Cuál es la incidencia de pobreza en la Región de Bicol?"

• "¿Cuál es la calidad del aire en Manila en este momento?"

• "Dame un perfil de riesgo multiamenaza para Leyte."

Demos por fuente

PHIVOLCS — terremotos + niveles de alerta volcánica

PAGASA — pronóstico del tiempo + seguimiento de tifones

PhilGEPS — búsqueda de adquisiciones + agregación

PSA — población (Censo 2020) + pobreza (Año completo 2023)

AQICN — calidad del aire en tiempo real

Fuente cruzada — perfil de riesgo multiamenaza paralelo

Cómo se producen las demos

docs/live_demo.py + docs/live_demo_single.py abren un StdioTransport de MCP apuntando a uvx ph-civic-data-mcp (que se resuelve en esta versión de PyPI), llaman a las herramientas y renderizan las respuestas con Rich (paneles, tablas, JSON con resaltado de sintaxis, spinners en vivo). vhs controla una terminal real y graba la sesión. Las cintas se confirman bajo docs/*.tape.

Fuentes de datos

Todas las herramientas

Variables de entorno

Nota: el token demo de AQICN solo devuelve datos para Shanghái y no funcionará para ciudades filipinas. Debes registrarte para obtener un token real (gratis, <1 minuto).

Advertencias sobre la frescura de los datos

• Población: Censo 2020. Aún no existen datos nacionales posteriores.

• Pobreza: Estadísticas de pobreza del año completo 2023 (última publicación de la PSA).

• Adquisiciones: Los datos abiertos de PhilGEPS no exponen una búsqueda filtrable externamente. Este servidor extrae los últimos ~100 avisos de licitación y filtra del lado del cliente. Caché de 6h.

• Emergencias: para respuesta a desastres en tiempo real, consulta siempre ndrrmc.gov.ph y los canales oficiales de PHIVOLCS/PAGASA. Este servidor es para investigación, no para decisiones de seguridad vital.

Arquitectura

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

• Dos clientes HTTP: estándar + PHIVOLCS_CLIENT con verify=False (PHIVOLCS tiene una cadena de certificados SSL rota). La verificación SSL nunca se deshabilita globalmente.

• Cachés TTL en memoria por fuente; sin escrituras en disco.

• Solo transporte stdio (costo de alojamiento cero).

• Las rutas de las tablas de la PSA se descubren a través de la API de navegación PXWeb, nunca codificadas de forma rígida.

Desarrollo

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

Limitaciones

• El token de PAGASA está restringido. A los usuarios no gubernamentales se les puede denegar. La alternativa de Open-Meteo elimina esto como una dependencia estricta.

• Se requiere token de AQICN. Gratis pero debe solicitarse.

• PhilGEPS no es en tiempo real. El portal público no expone una API filtrable; este servidor opera con los últimos ~100 avisos con filtrado del lado del cliente.

• Emergencias: dirige a los usuarios a los canales oficiales; esta es una herramienta de investigación.

Hoja de ruta (v0.2.0)

• get_active_disasters / get_situational_report a través del tablero de monitoreo de NDRRMC

• assess_hazard(lat, lng) a través de la API REST de ArcGIS de HazardHunterPH — riesgo de inundación/terremoto/deslizamiento de tierra por coordenada

Antecedentes

• panukatan/lindol — Paquete R para terremotos de PHIVOLCS

• pagasa-parser — Organización JS para el análisis de datos de PAGASA

Ninguno es Python, multifuente o MCP. Este proyecto reconoce a ambos.

Licencia

MIT. Xavier Puspus. No afiliado a PHIVOLCS, PAGASA, PhilGEPS, PSA o EMB.

Contribución

Las incidencias y PR son bienvenidos en github.com/xmpuspus/ph-civic-data-mcp.