기상청 Open API를 활용한 날씨 MCP 서버를 만들어보자. (1)

Github : https://github.com/jikime/py-mcp-ko-weather

GitHub - jikime/py-mcp-ko-weather

Smithery : https://smithery.ai/server/@jikime/py-mcp-ko-weather

Korea Weather Service | Smithery

 

날씨는 우리의 일상과 떼려야 뗄 수 없는 요소입니다. 특히 한국처럼 계절 변화가 뚜렷하고 기상이 급변하는 환경에서는 실시간으로 정확한 날씨 정보를 제공하는 서비스가 큰 가치를 지닙니다.

 

이 글은 기상청_단기예보 ((구)_동네예보) 조회서비스 Open API 를 활용해 Model Context Protocol(MCP) 기반의 서버와 클라이언트를 구축하는 여정을 안내합니다.

MCP는 데이터와 모델 간의 효율적인 상호작용을 지원하는 프로토콜로, AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화 된 방법을 제공합니다. 따라서 날씨 데이터를 체계적으로 처리하고 제공하는 데 이상적입니다.

 

공공데이터포털에서 API 키를 발급받는 것부터 지역 좌표를 SQLite에 저장하고, Python으로로 MCP 서버와 클라이언트를 구현합니다.
또한, MCP 클라이언트와 Claude Desktop, Cursor AI를 활용한 테스트 방법을 통해 실제 동작을 확인하고 최적화하는 과정도 포함했습니다.

초보자부터 숙련된 개발자까지, 이 실습 중심의 가이드는 여러분의 프로젝트에 날씨 데이터를 통합하는 데 흥미와 전문성을 더할 것입니다.

지금, 데이터와 기술이 만나는 매력적인 여정을 시작해봅시다!

1. 기상청 Open API 소개 및 사용 방법

기상청_단기예보 ((구)_동네예보) 조회서비스 API는 공공데이터포털에서 제공됩니다.

• 초단기실황, 초단기예보, 단기((구)동네)예보, 예보버전 정보를 조회하는 서비스
• 초단기실황정보는 예보 구역에 대한 대표 AWS 관측값을, 초단기예보는 예보시점부터 6시간까지의 예보 제공
• 단기예보는 예보기간을 글피까지 확장 및 예보단위를 상세화(3시간→1시간)하여 시공간적으로 세분화한 예보를 제공
• 단기예보는 3일 이내, 초단기예보는 6시간 이내의 고해상도 날씨 데이터를 제공하며, 지역별 예보 조회에 활용

기상청_단기예보 ((구)_동네예보) 조회서비스 API

링크 내에서 Request 및 Response 파라미터, 개발 언어별 예제 코드도 확인할 수 있습니다.
우리는 제공되는 서비스중 초단기실황 API를 개발에 활용할 것입니다.

초단기실황조회

---

API 사용 방법

1. API 활용 신청
   위의 이미지에서 "활용신청"을 클릭하면 공공데이터포털 로그인 페이지로 이동됩니다. 만일 회원가입이 되어 있지 않다면 회원가입 후 로그인을 합니다.
   1. 기상청 단기예보 API 페이지에서 활용 신청을 진행합니다.
   2. 승인 후 발급받은 인증키를 안전하게 저장하세요. 이 키는 모든 API 요청에 필요합니다.
   3. 인증키는 마이페이지 > 데이터활용 > Open API > 인증키 발급현황에서 확인할 수 있습니다.
2. API 상세 정보
   1. 주요 요청 변수
      • serviceKey: 공공데이터포털에서 받은 인증키
      • base_date: 예보 발표 일자 (예: 20250416)
      • base_time: 예보 발표 시간 (예: 0900)
      • nx, ny: 예보 지점의 격자 좌표 (X, Y) 예) 양재1동 nx : 61, ny: 125
      • dataType: 출력 형식 (JSON 또는 XML)
      • [예시]: http://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getUltraSrtFcst?serviceKey=your_service_key&numOfRows=60&pageNo=1&dataType=json&base_date=20250416&base_time=0900&nx=61&ny=125
   2. 주요 응답 결과
      • category : 자료구분코드
      • fcstDate : 예측일자 (예: 20250416)
      • fcstTime : 예측시간 (예: 1200)
      • fcstValue : 예보 값 - 기온(TMP), 하늘 상태(SKY), 강수 형태(PTY), 강수량(RN1) 등 다양한 날씨 정보 반환
   3. 사용 가능한 코드값
      • 세부 항목은 기상청41_단기예보 조회서비스_오픈API활용가이드 를 다운로드 받고 압축을 풀면 "기상청41_단기예보 조회서비스_오픈API활용가이드_241128" 파일에서 확인 가능합니다.
        
        

---

예보지점의 격자 좌표 저장하기

기상청 API는 지역별 격자 좌표(nx, ny)를 기반으로 작동합니다. nx, ny 예보 지점의 격좌 좌표는 어떻게 알아낼 수 있을까?
기상청41_단기예보 조회서비스_오픈API활용가이드 에서 "기상청41_단기예보 조회서비스_오픈API활용가이드_격자_위경도(2411)" 파일에서 확인 가능합니다.

 

여러 항목들 중에서 실제 활용할 데이타 "1단계, 2단계, 3단계, 격자 X, 격자 Y" 만 엑셀에서 추출하여 이를 효율적으로 관리하기 위해 좌표 데이터를 SQLite 데이터베이스에 저장할 것입니다.
SQLite는 작고 빠르고, 자체적으로 독립적이며, 고유 한 고유 한 SQL 데이터베이스 엔진을 구현하는 DBMS 입니다.

 

※ 프로젝트는 맥OS 환경 및 Cursor AI 편집기에서 진행합니다.

