ph-civic-data-mcp

AI 에이전트에서 필리핀 정부 데이터(지진, 날씨, 태풍, 조달, 인구, 대기질)를 제공하는 최초의 MCP 서버입니다.

ph-civic-data-mcp는 PHIVOLCS, PAGASA, PhilGEPS, PSA, AQICN/EMB의 실시간 데이터를 Claude Desktop, Claude Code, Cursor 또는 기타 MCP 호환 클라이언트가 직접 호출할 수 있는 도구로 노출하는 비용 제로의 stdio 전송 MCP 서버입니다.

데모

아래의 모든 GIF는 docs/live_demo.py의 실제 VHS 녹화본입니다. 이 스크립트는 PyPI 릴리스에서 uvx ph-civic-data-mcp를 실행하고 실제 MCP stdio 프로토콜을 통해 각 도구를 호출합니다. 화면에 보이는 패널에는 서버가 반환한 실제 JSON이 포함되어 있습니다. 연출된 것은 없습니다.

한 세션에서 5개 소스에 걸쳐 8개의 도구를 사용하는 전체 투어:

소스별 상세 설명은 아래와 같습니다. 로컬에서 재현하려면 uv run python docs/live_demo_single.py <suite>를 실행하세요.

이 프로젝트의 존재 이유

필리핀 공공 데이터 포털은 데이터를 공개하지만, 스크랩된 HTML 테이블, PXWeb JSON, 문서화되지 않은 API 등 각기 다른 스키마를 사용합니다. AI 에이전트를 위해 이들을 하나로 묶어주는 것은 없었습니다. 이 서버가 그 역할을 합니다.

2026년 4월 기준 GitHub나 PyPI에 이전 사례가 없습니다. 가장 유사한 프로젝트: panukatan/lindol (R, PHIVOLCS 전용), pagasa-parser (JS, PAGASA 전용).

설치

uvx ph-civic-data-mcp

또는 pip 사용:

pip install ph-civic-data-mcp

설정

Claude Desktop

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

.claude/settings.json에 추가:

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

또는 Claude Code CLI를 통해 설치:

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

Cursor, Zed 및 기타 MCP 클라이언트

stdio MCP 전송을 지원하는 모든 클라이언트에서 작동합니다. 명령어를 uvx ph-civic-data-mcp로 지정하고 AQICN_TOKEN을 환경 변수로 전달하세요.

질문 예시

설정 후 에이전트에게 다음과 같이 물어보세요:

• "지난 24시간 동안 필리핀에서 발생한 지진은 무엇인가요?"

• "탈 화산이 현재 활성화 상태인가요?"

• "케손시티의 3일간 날씨 예보는 어떤가요?"

• "현재 필리핀에 활성화된 태풍이 있나요?"

• "PhilGEPS에서 홍수 방지 계약을 검색해줘."

• "PSA 기준 Region VII의 인구는 얼마인가요?"

• "비콜 지역의 빈곤율은 얼마인가요?"

• "현재 마닐라의 대기질은 어떤가요?"

• "레이테 지역의 다중 재해 위험 프로필을 알려줘."

소스별 데모

PHIVOLCS — 지진 + 화산 경보 단계

PAGASA — 날씨 예보 + 태풍 추적

PhilGEPS — 조달 검색 + 집계

PSA — 인구(2020년 인구조사) + 빈곤(2023년 연간)

AQICN — 실시간 대기질

교차 소스 — 병렬 다중 재해 위험 프로필

데모 제작 방법

docs/live_demo.py와 docs/live_demo_single.py는 uvx ph-civic-data-mcp(이 PyPI 릴리스로 해석됨)를 가리키는 MCP StdioTransport를 열고, 도구를 호출하며, Rich를 사용하여 응답을 렌더링합니다(패널, 테이블, 구문 강조 JSON, 라이브 스피너). vhs는 실제 터미널을 구동하고 세션을 기록합니다. 테이프는 docs/*.tape에 커밋되어 있습니다.

데이터 소스

모든 도구

환경 변수

참고: AQICN demo 토큰은 상하이 데이터만 반환하며 필리핀 도시에서는 작동하지 않습니다. 실제 토큰을 등록해야 합니다(무료, 1분 미만).

데이터 최신성 경고

• 인구: 2020년 인구조사. 이후의 국가 데이터는 아직 존재하지 않습니다.

• 빈곤: 2023년 연간 빈곤 통계 (최신 PSA 릴리스).

• 조달: PhilGEPS 오픈 데이터는 외부에서 필터링 가능한 검색을 제공하지 않습니다. 이 서버는 최근 약 100개의 입찰 공고를 스크랩하여 클라이언트 측에서 필터링합니다. 6시간 캐시.

• 비상 상황: 실시간 재난 대응은 항상 ndrrmc.gov.ph 및 공식 PHIVOLCS/PAGASA 채널을 확인하세요. 이 서버는 연구용이며 생명 안전 결정용이 아닙니다.

아키텍처

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

• 두 개의 HTTP 클라이언트: 표준 + verify=False를 사용하는 PHIVOLCS_CLIENT (PHIVOLCS는 SSL 인증서 체인이 손상됨). SSL 검증은 전역적으로 비활성화되지 않습니다.

• 소스별 메모리 내 TTL 캐시; 디스크 쓰기 없음.

• stdio 전송 전용 (호스팅 비용 제로).

• PSA 테이블 경로는 PXWeb 브라우즈 API를 통해 발견되며 하드코딩되지 않습니다.

개발

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

제한 사항

• PAGASA 토큰은 제한적입니다. 비정부 사용자는 거부될 수 있습니다. Open-Meteo 대체 기능이 이 하드 의존성을 제거합니다.

• AQICN 토큰이 필요합니다. 무료이지만 요청해야 합니다.

• PhilGEPS는 실시간이 아닙니다. 공개 포털은 필터링 가능한 API를 노출하지 않으며, 이 서버는 클라이언트 측 필터링을 통해 최근 약 100개의 공고를 처리합니다.

• 비상 상황: 사용자에게 공식 채널을 안내하세요; 이것은 연구 도구입니다.

로드맵 (v0.2.0)

• NDRRMC 모니터링 대시보드를 통한 get_active_disasters / get_situational_report

• HazardHunterPH ArcGIS REST API를 통한 assess_hazard(lat, lng) — 좌표별 홍수/지진/산사태 위험

이전 사례

• panukatan/lindol — PHIVOLCS 지진용 R 패키지

• pagasa-parser — PAGASA 데이터 파싱용 JS 조직

둘 다 Python, 다중 소스, MCP가 아닙니다. 이 프로젝트는 두 사례 모두에 감사드립니다.

라이선스

MIT. Xavier Puspus. PHIVOLCS, PAGASA, PhilGEPS, PSA 또는 EMB와 관련이 없습니다.

기여

github.com/xmpuspus/ph-civic-data-mcp에서 이슈와 PR을 환영합니다.