korea-weather-mcp 0.1.0

MCP server for Korean weather forecasts using KMA API

대한민국 날씨 정보 MCP 서버

공공데이터포털의 기상청 초단기예보 API를 활용하여 대한민국의 실시간 날씨 정보를 제공하는 Model Context Protocol(MCP) 서버입니다.

기능

• 위도와 경도를 기반으로 한 현재 날씨 정보 제공
• 기온, 하늘상태, 강수형태, 습도, 1시간 강수량 등 상세 정보 제공

설치 방법

uvx를 사용한 간편 설치 (권장)

uvx korea-weather-mcp@latest

개발자용 설치

1. Python 3.13 이상이 필요합니다.
2. uv 패키지 매니저를 사용하여 의존성을 설치합니다:

git clone <repository-url>
cd weather
uv venv --python 3.13
uv sync

사용 방법

환경 설정

1. 공공데이터포털에 회원가입 후 기상청 초단기예보 API 키를 발급받아야 합니다.

마이페이지 -> 개인 API인증키에서 인증키 복사(Decoding)을 클릭하여 API 키를 받아옵니다.

2. 발급받은 API 키를 환경변수로 설정합니다.

방법 1: 터미널에서 직접 설정 (임시)

터미널에서 다음 명령어를 실행합니다:

export PUBLIC_DATA_API_SECRET="발급받은_API_키를_여기에_입력"

이 방법은 현재 터미널 세션에서만 유효하며, 터미널을 닫으면 설정이 사라집니다.

방법 2: 쉘 설정 파일에 영구 설정

zsh 사용자 (.zshrc):

echo 'export PUBLIC_DATA_API_SECRET="발급받은_API_키를_여기에_입력"' >> ~/.zshrc
source ~/.zshrc

bash 사용자 (.bashrc):

echo 'export PUBLIC_DATA_API_SECRET="발급받은_API_키를_여기에_입력"' >> ~/.bashrc
source ~/.bashrc

설정 후 다음 명령어로 환경변수가 제대로 설정되었는지 확인할 수 있습니다:

echo $PUBLIC_DATA_API_SECRET

Claude Desktop에서 사용하기

Claude Desktop에서 MCP 서버를 등록하고 사용할 수 있습니다:

• Claude Desktop 의 Settings 에서 Developer 섹션으로 이동
• Edit Config 를 선택하여 claude_desktop_config.json 파일을 열어서 편집합니다.

uvx 사용 (권장)

{
  "mcpServers": {
    "korea-weather-mcp": {
      "command": "uvx",
      "args": ["korea-weather-mcp@latest"],
      "env": {
        "PUBLIC_DATA_API_SECRET": "발급받은_API_키를_여기에_입력"
      }
    }
  }
}

로컬 개발 환경

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "weather.py 가 위치한 디렉토리의 절대경로 입력",
        "run",
        "weather.py"
      ],
      "env": {
        "PUBLIC_DATA_API_SECRET": "발급받은_API_키를_여기에_입력"
      }
    }
  }
}

• Claude Desktop 을 다시 시작합니다.

응답 예시

기술 스택

• Python 3.13+
• FastMCP 2.3.4+
• httpx (비동기 HTTP 클라이언트)
• uv (Python 패키지 매니저)

데이터 출처

• 기상청 초단기예보 (공공데이터포털)

PyPI 배포 방법

1. 빌드 도구 설치:

uv add --dev build twine

2. 패키지 빌드:

uv run python -m build

3. PyPI 업로드:

uv run twine upload dist/*

참고 사항

• 초단기예보는 매시간 30분에 생성되고 10분마다 최신 정보로 업데이트됩니다.
• 하늘상태(SKY) 코드: 맑음(1), 구름많음(3), 흐림(4)
• 강수형태(PTY) 코드: 없음(0), 비(1), 비/눈(2), 눈(3), 빗방울(5), 빗방울눈날림(6), 눈날림(7)