1. 프로젝트 생성
   엑셀 데이타에서 필요한 항목만 추출하여 SQLite로 저장하기 위해 python 으로 마이그레이션 코드를 작성하려고 합니다.
   가장 먼저 프로젝트를 생성하도록 하겠습니다. 이 프로젝트는 앞으로 개발할 MCP 클라이언트 및 서버 소스도 포함될 것입니다.

프로젝트 생성을 위해 "패키지 설치 및 관리와 패키지 빌드 및 배포"까지 모두 가능한 관리 툴인 UV를 사용하도록 하겠습니다.

다음과 같은 방식으로 전역으로 uv 설치합니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

이제 터미널에서 uv 를 이용하여 python 3.12 버전으로 프로젝트를 생성합니다.

uv init -p 3.12 py-mcp-ko-weather
cd py-mcp-ko-weather

2. 가상 환경 생성

   uv venv
   source .venv/bin/activate

3. 코드 작성 및 실행
이제 코드를 작성하기 위해 프로젝트 폴더내에서 Cursor를 실행하면 아래와 같이 커서 화면이 보실 수 있습니다.

cursor .

 

편집기에서 src 폴더를 만들고 migrate.py 파일을 생성합니다. 이제 이 파일의 내용을 Cursor AI chat을 이용하여 코드를 채우겠습니다.
Chat 질문은 "data 폴더의 nxy.xlsx 엑셀 파일로부터 1단계, 2단계, 3단계, 격자 X, 격자 Y의 필드를 읽어와서 sqlite로 저장하는 마이그레이션 코드를 작성해줘" 입니다.
그러면 아래 화면처럼 AI Agent(claude-3.7-sonnect 모델)가 알아서 코드를 작성해줍니다. 혹시라도 작성중 오류가 있어도 스스로 오류를 찾아서 수정한후 최종 코드를 완료해줍니다.
작성된 코드를 확인후 Accept All을 클릭하여 적용을 합니다.

 

마지막에는 AI Agent가 친절하게도 자신이 작성한 코드에 대한 설명을 해주고 있습니다.

내용을 보니 data 폴더내에 nxy.xlsx 파일을 생성하라고 합니다. 이전에 다운로드 받았던 "기상청41_단기예보 조회서비스_오픈API활용가이드_격자_위경도(2411).xlsx" 파일의 이름을 nxy.xlsx 로 변경하여 data 폴더로 복사해 줍니다.
또한 아래 이미지의 pandas 패키지에 노란색 라인이 표시되어 있는데 이것은 현재 프로젝트내에 pandas 패키지가 설치되어 있지 않다라는 것입니다.
아래 명령어로 패키지를 설치해 줍니다. 설치후 노란색 라인이 없어진 것을 확인할 수 있습니다.

uv add pandas

 

단, 주의할 점은 사용자마다 같은 질문을 하더라도 다른 코드를 작성해 주기때문에 제 코드와 다를 수 있습니다.

 

제 github의 기상청 Open API를 활용한 날씨 MCP Server에서 코드를 확인할 수 있습니다.

Cursor AI의 챗 기능은 마치 당신의 코딩 조수와 대화하는 것과 같습니다. 예를 들어, '웹사이트 로그인 페이지를 만들어줘'라고 요청하면, Cursor AI는 프로젝트의 맥락, 사용자의 코딩 스타일, 그리고 요청의 세부 사항을 분석해 코드를 생성합니다. 하지만 같은 요청을 다른 사용자가 하면, 결과 코드가 다를 수 있습니다. 왜 그럴까요? 이는 Cursor AI가 단순히 정해진 템플릿을 뱉어내는 게 아니라, 각 사용자의 고유한 맥락을 반영하기 때문입니다.

 

폴더 구조를 보니 AI Agent가 migrate.py외에도 main.py (저장된 데이타를 가져오는 실행 파일), README.md (설치 및 사용 방법 가이드), pyproject.toml(의존성 모듈 관리) 를 새로 만들어 준것을 확인할 수 있습니다.
요구하지 않았는데도 필요한 것들을 알아서 척척 잘 만들어줍니다.

 

이제 AI Agent가 코드를 잘 만들어주었는지 migrate.py 파일을 확인해보겠습니다.
migrate_excel_to_sqlite 함수를 정의하고

• 기본 경로 설정 및 폴더 생성, 엑셀 파일이 없을 경우 오류 출력
• pandas를 이용하여 엑셀로부터 데이타 읽어와 필요한 항목 체크
• SQLite DB 접속 및 데이타를 저장할 테이블 생성
• 엑셀로부터 읽어온 데이타를 테이블에 저장
• 정상적으로 데이타가 저장되었는지 확인할 수 있는 데이타 수 구하기

전체 코드를 보면 의도대로 아주 잘 만들어주었습니다. 실제 제대로 동작이 되는지 코드를 실행해보겠습니다.

uv run src/migrate.py

 

와~ 정말 대박이네요. 오류없이 깔끔하게 실행되어 data/weather_grid.db 파일 생성과 3831개의 데이타가 입력된 것을 확인할 수 있습니다.
단, 몇 분만에 원하는 기능을 AI Agent가 오류없이 만들어 준것에 대해 놀라울 따름입니다.

마지막으로 main.py를 이용하여 내가 알고싶어하는 지역에 대해 nx, ny 값을 제대로 가져오는지 테스트 해보겠습니다.

4. 테스트 실행

   uv run main.py

 

이상 "기상청41_단기예보 조회서비스_오픈API활용가이드_격자_위경도(2411)" 엑셀 데이타를 SQLite로 마이그레이션하는 과정을 마치겠습니다.