GitHub - jikime/py-mcp-ko-weather

py-mcp-ko-weather 프로젝트는 대한민국 기상청(KMA) API에 접근하여 AI 에이전트가 한국의 특정 위치에 대한 날씨 예보 정보를 검색할 수 있도록 하는 MCP(Multi-platform Communication Protocol) 서버입니다.

이 서버의 핵심 기능은 다음과 같습니다:

정확한 그리드 좌표 조회: 한국의 행정 구역(시, 구, 동)에 해당하는 기상청의 nx, ny 그리드 좌표를 조회합니다. 이는 src/migrate.py 스크립트를 통해 Excel 파일에서 SQLite 데이터베이스로 마이그레이션된 지역별 좌표 데이터베이스를 기반으로 합니다.

상세 단기 일기 예보 제공: 조회된 그리드 좌표를 사용하여 KMA의 "기상청\_단기예보 ((구)\_동네예보) 조회서비스" API를 호출하여 날씨 정보를 가져옵니다.

광범위한 지역 지원: 모든 한국의 행정 구역 단위(시/도, 시/군/구, 읍/면/동)를 지원합니다.

LLM 최적화된 응답: 대규모 언어 모델(LLM)이 쉽게 처리할 수 있도록 구조화된 텍스트 형식으로 응답을 제공합니다.

종합적인 날씨 데이터: 온도, 강수량, 하늘 상태, 습도, 풍향, 풍속 등 포괄적인 날씨 데이터를 포함합니다.

핵심 방법론 (Core Methodology):

이 MCP 서버는 AI 에이전트와 KMA API 사이의 중개자 역할을 수행합니다. 내부적으로 두 가지 주요 MCP Tool을 노출합니다:

$get_grid_location(city: str, gu: str, dong: str) -> dict$:

* 기능: 사용자가 제공한 한국의 행정 구역 정보(예: 서울특별시, 서초구, 양재1동)를 기반으로 KMA API에서 사용하는 nx 및 ny 그리드 좌표를 검색합니다.
* 기술적 세부사항: 이 Tool은 서버 내부에 구축된 데이터베이스(SQLite)를 조회하여, KMA의 그리드 시스템에 맞는 nx, ny 값을 찾아 반환합니다. 이는 KMA API가 행정 구역 이름을 직접 입력받지 않고 좌표를 요구하기 때문에 필수적인 단계입니다.

$get_forecast(city: str, gu: str, dong: str, nx: int, ny: int) -> str$:

* 기능: get_grid_location Tool을 통해 얻은 nx, ny 좌표와 함께 행정 구역 정보를 사용하여 KMA의 초단기 예보(ultra-short-term forecast) API를 호출하고, 그 결과를 구조화된 텍스트로 반환합니다.
* 기술적 세부사항: 이 Tool은 nx, ny 좌표를 KMA API 엔드포인트에 전달하여 날씨 데이터를 요청합니다. KMA API로부터 수신된 원시 JSON 데이터는 LLM이 쉽게 해석하고 활용할 수 있도록 가독성 좋은 형식(예: 온도, 습도, 풍속 등을 명확하게 레이블링한 텍스트)으로 파싱되고 포맷팅됩니다. 응답은 현재 날씨 조건과 함께 시간별 예보를 포함합니다.

MCP 설정 및 통합:

py-mcp-ko-weather 서버는 MCP 프로토콜을 통해 Claude, Cursor IDE, Google Toolbox 등과 같은 AI 플랫폼에 통합될 수 있습니다. 통합은 해당 플랫폼의 MCP 설정 파일에 서버 실행 명령어를 추가하는 방식으로 이루어집니다. 예를 들어, 로컬 환경에서 uv를 사용하거나 Docker 컨테이너를 통해 서버를 실행하도록 설정할 수 있습니다. 이를 통해 AI 에이전트는 get_grid_location 및 get_forecast Tool을 자동으로 감지하고 사용하여 한국 날씨 관련 질의에 응답할 수 있게 됩니다.

이 프로젝트는 weather://instructions와 같은 MCP Resource를 통해 사용법에 대한 상세 문서를 제공하며, Weather Query와 같은 구조화된 프롬프트 템플릿을 포함하여 LLM과의 효율적인 상호작용을 돕습니다.